GridBuilding 5.0.2 is best understood as a node-first plugin with a composition-container / injector integration style.
Core Systems
5.0.2 consists of these main systems that work together:
| System | Purpose | Location |
|---|---|---|
| GBInjectorSystem | Initializes and wires dependencies across the scene | addons/grid_building/systems/injection/ |
| GBCompositionContainer | Holds global configuration (rules, settings, state) | Resource-based configuration |
| BuildingSystem | Orchestrates placement workflow, manages placeables | addons/grid_building/systems/building/ |
| GridTargetingSystem | Tracks where the player is targeting on the grid | addons/grid_building/systems/grid_targeting/ |
| GridPositioner2D | Node2D that positions on grid cells | addons/grid_building/systems/grid_targeting/grid_positioner/ |
| TargetingShapeCast2D | ShapeCast2D for querying objects under cursor | addons/grid_building/systems/grid_targeting/grid_positioner/ |
| ManipulationSystem | Manages object manipulation (move, rotate, flip) | addons/grid_building/systems/manipulation/ |
Key Classes
State Management
| Class | Purpose |
|---|---|
| GBStates | Container for all state (mode, targeting, etc.) |
| ModeState | Current building mode (OFF, BUILD, MANIPULATE) |
| GridTargetingState | Targeting information (target cell, map, positioner) |
Placement Rules
| Class | Purpose |
|---|---|
| PlacementRule | Base class for all placement rules (v5.0) |
| TileCheckRule | Base class for rules evaluating TileMapGrid |
| CollisionsCheckRule | Checks for overlapping physics bodies |
| WithinTilemapBoundsRule | Validates placement within tilemap bounds |
| ValidPlacementTileRule | Basic placement validity check |
Boundary (5.0.2)
- Godot nodes + scripts
- Own most runtime behavior.
- Public API is primarily node exports + signals.
- Composition container + injector
- Wiring layer that assigns settings/services/state into nodes.
- State-first coordination
- Many listeners consume state directly (polling or state references in signals).
- 5.0.2 does not consistently separate event payloads from state.
High-level shape
Godot nodes / scripts
↓
GBInjectorSystem (initialization)
↓
GBCompositionContainer (configuration)
↓
Systems (BuildingSystem, GridTargetingSystem, ManipulationSystem)
↓
Nodes (GridPositioner2D, TargetingShapeCast2D)
Data Flow
- Initialization: GBInjectorSystem reads GBCompositionContainer and injects dependencies
- Input: Player input goes to GridTargetingSystem
- Targeting: TargetingShapeCast2D queries scene, GridPositioner2D positions preview
- Validation: Placement rules validate against GridTargetingState
- Placement: BuildingSystem orchestrates final placement
What 5.0.2 optimized for
- Fast adoption: add nodes to a scene, connect signals, configure exports.
- Direct debuggability in the editor: follow node references in the inspector.
What 5.0.2 did not standardize (later improved in 6.0)
- A strict, explicit split between:
- service-owned state
- event payloads
- diagnostics snapshots
6.0 improves this by introducing a clearer boundary where:
- signals/events carry small payload objects (EventData)
- snapshots exist for diagnostics/tests
- internal state stays private to services
Related Guides
- Composition + injection (5.0.2) — Dependency wiring
- Targeting Flow (5.0.2) — Targeting system details
- Placement Rules (5.0.2) — Runtime validation
Validated By
- Recommended Workflow: res://addons/grid_building/test/integration/getting_started_workflow_test.gd — test_recommended_ui_trigger_flow validates the UI-driven interaction pattern for starting the building lifecycle.
- System Coordination: res://addons/grid_building/test/e2e/all_systems_integration_tests.gd — Validates the integration and communication between
BuildingSystem,ManipulationSystem, andGridTargetingSystem. - Dependency Wiring: res://addons/grid_building/test/utilities/data/environment_loading_unit_test.gd — Confirms that
GBCompositionContainercorrectly initializes states and context for system consumption. - Rule Hierarchy: res://addons/grid_building/test/rules/validation/rule_system_integration_tests.gd — Verifies that the rule system correctly processes both base rules and placeable-specific overrides.
- Node Lifecycle: res://addons/grid_building/test/integration/grid_positioner_rotation_integration_test.gd — Validates the interaction between
GridPositioner2DandManipulationParentwithin the node hierarchy.