Grid Placement

GBInjectorSystem

AUTO-GENERATED FILE — DO NOT EDIT MANUALLY

Source: systems/injection/gb_injector_system.gd

Version: 5.1

class_name: GBInjectorSystem extends: GBSystem

Summary

Dependency injection system for the Grid Building Plugin.

5.1 composition root note:

  • This node is the canonical scene-tree composition root in the 5.0/5.1 GDScript track.
  • It wires a GBCompositionContainer into the nodes within its injection scope and (optionally) validates the resulting configuration.

6.0 equivalence note:

  • In the 6.0 C# track, the closest equivalent responsibility is handled by GridBuilding.Godot.Bootstrap.ServiceCompositionRoot (C#), which wires the service registry and core services for a Godot scene tree.
  • GBInjectorSystem remains the 5.0/5.1 GDScript injector for GBCompositionContainer and does not imply any cross-language bridge.

Timing drift note (5.1 vs 6.0):

  • In 5.0/5.1 GDScript, this injector runs early in the scene lifecycle and may observe a brief window where GBLevelContext / GBOwner are not populated yet.
  • In 6.0 C#, the composition root is explicit (service wiring happens in the bootstrap root), so this class of “scan-inject-then-validate” timing drift is largely avoided by construction.

Potential future improvement (5.1):

  • Add an explicit “runtime ready” gate/signal from host code to trigger FULL validation once world contexts are guaranteed available.
  • Keep current default behavior for backwards compatibility; projects that wire contexts late can opt into the gate by setting validation_mode = NONE (or STRUCTURE_ONLY) and calling run_validation() when ready.

This system automatically handles:

  1. Dependency Injection: Wires the GBCompositionContainer into all nodes that implement resolve_gb_dependencies(p_config: GBCompositionContainer)
  2. Automatic Validation: Validates the complete setup after injection and reports any configuration issues via the container’s logger

Runtime behavior and invariants:

  • Injection is scope-based: use injection_roots to constrain which part of the scene tree receives injection.
  • Injection is performed for existing nodes on startup and for newly-added nodes within the injection scope.
  • Injection is idempotent per-injector instance (meta is written on injected nodes).
  • The injector does not own the container; it only references it.

No manual validation calls are required - the injector handles everything automatically after dependency injection is complete.

The injector operates on a scoped portion of the scene tree (or the whole tree when no injection_roots are provided). It does not own the composition container — it holds a reference to one and performs injection and validation.

Setup Requirements:

  • Assign a GBCompositionContainer resource to this injector
  • Ensure GBLevelContext and GBOwner are properly configured before the injector runs (usually in _ready() methods)
  • The injector will automatically validate after injection and log any issues

Usage Example:

1
2
3
4
5

# In your scene node:
func resolve_gb_dependencies(p_config: GBCompositionContainer):
_composition_container = p_config
_logger = p_config.get_logger()
# No validation call needed - injector handles it automatically

[i]Nodes that implement resolve_gb_dependencies(p_config: GBCompositionContainer) will be injected automatically by this system.[/i]

Signals

  • initial_injection_completed
    • Emits when the initial scene injection is completed
  • node_injected
    • Emit whenever a node is injected

Exports

  • composition_container
    • Container services as the single source of truth for settings within it’s scope for systems and other nodes concerned with grid building operations. [br][br]

[b]Dependencies are injected out of this container by the GBInjectorSystem[/b]

  • injection_roots
    • Root nodes for injection. These nodes and any children node added will be injected by the GBInjectorSystem. Use this for scoping injection. If left empty, all nodes in the scene tree will be injected.

Methods

  • _init()
    • Optionally provide a container at construction time. Most projects assign composition_container via the inspector.
  • _ready()
    • Scene-tree entrypoint.

This method:

  • Ensures required container services exist (service registry / systems context)
  • Establishes cross-service workflow wiring
  • Performs initial injection
  • Schedules post-injection validation based on validation_mode
  • _wire_orchestrator_output_applier()
  • _unhandled_input()
  • _initialize()
  • get_injection_roots()
    • Gets the scoped root nodes for injection
  • validate_runtime()
    • Validates the runtime level setup for the grid building system.

Notes:

  • The authoritative validation is performed by composition_container.get_runtime_issues(); this method aggregates container-level issues and any injector-specific checks.
  • This function does NOT auto-run during _ready(); call run_validation() or call into the container from host code after the composition container has been injected and GBLevelContext / GBOwner are available.
  • run_validation()
    • Public helper: run validation and return boolean result. Logs issues using the container logger. Public helper: run validation and return boolean result. Logs issues using the container logger. Prefer calling composition_container.get_runtime_issues() directly from host scripts when you want to inspect the issue list without logging side-effects.
  • get_editor_issues()
  • get_runtime_issues()
  • _inject_existing()
  • _on_node_added_to_scope()
    • Handler for new nodes added to the injection scope. [code]p_scope[/code]: The scope node to which the new child belongs. [code]p_node[/code]: The newly added child node.
  • resolve_gb_dependencies()
    • Default resolve hook used by the injector when injecting this system into the scene. Host projects may implement their own resolve_gb_dependencies on world or player scripts to capture the container pointer and to run validation. The default implementation here only captures a logger and prints a small diagnostic.
  • set_validation_mode()
  • inject_node()
    • Injects dependencies into a single node (not recursive). Also connects signals to monitor future children and node exiting.
  • inject_recursive()
    • Injects dependencies into the node and all its children recursively. Used only on startup to cover existing tree nodes.
  • set_injection_meta()
    • Sets the meta data on the object following a successful injection.
  • remove_injection_meta()
    • Removes the injection meta data from the object.
  • _on_child_entered_tree()
    • Handler for new nodes entering the tree at runtime. Injects only the single node; child nodes will trigger their own injections.
  • _on_node_exiting_tree()
    • Handler for node exiting tree to clean up signal connections[br]
  • _connect_child_entered_tree()
    • [b]Private helper: Connect child_entered_tree signal if not already connected.[/b][br]
  • _disconnect_child_entered_tree()
    • [b]Private helper: Disconnect child_entered_tree signal if connected.[/b][br]
  • _connect_tree_exiting()
    • [b]Private helper: Connect tree_exiting signal if not already connected.[/b][br]
  • _disconnect_tree_exiting()
    • [b]Private helper: Disconnect tree_exiting signal if connected.[/b][br]
  • _connect_scene_tree_node_added()
  • _on_scene_tree_node_added()
  • _validate_after_injection()
    • Automatically validates the Grid Building setup after injection completes. This is called deferred after initial_injection_completed to ensure all nodes are properly injected.

Note: This does not guarantee that game-level runtime dependencies (like GBLevelContext / GBOwner) have already been populated. If those are wired later by host code, consider using validation_mode = STRUCTURE_ONLY (or NONE) and triggering run_validation() at the appropriate time.

  • _get_logger()
    • [b]Private helper: Report warnings through direct print or push_warning.[/b][br]