Grid Placement

Placement Workflow (5.0.2 Node-centric)

Detailed breakdown of the 5.0 node-centric placement workflow, from rule registration to history tracking, including validation touchpoints.

Weight: 24

This guide explains the 5.0.2 placement workflow for the maintenance lane.

5.0 is node-centric: scene nodes, composition container wiring, and stateful services/systems cooperate to place objects. This workflow represents the complete lifecycle of a placement action.

Architecture context (5.0)

In 5.0, placement is driven by node/state interactions:

  1. Input/Targeting: Updates node-backed targeting state.
  2. Rule Validation: Evaluates placement validity against runtime context.
  3. Indicator Sync: Mirrors validity and feedback to the user.
  4. Commit/Reject: Build systems finalize the action and record history.

The workflow is valid as long as targeting → validation → indicator feedback → commit stays coherent under node lifecycle constraints.

Detailed Placement Workflow

Phase 1: Preparation & Validation Setup

Before placement can occur, the system must be aware of the rules and constraints.

  • Rule Setup: Rules are configured with unique IDs and validators.
  • System Entry: The workflow typically begins by calling building_system.enter_build_mode(placeable). This method handles critical initialization steps, including clearing previous previews, resetting rotation, and preparing the targeting state.

Phase 2: Runtime Validation

As the user moves their cursor (Targeting Phase), the system continuously validates the potential placement. This is a critical step for learner feedback.

  • Context Evaluation: The current GridTargetingState is fed into the active rules. This state includes the target cell, world position, and any objects currently occupying that cell.
  • Parameterized Checks: Rules check bounds (is the cell within the grid?), collisions (is something already there?), and resource costs (does the player have enough gold?).
  • Result Generation: A PlacementReport (v5.0.2) or RuleResult is generated. This result is not just a boolean; it contains specific failure messages (issues) that can be displayed to the player. If any rule fails, the entire placement is marked as invalid.

Phase 3: Execution & Commit

When the user confirms placement (e.g., clicks the mouse), the system attempts to commit the action. This phase must be atomic to prevent state inconsistencies.

  • Final Validation: A final check ensures state hasn’t changed since the last frame.
  • Instantiation: The scene object is instantiated from the template and added to the scene tree.
  • Resource Consumption: If applicable, resources are deducted. This only happens after successful instantiation.

Common Pitfalls in Phase 3

  • Direct Property Assignment: Avoid setting building_system.selected_placeable directly. Use enter_build_mode(placeable) to ensure the system transitions to BUILD mode and sets up previews correctly.
  • Dirty State: Modifying the global state (e.g., player inventory) before the placement is fully committed can lead to desyncs if the placement fails at the last moment. Always consume resources as the final step.
  • Lifecycle Issues: Instantiating objects without adding them to the scene tree immediately can cause script errors if they rely on _ready() or tree access.
  • Signal Ordering: Be careful with signal emission order. Emitting “placement_started” should happen before “placement_committed” to ensure UI listeners update correctly.

State Management

A robust workflow relies on the Single Source of Truth principle.

  • Do not duplicate state: If GridTargetingState says a cell is valid, do not re-calculate validity in your UI code. Trust the state.
  • Reactive UI: Bind your UI indicators (ghosts, cursors) to the GridTargetingState signals (validity_changed, position_changed) rather than polling every frame. This ensures your visual feedback is always frame-perfect with the logic.

Phase 4: History & Persistence

Successful placements are recorded for undo/redo and session tracking.

  • Event Recording: A PlacementHistoryEntry is created, capturing timestamp, entity ID, position, and template.
  • Session Management: Entries are grouped by session_id, allowing for batch operations or session-based queries.
  • Serialization: History data can be serialized to dictionaries for saving/loading.

Validated by tests

Workflow evidence for this guide:

  • Recommended Workflow: res://addons/grid_building/test/integration/getting_started_workflow_test.gd — test_recommended_ui_trigger_flow validates that the UI-to-System architectural pattern correctly initializes the building state.
  • System Entry & State Management: res://addons/grid_building/test/e2e/all_systems_integration_tests.gd — test_enter_build_mode_state_consistency validates that the recommended entry point correctly initializes building state.
  • Full Pipeline: res://addons/grid_building/test/e2e/all_systems_integration_tests.gd — Validates the full targeting-to-placement pipeline.
  • Rule System: res://addons/grid_building/test/rules/validation/rule_system_integration_tests.gd — Confirms the validation phase logic.
  • Placement Logic: res://addons/grid_building/test/building/placement/rect4x2_bounds_validation_unit_test.gd — Validates coordinate-based placement logic.

Test Verification

The placement workflow is rigorously validated across several test suites. Refer to these scripts for implementation details and edge case handling:

Core Validation Logic

  • Reference: res://addons/grid_building/test/building/placement/rect4x2_bounds_validation_unit_test.gd
  • Key Coverage:
    • Grid Bounds: detailed integration tests for GridBoundsUtils.check_bounds.
    • Rule Registration: Tests bounds validation with multiple rule types via PlacementValidator.
    • Performance: Benchmarks for high-volume validation loops.

History & Persistence

  • Reference: res://addons/grid_building/test/building/placement/placement_report_unit_test.gd
  • Key Coverage:
    • Entry Recording: Validates placement report generation with full metadata.
    • Querying: Tests retrieval by position, entity ID, and session information.

Validation Components

  • Reference: res://addons/grid_building/test/rules/validation/valid_placement_tile_rule_test.gd
  • Key Coverage:
    • Tests the specific TileCheckRule logic used during Phase 2 of the workflow.

By examining these tests, you can see the exact data structures (like PlacementRuleContext) and method calls (validate_placement) that drive the workflow described above.