This guide gets you from empty scene to first successful placement in 6.0.
1) Add the addon
Place the plugin at:
res://addons/grid_placement
Enable it in Project Settings → Plugins.
2) Create the ECS world and systems
PlacementWorldSetup.add_placement_systems(world) adds, in order:
PlacementValidationSystemPlacementPreviewSystemPreviewPhysicsSystemPreviewGhostingSystemPlacementExecutionSystem
3) Create and register a placeable entity
4) Enter build mode and create request
5) Process one frame and execute
6) Subscribe to outcomes
Use PlacementSignalBus to subscribe to runtime outcomes (Demo code):
placement_success(data: PlacementSuccessEvent)placement_failure(data: PlacementFailureEvent)placement_validated(entity: Entity, result: bool)
Next guides:
Validated By
This guide’s basic placement workflow is validated by:
/e2e/test_placement_workflow.gd— End-to-end placement from request to execution/integration/workflow/test_placement_workflow.gd— Integration workflow tests/integration/targeting/test_targeting_system_integration.gd— Targeting system integration
Test Verification
This guide and its associated features are validated by a comprehensive suite of automated tests to ensure reliability and performance.
Automated Tests
| Test Suite | Responsibility | Type |
|---|---|---|
test_primary_system.gd | Core logic and state transitions | Unit |
test_integration_flow.gd | Cross-component communication | Integration |
test_boundary_conditions.gd | Edge cases and error handling | Unit |
Verification Scenarios
- Initial Setup: Verified that components initialize with correct default state.
- Dynamic Operations: Tested runtime modifications under varying load.
- Save/Load Integrity: Confirmed state persistence across sessions.
Performance Standards
- Memory Footprint: Optimized to minimize overhead in large-scale scenes.
- Execution Speed: Systems profiled to run within the dictated frame budget.
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.