Grid Toolkit glossary
When a tutorial names an unfamiliar object or boundary, use the table below. The terms describe different responsibilities; keeping them separate makes actions, saving, and rendering easier to reason about.
| Term | Plain-language meaning |
|---|---|
| Board definition | A GridBoardDefinition: the frozen description of which cells exist and which topology they use. It answers “what may exist?” |
| Board state | A GridBoardState: the live data for one board, including cells, structures, occupancy, extensions, revision, and observers. It owns that internal runtime data, while a component or project system owns the state object's lifetime. It answers “what exists now?” |
| Board asset | An editable Unity asset that builds a board definition. |
| Setup asset | An authored recipe that combines a board asset, optional structure library, initial placements, and runtime configuration. |
| Authoring | Creating and configuring a board through Unity assets and GridBoardAuthoring. It produces the same kind of runtime state as code-owned construction. |
| Code-owned board | A board whose state is created, retained, and disposed by project code. This is an optional ownership model, not a separate topology or extension point. |
| Topology | The logical rules for valid coordinates, neighbors, distance, directions, footprints, and orientations. |
| Coordinate | A GridCoordinate: a topology-specific logical value such as square (x, y). It is not a world-space position. |
| Address | A GridAddress: a topology ID paired with a compatible coordinate. It is a stable logical dictionary key, not a board-instance identity. |
| Orientation | A topology-defined logical rotation or facing used to transform footprints. |
| Layout | The presentation rule that converts logical coordinates into world-space or Canvas poses, shapes, and hits. |
| Cell | One logical location in a board definition and its corresponding live cell state. |
| Structure definition | The reusable description of a placeable object, including its stable definition ID, topology, layer, and footprint. |
| Structure instance | One placed structure with its own instance ID, anchor, orientation, occupied cells, and runtime extensions. |
| Footprint | The topology-relative cell offsets covered by a structure. |
| Layer | A logical occupancy category. Policies decide whether structures in particular layers may coexist. |
| Occupancy | The board-owned indexes that connect placed structure instances to every cell they cover. |
| Policy | A rule evaluated while an action or restoration is planned. It accepts or rejects a request but does not own descriptive data or mutable board state. |
| Action | A description of an intended runtime change, such as placing a structure or adding a cell. |
| Action plan | A GridActionPlan: validated mutations and events built against one board revision. A retained plan may become stale before it is applied. |
| Preview | A complete validation of an action that does not mutate state, advance revision, or publish committed events. |
| Atomic transaction | An all-or-nothing change: every validated mutation commits together, or the board stays unchanged. |
| Revision | A monotonically increasing board-state version. A mutating commit advances it once; an event-only commit does not. Every successful snapshot restoration advances it once, including an identical restore. |
| Committed event batch | The facts published to observers after one board has completed an atomic commit. |
| State source | A component or service that provides the current board state and reports when another state replaces it. |
| Read-only state view | An IGridBoardStateView: live access to board data without mutation authority. It follows its state owner and is not an independent copy. |
| Board view | A component that watches board state and tells the renderer which visuals need refreshing. |
| Renderer | The part that creates, keeps, updates, and removes the actual World 2D, World 3D, uGUI, or project-owned visuals. |
| Renderer capability | A named kind of content or behavior that a renderer supports. Views and modules use capabilities to reject incompatible visual combinations before rendering. |
| Hit | A logical GridHit returned from a renderer or layout query. Game code decides whether it means hover, selection, placement, or another interaction. |
| Retained visualization | Visual objects are kept and updated when needed instead of being rebuilt every frame. |
| Invalidation | The technical name for identifying which visuals need refreshing. |
| Visual intent | Transient presentation state such as a hover or selection highlight. It does not mutate the board or advance revision. |
| Snapshot | Independent, versioned data used to save or transfer a definition and runtime state. |
| Resolver | A service that translates stable IDs or extension payloads while building, saving, or restoring state. |
| Extension | Project-owned data or behavior added through a supported Grid Toolkit contract. |
| Definition extension | Immutable descriptive project data cloned, validated, and frozen with a board, cell, or structure definition. |
| Runtime extension | Mutable board-owned project data changed through actions and exposed through an independent read-only value or copy. |
| Detached read model | An independent read-only value or copy for observation. Unlike a live state view, it does not follow later board changes or expose the board's mutable storage. |
| Diagnostic | Reason or error details that explain why an operation failed or a setup is not ready. |
| Contract | A supported public API or extension interface that project code may depend on. |
Important distinctions
| Pair | First term | Second term |
|---|---|---|
| Definition / state | A definition is frozen input that answers which topology, cells, and descriptive data exist. | State is the owned runtime data that answers what exists now and carries the revision. Policies make decisions separately. |
| Topology / layout | Topology defines logical coordinates, neighbors, distance, and valid orientation. | Layout converts those logical values into Unity poses, shapes, and hit regions. |
| Action / transaction | An action describes the requested change and can be previewed. | An atomic transaction applies the whole validated change or none of it. |
| View / renderer | A view watches state and decides what needs refreshing. | A renderer creates, updates, and removes the concrete World 2D, World 3D, or uGUI visuals. |
| Coordinate / address | A coordinate is one topology-specific logical value. | An address pairs a topology ID with a compatible coordinate; neither identifies a particular board instance. |
The shortest useful model
A board asset builds a definition. A board owner uses the setup to create live state. Actions change that state atomically. A board view observes committed state and asks a renderer to present it.