Placement Workflow (6.0 ECS)

Detailed ECS pipeline for placement: from user intent to committed entity, including validation and event emission.

Weight: 31

This guide explains the 6.0 placement workflow in the ECS runtime. Unlike the node-centric 5.0, 6.0 relies on strictly ordered systems processing component data.

The ECS Paradigm

In 6.0, “placing an object” is a multi-frame process of refining data.

Components: Hold state (Request, Valid, Invalid, Preview).
Systems: Process behavior (validate connection, update visual).
Events: Broadcast outcomes (UI updates, audio triggers).

Detailed Workflow Steps

Step 1: Intent Creation

The user input system creates a PlacementRequestComponent.

Data: Contains placeable_id, grid_position, orientation.
Lifecycle: This component is ephemeral. It exists only while the user is trying to place something.

Step 2: Validation System

The PlacementValidationSystem runs first.

Input: Entities with PlacementRequestComponent.
Process: Checks bounds, collisions, and custom rules (like resource costs).
Output: Adds a ValidationResultComponent to the entity. This component flags the request as Valid or Invalid.

Step 3: Preview System

The PlacementPreviewSystem runs next.

Input: PlacementRequestComponent + ValidationResultComponent.
Process:
- Valid: Shows a green ghost, snap to grid.
- Invalid: Shows a red ghost, maybe displays error text.
State: Updates the PlacementPreviewComponent which holds the visual instance.

Step 4: Execution System

When the user confirms the placement (click):

Input: A PlacementRequestComponent that is Valid and marked for Commit.
Process:
- Converts the request into a permanent PlaceableEntity.
- Consumes resources (via ResourceConsumptionRule).
- Removes the temporary request components.
Output: A new entity in the world.

Step 5: Event Emission

Throughout this process, the PlacementSignalBus emits events for decoupled systems (UI, Audio).

placement_validity_changed(is_valid: bool)
placement_committed(entity: Entity)
placement_failed(reason: String)

Data Flow Diagram

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
[User Input] -> [PlacementRequest]
                      |
                      v
             [ValidationSystem] -> [ValidationResult]
                      |
        +-------------+-------------+
        |                           |
        v                           v
[PreviewSystem]              [ExecutionSystem] (if committed)
   (Visuals)                        |
                                    v
                             [World Entity]

placement-lifecycle.md: Full entity lifecycle details.
architecture-overview.md: High-level ECS concepts.
ecs-components-reference.md: API reference for components.
events-and-ui-integration.md: How to hook up UI.

Performance Tuning

In ECS, performance is about data access patterns.

Batch Processing: The ValidationSystem processes all requests in a single pass. Ensure your rules don’t do expensive single-entity lookups (like get_node()). Use component data instead.
Archetypes: Keep your entity structures consistent. Adding/removing components at runtime (archetype fragmentation) is expensive. PlacementRequestComponent is added once and removed once; this is fine.
Spatial Hashing: For validation queries (get_neighboring_entities), use the GridSystem’s spatial hash map rather than iterating all entities.

Test Verification

The ECS workflow is verified by end-to-end tests that simulate the entire pipeline.

Core Workflow: res://addons/grid_placement/tests/e2e/test_placement_workflow.gd
- Pipeline Integrity: Creates a request, runs the systems, and asserts that a final entity is created.
- Failure Paths: Intentionally creates invalid requests (out of bounds) and asserts that NO entity is created.
Event Integration: res://addons/grid_placement/tests/integration/targeting/test_targeting_event_workflow.gd
- Signal Timing: Verifies that events are emitted in the correct order (Validation -> Preview -> Commit).
- Data Accuracy: Checks that the events carry the correct payload (e.g., correct resource cost in failure message).

Implementation Details

The implementation of these systems follows a strict Entity Component System (ECS) pattern, prioritizing data locality and cache efficiency. By separating state into components and logic into static systems, we achieve a high degree of modularity and testability.

Key Considerations

Scalability: Designed to handle thousands of entities without significant performance degradation.
Interoperability: Components are designed to be easily extensible and compatible with other plugin systems.
Error Handling: Robust input validation and fail-fast mechanisms are integrated at the system level.

Common Pitfalls

Component Lifecycle: Ensure that components are correctly removed when entities are destroyed to avoid orphaning data.
Signal Loops: Be cautious of cyclical dependencies between systems via signal observers.
Threading: Systems are generally thread-safe, but UI-bound operations must remain on the main thread.

Advanced Configuration

For advanced users, most systems support custom hooks and override mechanisms. Refer to the specific system documentation for details on extending the default behavior.