Customize board data and rules
Grid Toolkit separates descriptive data, live data, and decisions. Keeping those jobs separate makes ownership, saving, previews, and tests easier to reason about.
Store project data safely
Choose the extension by when its data changes:
- A definition extension stores immutable data that describes a board, cell, or structure definition.
- A runtime extension stores mutable data owned by a live board, cell, or placed structure.
In both cases, the receiving owner stores its own copy. Callers receive an independent read-only value—called a detached read model—rather than access to mutable storage.
For example, a turn counter can be stored as a board-state extension. Gameplay can read its current value, while an action replaces or updates the board-owned value. If the counter is saved, a snapshot resolver translates it to and from independent save data.
Change board decisions with policies
Use a policy when a placement, occupancy write, coexistence decision, or restoration must be accepted or rejected. Policies inspect the supplied context and return a decision; they do not mutate the board or update visuals.
GridRuntimeConfiguration collects the policies, snapshot resolvers, and structure-ID provider used by one board. Create that configuration once so preview, apply, restoration, and tests all use the same rules.
| Need | Use | Board ownership |
|---|---|---|
| Describe a board, cell, or structure definition | Definition extension | The frozen definition stores a private copy and exposes an independent read model. |
| Store a value that changes during play | Runtime extension | The live board stores a private copy and exposes an independent read model. |
| Save or restore extension data | Snapshot resolver | Save data stays independent of live state. |
| Accept or reject a requested change | Placement, admission, or coexistence policy | The configuration owns an ordered copy of the policy set. |
| Generate omitted structure instance IDs | Structure-ID provider | The configuration supplies the service used during planning. |
Rules to preserve
- Give extensions, payload formats, policies, and providers stable IDs.
- Make owned copies when mutable data enters a board or configuration.
- Return safe read-only values to consumers.
- Keep policy ordering explicit and deterministic.
- Apply mutations through actions so accepted changes remain all-or-nothing.
- Keep scene objects and renderer state outside runtime extensions and policies.