83 lines
3.9 KiB
Markdown
83 lines
3.9 KiB
Markdown
# Engine And Client Boundary
|
|
|
|
Aquarium Engine is not the Epiphany frontend client.
|
|
|
|
`Aquarium.Engine` owns the native machinery: Win32 windowing, D3D12 device
|
|
state, swapchain presentation, resource lifetime, shader compilation, reload
|
|
transport, input translation, render target allocation, and future render graph
|
|
execution.
|
|
|
|
`Aquarium.Engine.Contracts` owns the Vortice-free public boundary clients use to
|
|
describe runtime state, render intent, UI, audio patches, and persistent
|
|
settings. Contracts may name reusable engine concepts. They may not smuggle
|
|
Epiphany policy into the host under a nicer namespace.
|
|
|
|
`Aquarium.Epiphany` owns the client meaning: CultCache runtime state, CultNet
|
|
interpretation, camera intent, cursor semantics, agent visual state, diegetic
|
|
layout rules, and the render graph configuration that turns Epiphany state into
|
|
world pixels.
|
|
|
|
`Aquarium.Sample.Minimal` exists as the tiny smoke test. `Aquarium.Zyphos`
|
|
exists as the first real non-Epiphany demo: a planetary client with its own
|
|
runtime, controls, scene state, and SDF shaders. If a feature cannot be
|
|
explained without Epiphany or Zyphos, it is not engine API yet.
|
|
|
|
## Hard Rules
|
|
|
|
- Engine code may expose rendering abstractions. It may not know Epiphany roles,
|
|
sub-agent identities, CultNet surface semantics, or frontend-specific layout
|
|
policy.
|
|
- Epiphany code may configure cameras, render targets, shader passes, body
|
|
registries, and resource bindings through engine APIs. It may not reach into
|
|
D3D12 implementation details.
|
|
- Hot reload is transport. It is not architecture. The reload boundary exists so
|
|
the client can change without killing the device, not so client policy can
|
|
leak into the engine under a nicer hat.
|
|
- If a feature name includes `Self`, `Face`, `Imagination`, `Eyes`, `Body`,
|
|
`Hands`, `Soul`, `Life`, `CultNet`, or Epiphany state semantics, the default
|
|
home is `Aquarium.Epiphany` unless it is a data-only contract.
|
|
- If a feature owns descriptors, command lists, fences, barriers, render target
|
|
transitions, shader object lifetime, or swapchain presentation, the default
|
|
home is `Aquarium.Engine`.
|
|
|
|
## Next Engine API Shape
|
|
|
|
The next durable renderer cut should make the client configure a small set of
|
|
engine primitives:
|
|
|
|
- Render targets: format, dimensions, history policy, clear policy, and exported
|
|
handles.
|
|
- Cameras: view/projection data, previous-frame data, jitter policy, and named
|
|
consumers.
|
|
- Shader passes: shader module, root bindings, target outputs, depth policy,
|
|
dispatch/draw shape, and reload identity.
|
|
- Scene resources: structured buffers, textures, samplers, body registries, and
|
|
light registries behind typed handles.
|
|
- Frame graph edges: explicit read/write dependencies so pass ordering is data,
|
|
not hidden renderer folklore.
|
|
|
|
Do not build this by piling adapters around the current monolith. First expose
|
|
the smallest real engine abstraction that lets `Aquarium.Epiphany` describe one
|
|
pass without D3D12 details. Then move one client-owned concept through it. Then
|
|
repeat.
|
|
|
|
## Repository Split Line
|
|
|
|
Aquarium should eventually be usable without carrying the Epiphany client in the
|
|
same repository. That does not mean the repo should be split before the boundary
|
|
is mechanically clean.
|
|
|
|
Keep both in this repo while the public contracts, graph declarations, shader
|
|
include layout, reload transport, and sample-client path are still changing
|
|
together. Split Epiphany out only when:
|
|
|
|
- `Aquarium.Engine` and `Aquarium.Engine.Contracts` contain no Epiphany role,
|
|
CultNet-surface, Grid-policy, or agent-layout semantics.
|
|
- A non-Epiphany client can declare cameras, targets, shaders, UI, and
|
|
presentation without referencing `Aquarium.Epiphany`.
|
|
- Epiphany shaders, state documents, and visual grammar live entirely on the
|
|
client side of the contracts.
|
|
- The host can load an external client assembly without repo-local path lore.
|
|
|
|
Until those are true, a repo split would not simplify ownership. It would just
|
|
make the same leak harder to see.
|