Composition & Injection

5.0.8 projects wire Grid Building through a composition container and an injector pattern.

Version note: This guide is validated for Grid Building 5.0.8 (maintenance stable). The wiring layer is unchanged from 5.0.4.

If you are coming from the setup flow, complete Getting Started first. This guide explains the wiring layer that sits behind that setup, not the initial addon install and first placement sequence.

What the Container Actually Owns

GBCompositionContainer is the canonical composition root for one runtime grid-building context. It exposes:

  • config — exported GBConfig property (direct property, not a helper method)
  • get_settings() — returns GBSettings
  • get_templates() — returns GBTemplates
  • get_actions() — returns GBActions
  • get_logger() — returns GBLogger
  • get_contexts() — returns GBContexts
  • get_states() — returns GBStates

Use one container per active runtime context.

What the Injector Actually Does

GBInjectorSystem:

  • Requires composition_container.
  • Injects any node that implements resolve_gb_dependencies(...).
  • Performs initial recursive injection.
  • Injects newly added nodes inside the injection scope.
  • Runs editor validation automatically.

Important runtime detail:

  • The injector helps with wiring.
  • Runtime validation is only meaningful once GBLevelContext and GBOwner have populated the contexts/states your systems depend on.

Canonical Scene Wiring

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

MainLevel
  -> World
      -> TileMapLayer
      -> ObjectsRoot
      -> GBLevelContext
  -> Systems
      -> GBInjectorSystem
      -> BuildingSystem
      -> GridTargetingSystem
      -> ManipulationSystem
  -> GridPositioner2D
      -> TargetingShapeCast2D
      -> ManipulationParent
  -> Player
      -> GBOwner
  -> UI

Required Scene Contracts

  • GBInjectorSystem.composition_container must be assigned.
  • GBLevelContext.target_map must be assigned.
  • GBLevelContext.objects_parent must be assigned.
  • GBOwner.owner_root must be assigned.
  • Any node that needs plugin dependencies must implement resolve_gb_dependencies(container: GBCompositionContainer).

What resolve_gb_dependencies(...) Means

There is no formal interface keyword here. The injector simply checks whether a node has the method and, if so, calls it.

Typical runtime patterns:

  • GBOwner.resolve_gb_dependencies(...) registers the active owner into owner context.
  • GBLevelContext.resolve_gb_dependencies(...) applies level maps and placement parent into the states.
  • UI and helper nodes read state/context references from the container.
  • Systems register themselves via GBSystemsContext.set_system() — this is separate from the injection pattern.
1
2
3
4
5
6

@onready var injector: GBInjectorSystem = $Systems/GBInjectorSystem

func _ready() -> void:
    var container: GBCompositionContainer = preload("res://path/to/my_container.tres")
    injector.composition_container = container
    injector.run_validation()

What Should Be in the Container Resource

  • config.settings.building
  • config.settings.manipulation
  • config.settings.targeting
  • config.settings.placement_rules
  • config.templates
  • config.actions

5.0.4 update: Base placement_rules should reference external .tres files, not embedded subresources. See Web Export Guide for why this matters in exported builds.

Example Injection Target

1
2
3
4
5
6
7

extends Node2D

func resolve_gb_dependencies(container: GBCompositionContainer) -> void:
    var states: GBStates = container.get_states()
    var systems: GBSystemsContext = container.get_systems_context()
    var logger: GBLogger = container.get_logger()
    var targeting_settings: GridTargetingSettings = container.get_settings().targeting

What Is Not Automatic

  • The injector does not invent a GBLevelContext for you.
  • The injector does not invent a GBOwner for you.
  • The injector does not make placement work if target_map, objects_parent, or owner wiring are missing.
  • The injector does not replace calling real system entry points like enter_build_mode(placeable).

Plugin-User Checklist

  • Create a GBCompositionContainer resource.
  • Assign a valid GBConfig.
  • Add GBInjectorSystem to your scene.
  • Assign composition_container.
  • Add GBLevelContext.
  • Assign target_map and objects_parent.
  • Add GBOwner.
  • Assign owner_root.
  • Add the systems/nodes you want to use.
  • Trigger placement through the system API or injected UI.