Architecture Overview

Grid Building 5.0.8 is best understood as a node-first plugin with a composition-container / injector integration style.

Version note: This guide is validated for Grid Building 5.0.8 (maintenance stable). The core architecture is unchanged from 5.0.4; 5.0.5 fixed GBAssetResolver subdirectory scanning. See the Patch Notes for specifics.

5.0.8 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 | Canonical runtime composition root for config, contexts, states, logger, actions, and templates | addons/grid_building/resources/ | | BuildingSystem | Enters build mode, creates preview instances, runs placement setup, and commits placement | addons/grid_building/systems/building/ | | GridTargetingSystem | Central targeting-side coordinator for targeting state/settings/path manager validation | addons/grid_building/systems/grid_targeting/ | | GridPositioner2D | Handles mouse/keyboard cursor-to-grid positioning and visibility | addons/grid_building/systems/grid_targeting/grid_positioner/ | | TargetingShapeCast2D | Updates GridTargetingState.target from collision queries | addons/grid_building/systems/grid_targeting/grid_positioner/ | | ManipulationSystem | Owns move/build-manipulation workflow and manipulation state transitions | addons/grid_building/systems/manipulation/ | | ManipulationParent | Visual transform parent for rotation/flip/preview hierarchy during manipulation | addons/grid_building/systems/manipulation/ |

5.0.4 stability note: The ManipulationSystem and BuildingSystem received significant hardening in 5.0.4. Stale state, deleted sources during active moves, and recursive cleanup edge cases are now handled safely.

5.0.8 note: TargetingShapeCast2D requires placed objects to have collision_layer (what the object IS) set to the targeting layer, not just collision_mask. See Troubleshooting.

Key Classes

State Management (in resources/states/ and systems/*/ subdirectories)

| Class | Location | Purpose | |-|-|******| | GBStates | resources/states/ | Container for all state (mode, targeting, building, manipulation) | | ModeState | mode/ | Current building mode (OFF, BUILD, MANIPULATE) | | GridTargetingState | systems/grid_targeting/ | Targeting information such as target, target map, maps, positioner, manual targeting flags, and collision exclusions | | BuildingState | systems/building/ | Placement parent, builder ownership, and build-related runtime state | | ManipulationState | systems/manipulation/ | Active manipulation parent and manipulation-specific runtime state |

Scene Context Nodes

| Class | Location | Purpose | |-|-|******| | GBLevelContext | components/ | Exports target_map, maps, and objects_parent properties; applies them via resolve_gb_dependencies() | | GBOwner | user/ | Registers the active owner/actor in owner context | | GBContexts | context/ | Holds indicator, owner, and systems contexts | | GBSystemsContext | context/ | Holds references to BuildingSystem, GridTargetingSystem, ManipulationSystem; use set_system() to register | | IndicatorContext | context/ | Holds reference to IndicatorManager | | GBOwnerContext | user/ | Internal refcounted holding the GBOwner reference |

Placement Rules (in placement/placement_rules/ and placement/placement_rules/template_rules/)

| Class | Location | Purpose | |-|-|******| | PlacementRule | placement/placement_rules/ | Base class for all placement rules | | TileCheckRule | placement/placement_rules/ | Base class for rules evaluating tile/indicator state | | CollisionsCheckRule | placement/placement_rules/template_rules/ | Checks for overlapping physics bodies | | WithinTilemapBoundsRule | placement/placement_rules/template_rules/ | Validates placement within tilemap bounds | | ValidPlacementTileRule | placement/placement_rules/template_rules/ | Basic placement validity check | | SpendMaterialsRuleGeneric | placement/placement_rules/template_rules/ | Consumes inventory/materials after successful placement |

Runtime Boundary

  • Godot nodes + scripts
    • Own most runtime behavior.
    • Expose the practical runtime API through exports, methods, and shared state objects.
  • Composition container + injector
    • Wire contexts, states, logger, actions, templates, and settings into nodes.
  • State-first coordination
    • Many listeners consume shared state directly instead of receiving small isolated payload objects.

High-Level Shape

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

Scene nodes
  ->
GBCompositionContainer
  ->
GBInjectorSystem
  ->
Nodes implementing resolve_gb_dependencies(...)
  ->
GBStates + GBContexts
  ->
Placement / targeting / manipulation runtime behavior

Data Flow

  1. Initialization
    • GBInjectorSystem reads composition_container.
    • It injects any node with resolve_gb_dependencies(...).
  2. Scene context application
    • GBLevelContext applies target_map, maps, and objects_parent.
    • GBOwner applies the active owner.
  3. Input and targeting
    • GridPositioner2D processes mouse/keyboard input and moves to tile centers.
    • TargetingShapeCast2D updates GridTargetingState.target.
  4. Placement start
    • UI or game code calls BuildingSystem.enter_build_mode(placeable).
    • Preview/rules/setup are created from the selected Placeable.
  5. Validation and commit
    • Base rules from GBSettings.placement_rules and placeable-specific rules are evaluated.
    • BuildingSystem.try_build() commits placement if validation succeeds.
  6. Manipulation
    • ManipulationSystem manages move/manipulation workflow.
    • ManipulationParent owns the visual rotation/flip parent hierarchy.

What Plugin Users Should Rely On

  • Inspector-driven setup for level wiring and settings.
  • Method-based DI via resolve_gb_dependencies(...).
  • State-based coordination through GBStates and GBContexts.
  • System entry points such as enter_build_mode(...), try_build(), and manipulation APIs.

Essential Integration Invariant

The plugin is only fully ready after all of these are true:

  • GBInjectorSystem.composition_container is assigned.
  • GBLevelContext is in the scene with target_map, maps, and objects_parent assigned.
  • GBOwner is in the scene with owner_root assigned.
  • Systems (BuildingSystem, GridTargetingSystem, ManipulationSystem) are registered via GBSystemsContext.set_system().
  • IndicatorContext.indicator_manager is assigned if using indicators.
  • Runtime validation passes once your level and owner context are actually available.