Place, move, orient, and remove structures
When to use
After the first structure placement tutorial, use the built-in actions to place a structure, move or orient it at another anchor, and eventually remove it.
Before you start
Start with a ready board containing a topology-compatible structure definition.
Build a topology-compatible definition and keep its definition ID stable. Supply a stable instance ID for any structure that must survive persistence or cross-system references.
Procedure
Excerpt — place, move, orient, and remove a structure. Tested using public APIs.
public static StructureMutationResult PlaceMoveAndRemoveStructure()
{
using GridBoardState state = CreateProgrammaticBoard();
GridStructureDefinition crate = CreateCrate();
GridActionResult placed = GridActionRunner.Apply(
state,
GridActions.PlaceStructure(
crate,
new SquareGridCoordinate(0, 0),
instanceId: "crate-1"));
GridActionResult moved = GridActionRunner.Apply(
state,
GridActions.MoveStructure(
crate,
"crate-1",
new SquareGridCoordinate(2, 1)));
GridActionResult removed = GridActionRunner.Apply(
state,
GridActions.RemoveStructure("crate-1"));
return new StructureMutationResult(
placed.Success,
moved.Success,
removed.Success,
state.Revision,
state.TryGetStructure("crate-1", out _));
}
Pass a normalized GridOrientation to placement or movement when the footprint should rotate. Preview supplies the resolved occupied cells and policy diagnostics before commit.
Result
Placement, movement, and removal each advance the revision once. After the third commit,
crate-1 is no longer in occupancy and observers have received ordered lifecycle events.
Troubleshooting
| Symptom | Check |
|---|---|
| Part of the footprint is outside the board. | Change the anchor or orientation, or add the required runtime cells. |
| Occupancy or coexistence rejects the request. | Inspect the placement failures to identify the responsible policy and cells. |
| Placement reports a duplicate instance ID. | Generate or supply a unique stable ID. |
| Apply rejects a retained plan as stale. | Build a fresh plan after the intervening commit. |