70 lines
2.8 KiB
Markdown
70 lines
2.8 KiB
Markdown
# Cult Runtime Surface
|
|
|
|
Aquarium uses CultLib directly for runtime identity and reload recovery.
|
|
|
|
## State Store
|
|
|
|
`AquariumCultStateStore` opens a `SingleFileMessagePackBackingStore` and attaches
|
|
it to a `CultCache`. The dev scripts pass:
|
|
|
|
```powershell
|
|
--cache E:\Projects\Aquarium-Engine\artifacts\dev-reload\cultcache\aquarium-client.msgpack
|
|
```
|
|
|
|
Direct runs can also use `--cache <path>` or `AQUARIUM_CULTCACHE_PATH`.
|
|
If the single-file MessagePack snapshot is unreadable at startup, Aquarium
|
|
quarantines it beside the live file with a `.corrupt-<timestamp>` suffix and
|
|
boots a fresh typed state. Schema guardrails protect valid persisted documents
|
|
whose shape has changed; they cannot rescue a truncated backing file with no
|
|
complete MessagePack envelope.
|
|
|
|
CultLib's single-file backing store writes snapshots through a same-directory
|
|
temporary file and atomic replace. That prevents process death during save from
|
|
turning the live cache path into a zero-byte startup trap.
|
|
|
|
## Live State
|
|
|
|
`AquariumLiveState` is a CultCache document:
|
|
|
|
- schema name: `epiphany.aquarium.live_state`
|
|
- schema version: `epiphany.aquarium.live_state.v0`
|
|
- record key: `aquarium-client/live-state`
|
|
- name: `aquarium-client`
|
|
|
|
It currently stores the camera target, yaw, pitch, distance, runtime time, and a
|
|
monotonic save generation. `AquariumRuntime` writes it every 0.2 seconds and
|
|
again during orderly shutdown.
|
|
|
|
## Graphics Settings
|
|
|
|
`AquariumGraphicsSettingsState` is a CultCache document:
|
|
|
|
- schema name: `epiphany.aquarium.graphics_settings`
|
|
- schema version: `epiphany.aquarium.graphics_settings.v0`
|
|
- record key: `aquarium-client/graphics-settings`
|
|
- name: `aquarium-client-graphics`
|
|
|
|
It stores global renderer presentation controls: render debug mode, scene
|
|
exposure, bloom intensity, and bloom veil intensity. `GraphicsSettings` lives in
|
|
the contracts assembly so the native host and renderer can consume the same
|
|
typed values without depending on CultCache internals. The Direct2D debug panel
|
|
edits the renderer copy, the host syncs changed values back to the client runtime,
|
|
and the runtime persists dirty graphics settings through the same CultCache file
|
|
used for live state.
|
|
|
|
Live reload flushes the current runtime before loading the next client assembly,
|
|
so changed graphics settings survive both process restart and assembly reload.
|
|
|
|
## CultNet Surface
|
|
|
|
The runtime creates a `CultNetHelloMessage` from the local CultCache registry.
|
|
That gives the engine a concrete CultNet identity and a schema catalog surface
|
|
before transport work starts:
|
|
|
|
- runtime kind: `aquarium-engine`
|
|
- role: `visual-client`
|
|
- display name: `Epiphany Aquarium`
|
|
- supported document types: taken from `CultDocumentRegistry.AllDescriptors`
|
|
|
|
Transport is still the next layer. The important thing for reload is already
|
|
true: live state is a typed Cult document backed by CultLib MessagePack storage.
|