IntermediateValidated 1.0.0

Learn the extension pattern with Cell Metadata

When to use

Cell Metadata is an optional, Preview-tier module included with Grid Toolkit. Its blocked, locked, tag, and region values are useful gameplay data. The tag workflow below shows how Grid Toolkit extension roles fit together without cataloging every built-in variation.

Use the same pattern for project-owned data rather than depending on Cell Metadata for unrelated domain concepts.

Before you start

Start with an authored board that is ready at revision 0. In the board asset, select one cell and add a Tags definition extension containing walkable. Runtime code should use GridCellMetadataQueries instead of depending on the extension's storage details.

Procedure

Follow the extension roles

Role in this example	Grid Toolkit responsibility	Continue with
Authored `walkable` tag	Immutable definition extension	Store project data in definitions
Runtime tag override	Mutable board-owned extension	Runtime extensions and detached read models
Add-tag request	Action and atomic transaction	Create a custom action and event
Optional placement rule	Policy that reads metadata and makes a decision	Placement, admission, and coexistence policies
Snapshot payload	Resolver-owned persistence	Snapshot resolvers and restore policies
Cell decoration	Renderer module reading committed state	Renderer modules, invalidation, capabilities, and visual intents

Definition data supplies the initial value. A runtime extension can replace that value without modifying the asset. Queries expose the effective read-only value, and policies decide whether the value should affect a particular action.

For example, a placement policy can ask whether the tag query marks a cell as walkable. The Cell Metadata resolver can preserve that tag in a snapshot, while the renderer decorates the same committed value without owning or changing it.

Read the authored value

Excerpt — read one effective tag value. Tested using public APIs.

public static bool ReadTag(
    IGridBoardStateView state,
    GridCoordinate coordinate,
    string tag)
{
    return GridCellMetadataQueries.HasTag(state, coordinate, tag);
}

Preview and apply a runtime change

Excerpt — preview one tag action without mutation. Tested using public APIs.

public static GridActionResult PreviewAddTag(
    GridBoardState state,
    GridCoordinate coordinate,
    string tag)
{
    IGridAction action = new GridAddCellTagAction(coordinate, tag);
    return GridActionRunner.Preview(state, action);
}

Excerpt — apply the accepted action and read the committed value. Tested using public APIs.

public static GridActionResult ApplyAddTag(
    GridBoardState state,
    GridCoordinate coordinate,
    string tag)
{
    return GridActionRunner.Apply(
        state,
        new GridAddCellTagAction(coordinate, tag));
}

Add a policy only when the tag should influence admission or placement. Add the matching resolver only when snapshots must preserve it. Add GridCellMetadataRenderer only when the value should decorate retained cells. None of those roles is implied merely because the data exists.

Blocked, locked, region, and other tag operations follow the same ownership flow. Use the Cell Metadata API reference for their exact types and members.

Result

The authored walkable value is readable at revision 0. Previewing a spawn tag changes neither state nor event batches. Applying it advances the board once, publishes one committed batch, and makes the new effective value visible to queries, policies, persistence, and presentation.

Troubleshooting

Symptom	Check
A value exists but placement ignores it	Metadata stores information; register the policy that should make the decision.
A runtime value is lost after restore	Register the resolver that owns that extension and payload.
A renderer changes but gameplay does not	Presentation is read-only; query committed metadata and apply a logical action.

Table of Contents