Document canonical CultMesh access rules
This commit is contained in:
parent
19c354ed9b
commit
8a76e4f9fb
9 changed files with 317 additions and 89 deletions
|
|
@ -1,10 +1,11 @@
|
|||
# Aetheria Verse Client Contract
|
||||
|
||||
Aetheria clients should enter the runtime through CultMesh typed state, not through
|
||||
daemon internals. The daemon owns simulation authority and publishes daemon state
|
||||
as Verse records. Unity, tools, test harnesses, and later non-Unity clients open
|
||||
the same state store with the same runtime document registry and read/write typed
|
||||
documents through CultNet.
|
||||
daemon internals. The daemon owns simulation authority over canonical shared
|
||||
documents; it does not own a separate private truth that is then copied into
|
||||
client state. Unity, tools, test harnesses, and later non-Unity clients open the
|
||||
same state store with the same runtime document registry and read/write the same
|
||||
typed documents through CultMesh/CultNet according to authority policy.
|
||||
|
||||
The ergonomic contract is stricter than "typed records are available
|
||||
somewhere." A client must be able to ask CultMesh for the domain state it wants
|
||||
|
|
@ -14,6 +15,14 @@ through daemon frames, projected rows, record keys, schema slots, state refs,
|
|||
renderer-local facade indexes, or transport route decisions to reconstruct one
|
||||
gameplay value.
|
||||
|
||||
The default implementation contract is one canonical document type per gameplay
|
||||
state concept. If `AetheriaRuntimeFooDocument` is the gameplay state, that is
|
||||
the document the daemon mutates/publishes and the document clients receive from
|
||||
the shared assembly. A separate projected document exists only when the shape is
|
||||
intentionally different: hidden-info filtering, expensive aggregation, viewport
|
||||
windowing, SoA/native layout, lossy UI summaries, surface documents, or a named
|
||||
compatibility bridge. "The client needs to see it" is not a projection reason.
|
||||
|
||||
The shared entrypoint is `AetheriaRuntimeVerseClient` in the runtime state
|
||||
package. It opens a local `CultMeshNode` with the runtime-only Aetheria contract
|
||||
registry and exposes:
|
||||
|
|
@ -55,11 +64,11 @@ handles:
|
|||
using var verse = await AetheriaRuntimeVerseClient.OpenAsync(statePath, "tool-client");
|
||||
var aetheria = verse.Aetheria();
|
||||
|
||||
using var inventory = aetheria.Current.Inventory.Watch(RenderInventory);
|
||||
using var docking = aetheria.Current.Docking.Watch(RenderDocking);
|
||||
using var dockingBay = aetheria.Current.DockingBay.Watch(RenderDockingBay);
|
||||
using var inventory = aetheria.State.Reactive<AetheriaRuntimeInventoryDocument>(entityIndex);
|
||||
using var docking = aetheria.State.Reactive<AetheriaRuntimeCurrentDockingDocument>();
|
||||
using var support = aetheria.State.Reactive<AetheriaRuntimeStationSupportDocument>();
|
||||
|
||||
var stationRefit = await aetheria.Station.Refit.LatestAsync();
|
||||
var stationRefit = await aetheria.State.LatestAsync<AetheriaRuntimeStationRefitDocument>();
|
||||
var visibleObjects = await aetheria.Zone(currentZoneId)
|
||||
.Objects
|
||||
.VisibleToCurrentPlayer()
|
||||
|
|
@ -73,6 +82,13 @@ Verse, bind an Eve state pointer, or expose a native slab view. That decision is
|
|||
CultMesh infrastructure. The caller gets a typed domain value and diagnostics
|
||||
when it asks for them.
|
||||
|
||||
Client input follows the same rule. When a runtime has authority or prediction
|
||||
rights, mutating the managed typed document is the ergonomic target; CultMesh
|
||||
debounces, routes, records the prediction, and reconciles against canonical
|
||||
state. When a runtime does not have direct write authority, it submits a typed
|
||||
operation handle that the daemon validates and applies to the same canonical
|
||||
document.
|
||||
|
||||
Unity should treat the client as its Aetheria-facing runtime surface. It can
|
||||
still use Burst, DOTS rendering, and native views for presentation, but the state
|
||||
authority boundary is the typed CultMesh contract. No Unity-facing code should
|
||||
|
|
|
|||
|
|
@ -5,13 +5,15 @@ Date: 2026-06-28
|
|||
This guide describes the target developer experience for adding Aetheria state
|
||||
with CultMesh. If the workflow grows into a chain of facades, sessions,
|
||||
projectors, adapters, and surface builders, stop and simplify the state API.
|
||||
That chain is heretek now: it means the feature is compensating for a missing
|
||||
typed document, query, operation, pointer, native view, or generated handle.
|
||||
|
||||
The rule is blunt:
|
||||
|
||||
```text
|
||||
small UI-only value: derive it inline from already accessible typed state
|
||||
named UI-only projection: define the projected document, then read it
|
||||
simulation feature: define simulation state, publish typed state, consume it
|
||||
simulation feature: define one canonical typed document, let daemon authority mutate it, consume the same document everywhere
|
||||
hot rendering/physics: use SoA, not object-graph UI documents
|
||||
```
|
||||
|
||||
|
|
@ -19,6 +21,36 @@ CultMesh owns document identity, sync, prediction, reconciliation, and reactive
|
|||
access. Aetheria code should read like it is using game state, not walking
|
||||
protocol layers.
|
||||
|
||||
## Canonical Document Rule
|
||||
|
||||
The default shape is one shared typed document contract.
|
||||
|
||||
```text
|
||||
AetheriaRuntimeFooDocument
|
||||
-> daemon authority mutates/publishes it
|
||||
-> Unity/Electron/tools read the same document type
|
||||
-> authorized clients write intent or predictions through the managed handle
|
||||
```
|
||||
|
||||
Do not split a feature into "daemon truth" and a separate "CultMesh typed
|
||||
state" unless the second shape is intentionally different. The assembly is
|
||||
shared, so the document the daemon owns is also the document clients receive.
|
||||
Across runtimes, callers should feel like they are grabbing a handle on typed
|
||||
state and either reading it for display or writing to it for client input.
|
||||
|
||||
A second document is justified only when it earns a distinct job:
|
||||
|
||||
- hidden-information filtering;
|
||||
- expensive or shared derived state;
|
||||
- viewport/windowed selection;
|
||||
- SoA/native render or physics layout;
|
||||
- lossy presentation summaries;
|
||||
- UI surface documents;
|
||||
- compatibility mirrors with a named removal stage.
|
||||
|
||||
Projection is not the normal way to make state client-visible. Projection is an
|
||||
exception for a different shape.
|
||||
|
||||
## The Ergonomic Bar
|
||||
|
||||
UI-only state should take one or two steps.
|
||||
|
|
@ -27,7 +59,7 @@ Use one step when the value is small and already derivable from state the caller
|
|||
has:
|
||||
|
||||
```csharp
|
||||
var currentDocking = client.State.Current.ReactiveDocking();
|
||||
var currentDocking = client.State.Reactive<AetheriaRuntimeCurrentDockingDocument>();
|
||||
var bayName = currentDocking.Current?.DockingBayName ?? "";
|
||||
```
|
||||
|
||||
|
|
@ -35,16 +67,16 @@ Use two steps when the projection is shared, non-trivial, or should have a
|
|||
stable schema:
|
||||
|
||||
```text
|
||||
1. Define the daemon-projected typed document.
|
||||
1. Define the typed projected document.
|
||||
2. Read it from Unity as a managed reactive typed document.
|
||||
```
|
||||
|
||||
Simulation state should take two or three steps:
|
||||
|
||||
```text
|
||||
1. Put the simulation data and rules in the daemon-owned domain model.
|
||||
2. Publish the useful client-facing shape as typed CultMesh state.
|
||||
3. Read that state from Unity and send typed operations back when input mutates truth.
|
||||
1. Define the canonical typed document in the shared runtime package.
|
||||
2. Let the daemon mutate/publish that document as the authority for the Verse.
|
||||
3. Read or modify the same managed document from clients according to authority policy.
|
||||
```
|
||||
|
||||
Anything beyond that needs a clear reason. Performance-sensitive entity
|
||||
|
|
@ -86,7 +118,11 @@ daemon document -> session -> facade -> projector -> adapter -> surface builder
|
|||
```
|
||||
|
||||
That shape preserves reconstruction-era scaffolding. It does not express the
|
||||
game.
|
||||
game. At most, one boundary adapter may exist at an actual boundary: Unity
|
||||
GameObject presentation, Eve/CultUI lowering, legacy import, persistence, or
|
||||
native view ownership. If two or more layers appear in a row just to obtain one
|
||||
domain value, stop and move the missing primitive into CultMesh/CultLib or the
|
||||
generated Aetheria handle surface.
|
||||
|
||||
## Choosing The State Shape
|
||||
|
||||
|
|
@ -105,18 +141,21 @@ Use a projected typed document when:
|
|||
- the result needs a stable schema or cross-runtime binding;
|
||||
- the projection should update reactively as daemon state changes.
|
||||
|
||||
Use daemon-owned simulation state when:
|
||||
Use a canonical simulation document when:
|
||||
|
||||
- the value affects game rules;
|
||||
- input can mutate it;
|
||||
- it needs authority, replay, persistence, or reconciliation;
|
||||
- the daemon must validate operations before publishing the next state.
|
||||
|
||||
Use a projected typed document when the caller needs a different state shape,
|
||||
not merely because a client needs to see daemon-owned state.
|
||||
|
||||
Use SoA/native views when:
|
||||
|
||||
- Unity jobs, Burst, Ymir, or rendering need large columnar data;
|
||||
- row count and per-frame access make object graphs the wrong format;
|
||||
- the data is a hot view over daemon truth rather than a UI document.
|
||||
- the data is a hot view over canonical simulation state rather than a UI document.
|
||||
|
||||
## One-Step UI Derivation
|
||||
|
||||
|
|
@ -140,7 +179,8 @@ public sealed class DockingBadge : IDisposable
|
|||
{
|
||||
get
|
||||
{
|
||||
_docking ??= _client.State.Current.ReactiveDocking();
|
||||
_docking ??= _client.State
|
||||
.Reactive<AetheriaRuntimeCurrentDockingDocument>();
|
||||
var current = _docking.Current;
|
||||
return current?.IsDocked == true ? current.DockingBayName : "";
|
||||
}
|
||||
|
|
@ -162,6 +202,11 @@ document.
|
|||
Use this for shared presentation state such as player HUD, docking summary,
|
||||
commander wave status, station service summary, or Starbridge support alerts.
|
||||
|
||||
Before adding this projection, ask whether the UI can read the canonical
|
||||
simulation document directly. If it can, do that. The projection exists only
|
||||
when the UI shape is genuinely derived, filtered, windowed, or shared enough to
|
||||
deserve its own schema.
|
||||
|
||||
### Step 1: Define The Projected Document
|
||||
|
||||
Put the document type in the shared runtime package so every runtime sees the
|
||||
|
|
@ -195,20 +240,17 @@ public sealed class AetheriaRuntimeZoneDefenseStatusDocument
|
|||
}
|
||||
```
|
||||
|
||||
Then expose it as a named projection from `AetheriaClientState`:
|
||||
Then make it available through generic managed state access:
|
||||
|
||||
```csharp
|
||||
public CultMeshReactiveDocument<AetheriaRuntimeZoneDefenseStatusDocument>
|
||||
ReactiveZoneDefenseStatus()
|
||||
{
|
||||
return Mesh.Reactive<AetheriaRuntimeZoneDefenseStatusDocument>(
|
||||
AetheriaRuntimeDaemonDocuments.ZoneDefenseStatus);
|
||||
}
|
||||
using var status =
|
||||
client.State.Reactive<AetheriaRuntimeZoneDefenseStatusDocument>();
|
||||
```
|
||||
|
||||
The exact registration/publishing code belongs in the runtime plumbing. It
|
||||
should be generated or centralized. The feature author should not have to write
|
||||
five separate access classes for one projected state shape.
|
||||
five separate access classes, wrapper methods, sessions, or facades for one
|
||||
projected state shape.
|
||||
|
||||
### Step 2: Read It From Unity
|
||||
|
||||
|
|
@ -230,7 +272,8 @@ public sealed class ZoneDefenseHud : IDisposable
|
|||
|
||||
public void Refresh()
|
||||
{
|
||||
_status ??= _client.State.ReactiveZoneDefenseStatus();
|
||||
_status ??= _client.State
|
||||
.Reactive<AetheriaRuntimeZoneDefenseStatusDocument>();
|
||||
var status = _status.Current;
|
||||
if (status == null)
|
||||
return;
|
||||
|
|
@ -256,25 +299,10 @@ Use this when the feature changes gameplay: heat support, repair drones,
|
|||
station construction, scenario progression, commander infrastructure, or wave
|
||||
director state.
|
||||
|
||||
### Step 1: Put Truth In The Daemon
|
||||
### Step 1: Define The Canonical Document
|
||||
|
||||
Simulation truth lives with the daemon domain model and tick/apply logic.
|
||||
|
||||
```csharp
|
||||
public sealed class StationSupportState
|
||||
{
|
||||
public double CoolingReserve { get; set; }
|
||||
public double RepairNaniteReserve { get; set; }
|
||||
public int ActiveSupportDrones { get; set; }
|
||||
}
|
||||
```
|
||||
|
||||
The daemon mutates this state during ticks and command application. Unity does
|
||||
not own gameplay truth.
|
||||
|
||||
### Step 2: Publish Typed CultMesh State
|
||||
|
||||
Expose the client-facing shape as a typed document.
|
||||
Simulation truth is the shared typed document. The daemon owns authority over
|
||||
that document, but the document contract is not daemon-private.
|
||||
|
||||
```csharp
|
||||
[MessagePackObject]
|
||||
|
|
@ -292,21 +320,26 @@ public sealed class AetheriaRuntimeStationSupportDocument
|
|||
}
|
||||
```
|
||||
|
||||
The daemon publishes this document from its current truth. CultMesh handles sync.
|
||||
If the client has prediction authority, local changes to the managed document
|
||||
are predictions; reconciliation corrects them without requiring feature code to
|
||||
### Step 2: Let The Daemon Own Authority
|
||||
|
||||
The daemon validates operations, applies ticks, and publishes the canonical
|
||||
document into the Verse. Unity does not own gameplay truth, but Unity does not
|
||||
need a separate client-facing copy either. CultMesh handles sync. If the client
|
||||
has prediction authority, local changes to the managed document are
|
||||
predictions; reconciliation corrects them without requiring feature code to
|
||||
manually shuttle deltas.
|
||||
|
||||
### Step 3: Read State And Submit Typed Operations
|
||||
### Step 3: Read Or Mutate Through The Managed Handle
|
||||
|
||||
Unity reads state through the managed typed document:
|
||||
Unity reads the same document through the managed typed handle:
|
||||
|
||||
```csharp
|
||||
var support = client.State.ReactiveStationSupport();
|
||||
var support = client.State.Reactive<AetheriaRuntimeStationSupportDocument>();
|
||||
var cooling = support.Current?.CoolingReserve ?? 0;
|
||||
```
|
||||
|
||||
Unity asks the daemon to mutate truth through a typed operation:
|
||||
When the client does not have direct simulation authority, it submits a typed
|
||||
operation:
|
||||
|
||||
```csharp
|
||||
client.Operations.Submit(new AetheriaRuntimeDeploySupportDroneOperation
|
||||
|
|
@ -320,6 +353,11 @@ client.Operations.Submit(new AetheriaRuntimeDeploySupportDroneOperation
|
|||
The daemon validates and applies the operation. The next published document is
|
||||
the authoritative result.
|
||||
|
||||
When the client has prediction or simulation authority, the ergonomic target is
|
||||
even simpler: modifying the managed reactive document records a prediction,
|
||||
debounced by the update frame, and CultMesh routes/reconciles it according to
|
||||
the Verse authority policy.
|
||||
|
||||
## SoA For Hot Paths
|
||||
|
||||
Use SoA when Unity needs fast columnar access, not when a UI needs a label.
|
||||
|
|
@ -340,9 +378,9 @@ Bad SoA candidates:
|
|||
- player settings;
|
||||
- station service summary.
|
||||
|
||||
SoA should be a named high-performance view over daemon truth. It should not
|
||||
force ordinary presentation code to understand frame slabs, column handles, or
|
||||
native buffer ownership.
|
||||
SoA should be a named high-performance view over canonical simulation state. It
|
||||
should not force ordinary presentation code to understand frame slabs, column
|
||||
handles, or native buffer ownership.
|
||||
|
||||
## Reconnection
|
||||
|
||||
|
|
@ -373,13 +411,13 @@ For projected UI documents, test:
|
|||
- projection from representative daemon state;
|
||||
- empty/default state;
|
||||
- reactive update after source state changes;
|
||||
- Unity caller reads the projected document directly.
|
||||
- Unity caller reads the typed document directly.
|
||||
|
||||
For simulation features, test:
|
||||
|
||||
- daemon tick/application mutates truth;
|
||||
- daemon tick/application mutates the canonical typed document;
|
||||
- typed operation validation accepts and rejects correctly;
|
||||
- published document reflects daemon truth;
|
||||
- clients read the same shared document type the daemon publishes;
|
||||
- prediction/reconciliation behavior when the runtime supports local authority;
|
||||
- reconnect can reconstruct the required player state.
|
||||
|
||||
|
|
@ -401,8 +439,9 @@ Good verifier expectations:
|
|||
```text
|
||||
Unity caller owns CultMeshReactiveDocument<TDocument>
|
||||
Unity caller reads .Current
|
||||
Unity caller uses client.State.ReactiveFeatureName()
|
||||
Unity caller uses client.State.Reactive<TDocument>()
|
||||
Unity caller submits typed operations for mutations
|
||||
authorized caller mutates managed typed state as prediction/input
|
||||
hot renderer uses named SoA view
|
||||
```
|
||||
|
||||
|
|
@ -413,6 +452,7 @@ Unity caller owns AetheriaRuntime*Session for one document
|
|||
Unity caller calls ObserveFeatureName() wrapper only to read Current
|
||||
UI caller reads raw daemon frames and joins rows
|
||||
feature adds facade/projector/adapter/surface-builder chain
|
||||
feature introduces multiple translation layers to get one typed value
|
||||
```
|
||||
|
||||
The verifier should make the codebase harder to regress into ceremony, not
|
||||
|
|
@ -425,8 +465,8 @@ Before calling a CultMesh feature ergonomic, answer these questions:
|
|||
- Can a UI-only inline value be implemented in one local derivation?
|
||||
- Can a shared UI projection be implemented by defining the document and reading
|
||||
it from Unity?
|
||||
- Can a simulation feature be explained as daemon truth, typed state, typed
|
||||
operation?
|
||||
- Can a simulation feature be explained as one canonical typed document plus
|
||||
authority policy and typed operations?
|
||||
- Does Unity code read domain state instead of protocol plumbing?
|
||||
- Is SoA reserved for hot paths?
|
||||
- Did the verifier protect the clean path instead of the old wrappers?
|
||||
|
|
|
|||
|
|
@ -10,8 +10,9 @@ ambushed by half-finished architecture.
|
|||
The short version: Unity is being reduced to a renderer, input surface, and
|
||||
editor environment. Durable game state and portable gameplay facts now live in
|
||||
typed CultCache/CultNet/CultMesh records under `Aetheria.State`. The daemon is
|
||||
the simulation owner. Unity and the Electron RTS client are clients of the same
|
||||
typed Verse state.
|
||||
the authority over canonical shared documents, not a private truth source that
|
||||
exports a second client copy. Unity and the Electron RTS client are clients of
|
||||
the same typed Verse state.
|
||||
|
||||
## Start Here
|
||||
|
||||
|
|
@ -29,8 +30,9 @@ Read these in this order:
|
|||
5. `docs/aetheria-verse-client-contract.md`
|
||||
Intended client contract: use typed Verse state, not daemon internals.
|
||||
6. `docs/cultmesh-feature-implementation-guide.md`
|
||||
Step-by-step guide for adding daemon-owned typed state, publishing it through
|
||||
CultMesh, and consuming/interacting with it from Unity.
|
||||
Step-by-step guide for adding canonical typed state once, letting daemon
|
||||
authority own mutation, and consuming/interacting with the same document from
|
||||
Unity and other clients.
|
||||
7. `Aetheria.State/docs/verse-authority-implementation-plan.md`
|
||||
Authority and Starbridge staged implementation map.
|
||||
|
||||
|
|
@ -186,8 +188,12 @@ Expected recurring warnings:
|
|||
|
||||
### State Owner
|
||||
|
||||
Typed CultCache/CultNet/CultMesh documents are the state owner. The primary
|
||||
world file is:
|
||||
Typed CultCache/CultNet/CultMesh documents are the state owner. For normal
|
||||
gameplay features, define one canonical shared document and let authority policy
|
||||
decide who may write or predict it. Do not create "daemon truth" plus a separate
|
||||
client-facing copy unless the second document is intentionally filtered,
|
||||
aggregated, windowed, lossy, SoA/native, or a named compatibility bridge. The
|
||||
primary world file is:
|
||||
|
||||
```text
|
||||
GameData/aetheria-world.cc
|
||||
|
|
@ -220,14 +226,15 @@ Use `AetheriaClient` first:
|
|||
Packages/org.gamecult.aetheria.state/Runtime/AetheriaClient.cs
|
||||
```
|
||||
|
||||
It exposes named reads such as current entity, current docking, station/refit,
|
||||
sector map, viewport, Starbridge summary, health, authority policy, and SoA
|
||||
views. It also exposes typed controls through `AetheriaControl` and typed UI
|
||||
surface helpers through `AetheriaUi`.
|
||||
It exposes generic managed document reads such as `State.Latest<TDocument>()`
|
||||
and `State.Reactive<TDocument>()`, parameterized handles for viewport/detail
|
||||
documents, Starbridge seat handles, typed controls through `AetheriaControl`,
|
||||
and typed UI surface helpers through `AetheriaUi`.
|
||||
|
||||
If a Unity panel or Electron surface needs a fact, prefer adding or extending a
|
||||
named facade read. Avoid handing callers raw daemon frames unless the caller is
|
||||
a transitional projection layer.
|
||||
If a Unity panel or Electron surface needs a fact, prefer the generic managed
|
||||
document call first. Add a named facade only when it carries semantic identity,
|
||||
parameters, operation policy, or a distinct derived/native shape. Avoid handing
|
||||
callers raw daemon frames unless the caller is a transitional projection layer.
|
||||
|
||||
### Unity Shell
|
||||
|
||||
|
|
@ -373,6 +380,12 @@ Work on Ymir/physics:
|
|||
Git preserves history. The migration should delete dead shims when the typed
|
||||
replacement exists and tests prove it.
|
||||
|
||||
8. Treat facade/projector/adapter/surface-builder chains as a design failure.
|
||||
One adapter at a true boundary is fine. Stacked translation layers used to
|
||||
recover one typed value mean the code is missing a CultMesh primitive,
|
||||
generated handle, canonical document, query, operation, pointer, or native
|
||||
view.
|
||||
|
||||
## Known Transitional Debt
|
||||
|
||||
These are not surprises; they are known pressure points.
|
||||
|
|
@ -407,9 +420,13 @@ Use this checklist before writing code:
|
|||
Add or extend a MessagePack/CultNet document in the runtime package. Use
|
||||
explicit `[Key]` slots and stable names.
|
||||
|
||||
3. Add a facade read or operation.
|
||||
Prefer `AetheriaClient`, `AetheriaControl`, or `AetheriaUi` over direct
|
||||
low-level Verse calls in client code.
|
||||
3. Add the simplest access path.
|
||||
Prefer `AetheriaClient.State.Latest<TDocument>()` or
|
||||
`AetheriaClient.State.Reactive<TDocument>()` for canonical documents. Add a
|
||||
named handle only when type alone cannot identify the document, such as
|
||||
parameterized viewport/detail state or multiple documents sharing one CLR
|
||||
type. Use `AetheriaControl` or `AetheriaUi` for typed operations and UI
|
||||
commands.
|
||||
|
||||
4. Lower Unity and Electron through the same semantics.
|
||||
Unity and RTS do not need identical UI, but they should observe the same
|
||||
|
|
@ -498,8 +515,9 @@ The useful way to look at it is:
|
|||
When in doubt, follow the typed state:
|
||||
|
||||
```text
|
||||
document -> facade -> client presentation
|
||||
command document -> daemon apply -> projected result
|
||||
canonical document -> managed CultMesh handle -> client presentation/input
|
||||
typed operation -> daemon authority -> same canonical document
|
||||
projection/native view -> only when the shape is intentionally different
|
||||
```
|
||||
|
||||
If a path does not fit that shape, it is probably transitional debt or a bug.
|
||||
|
|
|
|||
Loading…
Reference in a new issue