GBCompositionContainer

AUTO-GENERATED FILE — DO NOT EDIT MANUALLY

Source: resources/gb_composition_container.gd

Version: 5.1

class_name: GBCompositionContainer extends: GBResource

Summary

Dependency injection root for context-specific Grid Building setup.

The GBCompositionContainer is the canonical composition root for a runtime Grid Building context. Typical usage:

• Create one container per player or active simulation instance (for multiplayer or local split-screen projects each player can have their own isolated composition container).
• Assign a GBConfig resource to the container. The config contains the user-visible settings, templates, rules, and runtime checks used by the systems.
• Create and assign a GBLevelContext and a GBOwner in your scene, then ensure they are wired into the container’s contexts (usually via the injector). The GBLevelContext provides tilemap / tilelayer lookup and spatial context required for placement and targeting. The GBOwner identifies who is responsible for performing operations (a player or simulated actor) and is required by many systems.

Runtime behavior and invariants:

• This resource caches runtime objects (contexts, registry, orchestrators).
• The cache is lazily created on first access.
• The cache is expected to be per-scene (and typically per-player).
• Sharing the same resource instance across scenes/players is unsafe; this class enforces isolation via resource_local_to_scene.

What this class is responsible for:

• Providing a single place to access core services (placement/targeting/etc.).
• Ensuring services are created with the correct contexts + logger + settings.
• Providing a single entrypoint to validate configuration/runtime readiness.

What this class is not responsible for:

• Owning scene nodes (it is a Resource, not a Node).
• Driving gameplay loops; callers invoke services/orchestrators.

Validation workflow:

1. Ensure the level is loaded and the GBLevelContext and a GBOwner instance are created and assigned to the container’s contexts.
2. The GBInjectorSystem automatically validates the complete setup after dependency injection is complete. Any issues are logged via the container’s logger system.
3. For manual validation, call composition_container.get_runtime_issues() to collect diagnostics, or composition_container.validate_runtime() to get a boolean result.

Note: The injector (GBInjectorSystem) handles both dependency injection and automatic validation. No manual validation calls are required in most cases.

Signals

(none)

Exports

• config
  • Main configuration resource for the grid building system.
• service_factory_override
  • Optional seam: allow host projects to provide a custom service factory. If null, the default ServiceFactoryScript is used.

Methods

• _ensure_runtime_isolation()
  • Ensures this resource is scene-local.

This prevents subtle bugs where cached runtime state leaks between scenes or between different players/owners.

• _get_service_registry()
  • Gets or creates the centralized service registry with all core services. Services are created once per container and managed through the registry. States are now encapsulated within services and accessed via service methods. [return]: [GPServiceRegistry] - Service registry with placement, indicator, manipulation, targeting services
• get_service_registry()
• get_mode_service()
• get_grid_service()
• get_targeting_service()
• get_placement_service()
• get_indicator_service()
• get_manipulation_service()
• get_positioning_input_adapter()
• get_placement_input_adapter()
• get_manipulation_input_adapter()
• get_input_service()
• get_orchestrator_effects_adapter()
• set_service_registry()
  • Sets the service registry. Should be called by GBInjectorSystem during initialization.
• get_targeting_workflow_adapter()
• get_build_orchestrator()
• get_manipulation_orchestrator()
• ensure_workflow_wiring()
• get_composition_registry()
  • Gets the composition registry.
• get_contexts()
  • Gets or creates the contexts container for dependency injection.[br][br] [code]return[/code]: [i]GBContexts[/i] - Contexts container with all system contexts
• get_logger()
  • Gets or creates the centralized logger instance.[br][br] [code]return[/code]: [i]GPLogger[/i] - Logger instance for error/warning reporting
• get_settings()
  • Gets the main settings configuration resource.
• get_visual_settings()
  • Gets the visual settings configuration resource.
• get_manipulation_settings()
  • Gets the manipulation settings configuration resource.
• get_placement_rules()
  • Gets the array of placement rules from the main settings. [code]return[/code]: [i]Array[PlacementRule][/i] - Array of placement rules from settings
• _log_placement_rules_summary()
• get_runtime_checks()
• get_templates()
  • Gets the templates resource from configuration.
• get_indicator_context()
  • Gets the placement context from the contexts container.
• get_actions()
  • Gets the input actions configuration resource.
• get_debug_settings()
  • Gets the debug settings from the main settings configuration.
• get_editor_issues()
  • Gets all issues that would prevent proper operation in the editor.
• get_structure_issues()
  • Gets all structural/editor issues (mirrors get_editor_issues but kept for clarity).
• get_runtime_issues()
  • Gets issues that prevent the grid building systems from operating at runtime.

Use this when you want a full runtime validation pass (everything required for the systems to actually function once the scene is running).

Expected call timing:

• After your level is loaded with GBLevelContext
• After a GBOwner is set to the GPOwnerContext

Note: This may include readiness issues as a subset depending on validator rules.

• log_runtime_issues()
  • Convenience: Log runtime issues using the container’s logger. Useful for quick smoke-tests from host scripts or for initial boot-time diagnostics. Returns the issue array for programmatic inspection as well.
• validate_runtime()
  • Compatibility API: validate_runtime() was used by older demo code paths.
• get_runtime_snapshot()
  • Returns a lightweight snapshot of runtime wiring state. Designed for debugging and smoke tests without exposing internal objects.
• _get_debug_settings_for_logger()
  • Internal helper to get debug settings without logging (for logger initialization)