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 [member 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. [code]0.0[/code] 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 [member ManipulationSettings.rotate_increment_degrees] for 2D, 90 degrees for 3D. A non-finite or off-lattice angle is rejected with [constant PlacementLifecycleResult.REASON_INVALID_DEFINITION] and a [code]pose_error[/code] 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 |