A backend/programmatic placement request. This is the headless entry point for consumers (an external game backend, a simulation host, or any automation) that need to submit an explicit placement command and receive a stable, typed, persistence-safe PlacementLifecycleResult without driving the placement UI or inspecting Godot nodes. The command is intentionally generic: Grid Placement never learns about pawns, GOAP, Bevy, or any gameplay policy. The caller attaches whatever correlation tokens it needs via correlation_context — that dictionary is carried verbatim on the committed lifecycle result.
Source: addons/grid_placement/placement/placement_command.gd
Syntax
class PlacementCommand extends ResourceMembers
| Name | Kind | Summary |
|---|---|---|
operation | Property | The lifecycle operation to perform. Maps directly to a PlacementLifecycleResult operation constant (StringName). |
placeable | Property | The placeable definition to attempt to commit. |
target | Property | For SMOOTH placement: the world-space target position. For GRID placement: the target cell (as Vector2i). |
rotation | Property | Optional rotation/orientation in radians. AUTHORITATIVE: this value alone determines the validation geometry, the committed transform, the rectangular footprint geometry, and the lifecycle geometry. A command no longer inherits the live UI preview's pose, so the same command produces the same result whatever the player has selected or rotated. 0.0 means zero rotation, not "unspecified". The axis depends on the lane: rotation about +Z for 2D, yaw about +Y for 3D (positive = clockwise seen from above, matching the 3D rotate gesture). On a GRID session the angle must be a multiple of the increment that lane can represent — the session's ManipulationSettings.rotate_increment_degrees for 2D, 90 degrees for 3D. A non-finite or off-lattice angle is rejected with PlacementLifecycleResult.REASON_INVALID_DEFINITION and a pose_error diagnostic, before anything is mutated. SMOOTH sessions accept any finite value. |
correlation_context | Property | Opaque caller metadata (a game backend may attach simulation_run_id, pawn_id, goal_id, plan_id, action_attempt_id, task_id, construction_site_id, etc.). This is NOT inspected by Grid Placement — it is surfaced verbatim on the committed [PlacementLifecycleResult.correlation_context]. |
session | Property | The owning session. When null the host resolves the active/default session. |
commit | Method | |
cmd | Property | |
cancel | Method | |
cmd | Property | |
remove | Method | |
cmd | Property |