Architecture overview (5.0.3)

GridBuilding 5.0.3 is best understood as a node-first plugin with a composition-container / injector integration style.

Core Systems

5.0.3 consists of these main systems that work together:

SystemPurposeLocation
GBInjectorSystemInitializes and wires dependencies across the sceneaddons/grid_building/systems/injection/
GBCompositionContainerCanonical runtime composition root for config, contexts, states, logger, actions, and templatesaddons/grid_building/resources/
BuildingSystemEnters build mode, creates preview instances, runs placement setup, and commits placementaddons/grid_building/systems/building/
GridTargetingSystemCentral targeting-side coordinator for targeting state/settings/path manager validationaddons/grid_building/systems/grid_targeting/
GridPositioner2DHandles mouse/keyboard cursor-to-grid positioning and visibilityaddons/grid_building/systems/grid_targeting/grid_positioner/
TargetingShapeCast2DUpdates GridTargetingState.target from collision queriesaddons/grid_building/systems/grid_targeting/grid_positioner/
ManipulationSystemOwns move/build-manipulation workflow and manipulation state transitionsaddons/grid_building/systems/manipulation/
ManipulationParentVisual transform parent for rotation/flip/preview hierarchy during manipulationaddons/grid_building/systems/manipulation/

Key Classes

State Management

ClassPurpose
GBStatesContainer for all state (mode, targeting, building, manipulation)
ModeStateCurrent building mode (OFF, BUILD, MANIPULATE)
GridTargetingStateTargeting information such as target, target map, maps, positioner, manual targeting flags, and collision exclusions
BuildingStatePlacement parent, builder ownership, and build-related runtime state
ManipulationStateActive manipulation parent and manipulation-specific runtime state

Scene Context Nodes

ClassPurpose
GBLevelContextPushes target_map, maps, and objects_parent into the runtime states
GBOwnerRegisters the active owner/actor in owner context
GBContextsHolds indicator, owner, and systems contexts

Placement Rules

ClassPurpose
PlacementRuleBase class for all placement rules
TileCheckRuleBase class for rules evaluating tile/indicator state
CollisionsCheckRuleChecks for overlapping physics bodies
WithinTilemapBoundsRuleValidates placement within tilemap bounds
ValidPlacementTileRuleBasic placement validity check

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.target_map and objects_parent are assigned
  • GBOwner.owner_root is assigned
  • the systems you depend on are present in the scene and injected
  • runtime validation passes once your level and owner context are actually available