Architecture Overview

Key Classes

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

  • GBStates (resources/states/) - Container for all state
  • ModeState (mode/) - Current building mode (OFF, BUILD, MANIPULATE)
  • GridTargetingState (systems/grid_targeting/) - Targeting information
  • BuildingState (systems/building/) - Placement parent, builder ownership
  • ManipulationState (systems/manipulation/) - Active manipulation parent

Scene Context Nodes

  • GBLevelContext (components/) - Exports target_map, maps, objects_parent
  • GBOwner (user/) - Registers the active owner
  • GBContexts (context/) - Holds indicator, owner, systems contexts
  • GBSystemsContext (context/) - Holds BuildingSystem, GridTargetingSystem, ManipulationSystem
  • IndicatorContext (context/) - Holds reference to IndicatorManager
  • GBOwnerContext (user/) - Internal refcounted holding the GBOwner reference

Placement Rules

  • PlacementRule - Base class for all placement rules
  • TileCheckRule - Base class for rules evaluating tile/indicator state
  • CollisionsCheckRule - Checks for overlapping physics bodies
  • WithinTilemapBoundsRule - Validates placement within tilemap bounds
  • ValidPlacementTileRule - Basic placement validity check
  • SpendMaterialsRuleGeneric - Consumes inventory/materials after 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.