Choose a built-in action
When to use
Choose a built-in action before creating project-owned mutation code. Use the narrowest request that describes the complete logical change, then preview it before applying input that can fail.
An IGridAction is a request object. It has no string action ID. Its runtime type identifies the request, while GridActionResult describes success, affected cells, and diagnostics.
Before you start
Start with a ready board state.
The GridActionRunner Preview method builds a
plan without mutating state, reserving cells, advancing revision, or publishing a batch.
Apply(state, action) plans again against current state; applying an existing plan may reject it
when it has become stale.
Procedure
Built-in Grid Toolkit actions — Stable
| Action or entry point | Choose it when | State and affected cells | Revision and committed events |
|---|---|---|---|
GridActions.PlaceStructure(...) |
Add one structure instance. | Adds occupancy for the resolved footprint. | Advances once; publishes GridStructurePlacedEvent. |
GridActions.MoveStructure(...) |
Move or reorient an instance. | Replaces anchor, orientation, and previous/next occupancy. | Advances once; publishes GridStructureChangedEvent. |
GridActions.RemoveStructure(...) |
Remove an instance by instance ID. | Removes the instance and all occupancy. | Advances once; publishes GridStructureRemovedEvent. |
GridActions.AddCell(...) |
Add one runtime cell. | Adds the coordinate and optional initial extensions. | Advances once; publishes GridCellAddedEvent. |
GridActions.RemoveCell(...) |
Remove one runtime cell. | Removes the cell and optionally its occupants. | Advances once; publishes GridCellRemovedEvent and any occupant-removal events. |
| GridSetStructureExtensionAction | Replace mutable project data on one instance. | Replaces one runtime extension. | Advances once; publishes GridStructureChangedEvent. |
| GridBatchAction | Same-board requests must commit together. | Combines child plans and affected cells. | Advances once when mutated; publishes child events in one batch. |
GridActionRunner.ApplySnapshot(...) |
Atomically restore complete saved state. | Reconciles the whole board. | Every successful restore advances once and publishes GridBoardRestoredEvent. |
Factory-created place, move, remove, add-cell, and remove-cell actions are returned through
GridActions. Call
GridActionRunner.BuildRestorePlan when restoration must be inspected before commit.
Cell Metadata actions — Preview
Cell Metadata uses these one-cell actions:
| Request | Change |
|---|---|
| GridAddCellTagAction | Add one tag. |
| GridRemoveCellTagAction | Remove one tag. |
| GridSetCellBlockedAction | Set the blocked value. |
| GridSetCellLockedAction | Set the locked value. |
| GridSetCellRegionAction | Set the region value. |
Each real change advances once and publishes GridCellChangedEvent; a request that produces no
mutation or event does neither.
See Learn the extension pattern with Cell Metadata for how those actions fit
the wider extension model.
Inventory actions and operations — Preview
| Request | Choose it when | Commit behavior |
|---|---|---|
| GridInventoryMoveItemAction | Move an item on one board. | Replaces placement and occupancy; advances once. |
| GridInventoryRotateItemAction | Rotate an item in place. | Replaces orientation and occupancy; advances once. |
| GridInventorySetQuantityAction | Change one stack quantity. | Replaces the item extension; advances once. |
| GridInventorySortAction | Atomically repack a board. | Advances once only when at least one placement changes. |
| GridInventoryTransferItemOperation | Move an item between boards. | Mutated source and destination boards each advance once. |
| GridInventoryStackMergeOperation | Merge compatible stacks. | Each board advances only when its state changes. |
Use GridMultiBoardActionRunner for a project-owned IGridOperation:
- declare every participating board before planning;
- call
GridMultiBoardActionRunner.Previewto validate without mutation; - call
GridMultiBoardActionRunner.Applyto commit all participants atomically; - expect event-only participants to publish without advancing revision;
- expect participants with no mutation or event to publish nothing.
Keep identifiers separate
| Identifier | What it identifies | Example |
|---|---|---|
| Action object and type | One requested single-board change; there is no string action ID. | The object returned by GridActions.AddCell(...) |
| Structure definition ID | One reusable structure type. | game.crate |
| Structure instance ID | One placed structure. | crate-17 |
| Visual intent ID | Temporary presentation meaning. | grid.action.affected |
| Channel ID | The replaceable owner slot for temporary presentation. | grid.visual.channel.action-affected |
| Operation and result objects | One multi-board command and one returned outcome. | Project-owned IGridOperation and IGridOperationResult |
Do not derive action identity from visual intents or channels. Several actions can use the same feedback route, and one custom action can contribute several intents.
Result
The selected request matches one complete logical change. Preview supplies diagnostics without mutation, and Apply either commits the accepted plan atomically or leaves state unchanged.
Troubleshooting
| Symptom | Check |
|---|---|
| Preview succeeds but Apply rejects | Current state may have changed; Apply the action for fresh planning or rebuild the retained plan. |
| Several same-board changes partially apply | Wrap them in GridBatchAction rather than applying each request separately. |
| A cross-board workflow mutates only one board | Use a declared multi-board operation instead of independent actions. |
| The request succeeds but no visual appears | Logical actions do not require a renderer; continue with the feedback guide. |