Draft — Unreleased:This page is in active development. APIs, class names, and behavior may change before the release is finalized. Use it as a preview of what's coming — not as a stable integration target.
Scene-free orchestration for the build/place flow. Extracted from PlacementSystem to:
- Reduce the god-class footprint of PlacementSystem (~1,192 lines)
- Centralize the build validation + report + signal emission flow
- Enable per-game validation policy injection (different games want different validation strictness, error messages, telemetry hooks) The orchestrator owns the [method run_build] flow as a pure coordination function: it takes all dependencies via [PlacementBuildContext], runs validation, builds the instance via a callback, and emits signals via a callback. It does NOT hold any state itself. All public methods take a focused context object ([PlacementReadinessContext], [PlacementFailureContext], or [PlacementBuildContext]) so the API style is consistent across the orchestrator.
Source: addons/grid_placement/systems/building/placement_build_orchestrator.gd
Syntax
class PlacementBuildOrchestrator extends RefCountedMembers
| Name | Kind | Summary |
|---|---|---|
states | Property | Context object bundling all dependencies needed for a build attempt. Caller (PlacementSystem) populates these fields before invoking [method PlacementBuildOrchestrator.run_build]. Shared states for plugin systems. Required. |
settings | Property | Settings for grid building system operation. Required. |
indicator_context | Property | Context for resolving references to current objects. Required. |
selected_placeable | Property | Currently selected placeable resource. Required. The currently-selected placeable for the build. Typed Variant deliberately: in the blacksmith freed-ref lifecycle race (see AGENTS.md / ROADMAP ), the slot can become a freed Object between PlacementSystem populating it and the orchestrator running. The orchestrator's guard then short-circuits with a clean "No placeable selected for build" issue BEFORE `_build_instance.call` runs, so `_build_instance` itself only ever sees a valid ScenePlacementEntry. Callers building the context should still pass a ScenePlacementEntry in practice, but the Variant type lets the regression test deterministically reproduce the freed variant. |
preview | Property | Preview instance from the lazy preview builder. Required. |
previous_report | Property | Previous build report (for indicator chain). May be null. |
build_instance | Property | Callback: (ScenePlacementEntry, bool) -> Node2D — builds the scene instance. Receives the placeable and the attach_placeable_instance flag. Returns the placed Node2D, or null on failure. |
emit_signal | Property | Callback: (PlacementReport, int, bool) -> void — emits the build result. Receives the report, the build type, and a success flag. |
states | Property | Context for [method is_ready_to_place] and [method is_ready_to_paint_terrain]. Bundles everything the readiness predicates need: the shared states, the indicator context (place-only), the selected placeable (place-only), and the selected terrain name (terrain-only). Fields not relevant to a particular check are simply ignored. Shared states for plugin systems. Required. |
indicator_context | Property | Context for indicator manager lookup. Required for [method is_ready_to_place]. |
selected_placeable | Property | Currently selected placeable resource. Required for [method is_ready_to_place]. |
selected_terrain_name | Property | Currently selected terrain name. Required for [method is_ready_to_paint_terrain]. |
builder_owner | Property | Context for [method report_precondition_failure]. Bundles the report's owner, the build type, the failure message, and the target TileMapLayer so the failure-report factory has a single argument. Owner for the report (PlacementOwner or null). |
type | Property | Build type (SINGLE, DRAG, AREA, TERRAIN). |
message | Property | Human-readable failure message. |
target_map | Property | Target TileMapLayer (may be null). |
is_ready_to_place | Method | |
issues | Property | |
is_ready_to_paint_terrain | Method | |
issues | Property | |
report_precondition_failure | Method | |
report | Property | |
run_build | Method | |
manager | Property | |
builder_owner | Property | |
previous_indicators | Property | |
report | Property | |
safe_str | Property | |
placement_validation | Property | |
diag_errors | Property | |
validation_issues | Property | |
safe_str | Property | |
fail_msg | Property |
Source
addons/grid_placement/systems/building/placement_build_orchestrator.gd
Plugin docs root:gdscript/plugins/grid_placement_dev/docs