This reference is scoped to setup and gameplay usage.
Core placement components
| Component | Role |
|---|---|
PlaceableComponent | Identifies what is being placed (template/id and placement-relevant data) |
GridPositionComponent | Grid-space position data |
PlacementComponent | Placement session/mode state (is_placing, attempts, lock flags) |
PlacementRequestComponent | Active request payload (target position, rotation, scale, validation result) |
PlacementCommandComponent | Execution command object used by placement execution system |
Validation and preview components
| Component | Role |
|---|---|
PlacementRuleComponent | Attaches runtime rule type/configuration for custom validation |
ValidationResultComponent | Aggregated validation result and issues |
VisualPreviewComponent | Preview visual state (valid/invalid/neutral, collision indicator visibility) |
Manipulation component
ManipulationComponent tracks operation state for:
PLACEREMOVEMOVEROTATE
and includes constraints/state needed by manipulation systems.
Persistence note
For save/load via GECS serialization, keep persistent data in @export fields on components.
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.
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.
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.