Definitions and state
A definition is the frozen recipe for a board; a state contains the live board data that changes during play. A component or project system owns the state object's lifetime.
What each one owns
A definition answers “what may exist?” A state answers “what exists now?”
| Value | What it owns |
|---|---|
| GridBoardDefinition | Topology, cell definitions, and board-level definition extensions. |
| GridStructureDefinition | A reusable structure's topology, footprint, occupancy layer, and definition extensions. |
| GridBoardState | Live cells, placed structures, occupancy, runtime extensions, configuration, revision, and observers. |
The component or project system that creates a board state retains it for as long as it is needed and disposes it when that lifetime ends.
From an asset to live state
The first-board wizard creates First Board Board.asset. That asset builds a definition containing
64 square cells. At Play Mode startup, GridBoardAuthoring uses the setup to create one board
state. Placing a structure changes the state to revision 1; it does not rewrite the board asset or
definition.
Rules that keep ownership safe
- Building a state freezes its definition.
- State-owned mutable values are cloned on entry.
- Public collections are read-only views; extension reads return independent read-only values.
- Initialization through builders starts at revision
0. - Runtime changes go through actions and publish only after commit.
- Disposing the state releases its owned data and subscriptions.
Read-only state views
Choose the narrowest live view that a consumer needs:
- IGridBoardStateView observes one live board without granting mutation ownership. Its IGridCellStateView, IGridOccupancyView, and IGridStructureView expose focused parts of that current state.
- IGridBoardStateSource lets observers follow a component or service that may replace the entire state object.
These views stay connected to the current owner; they are not independent copies. Definition-extension and runtime-extension read models are independent read-only values or copies. They cannot expose the board's mutable storage or follow later changes automatically.
How a board becomes observable state
flowchart LR
accTitle: Definition and board state construction
accDescr: A builder or authoring asset creates a frozen definition, which combines with runtime configuration to build owned mutable state exposed through live read-only views and independent extension read models.
A["Builder or authoring asset"] --> B["Frozen definition"]
B --> C["State builder"]
D["Runtime configuration"] --> C
C --> E["Owned mutable state"]
E --> F["Read-only state view"]
E --> G["Independent extension read models"]
What remains separate
Definitions do not carry scene objects or current occupancy. States do not own renderer objects. Snapshots are independent data for storage or transfer, not live state.