Getting Started

Use this page to get a clean GridBuilding 5.0.10 setup with the current template workflow.

1) Add the plugin and confirm paths

• Copy the plugin archive so the addon lands at res://addons/grid_building.
• Copy the templates folder if you want the shipped starter scenes (systems.tscn, placeable UI, grid positioner).
• Keep the 5.0.10 plugin files together; do not mix folders from older plugin snapshots.
• Confirm your project can load 5.0.10 resources (no missing script/resource errors in the editor).
• Enable the plugin, then run Project → Tools → Grid Placement / Setup Default Input Actions and restart the editor.

2) Configure systems via the Inspector (Recommended)

In GridBuilding 5.0.10, we prioritize a no-code setup for your level infrastructure. Instead of creating a level script to manually wire systems, you should assign dependencies directly in the Godot Inspector.

The fastest path is to drop in templates/grid_building_templates/systems/systems.tscn. That scene already contains GBInjectorSystem, BuildingSystem, GridTargetingSystem, and ManipulationSystem. Leave Injection Roots empty unless you are intentionally scoping injection. Empty means the whole scene tree is injected, including a GBLevelContext that is a sibling of Systems.

The Collector/Injector Pattern

1. GBInjectorSystem: Add this under Systems. Assign a GBCompositionContainer resource to composition_container.
2. GBLevelContext: Add this on the level (not under Systems). Assign target_map, maps, and objects_parent.
3. GBOwner: Add this on the player/controller. Assign owner_root to the player root. Skipping this is the usual reason build mode closes when you click a placeable in the UI.
4. GridPositioner2D: Add the shipped positioner stack in the main scene (sibling of Systems, not a child of it).

By assigning these in the editor, the GBInjectorSystem can automatically find and wire them at runtime without a single line of boilerplate code in your MainLevel.gd.

Required Scene Tree

MainLevel (Node2D)
├── World (Node2D)
│   ├── TileMapLayer          # GBLevelContext.target_map and maps
│   ├── PlacedObjects         # GBLevelContext.objects_parent
│   └── GBLevelContext
├── Systems
│   ├── GBInjectorSystem      # composition_container assigned; injection_roots empty
│   ├── BuildingSystem
│   ├── GridTargetingSystem
│   └── ManipulationSystem
├── GridPositioner2D
│   └── ManipulationParent
│       └── IndicatorManager
├── Player (CharacterBody2D)
│   └── GBOwner               # owner_root = Player
└── UI (CanvasLayer)
    └── PlaceableSelectionUI

Required inspector fields

Node	Field	Assign
GBInjectorSystem	composition_container	Your GBCompositionContainer
GBInjectorSystem	injection_roots	Leave empty for first setup
GBLevelContext	target_map	Ground TileMapLayer
GBLevelContext	maps	At least that same layer
GBLevelContext	objects_parent	Node2D that should own placed instances
GBOwner	owner_root	Player/controller root

If any of those are missing at runtime, selecting a placeable from the UI calls enter_build_mode(), fails readiness, and switches mode back to OFF. The UI disappears as if you pressed Escape. That is not a missing LevelBuildingContext node.

3) Use the Placement UI Template

Don't put all of your code in a level script. Instead, use the shipped PlaceableSelectionUI template (or a custom UI controller) to trigger building system interactions.

If you wrap the HUD in a full-screen Control, set that HUD root Mouse Filter to Ignore so empty UI space does not eat placement clicks. The selection list itself still receives clicks.

Recommended Architectural Pattern: UI-Driven Interaction

Instead of manually setting states in your level script, connect your UI components to the BuildingSystem. The PlacementUITemplate provides a "Golden Path" implementation for selection and placement triggers.

# Example of a UI Controller triggering the system
extends Control

@export var building_system:BuildingSystem

func _on_placeable_selected(placeable:Placeable)-> void:
    # Trigger placement mode from the UI
    var report= building_system.enter_build_mode(placeable)
    if report== null or not report.is_successful():
        _handle_error(report)

4) Validated By

We provide a set of "Golden Path" integration tests that match this recommended setup. If your scene matches the structure above, you can use these tests to verify your project integrity.

• Integration Tests: Includes test_recommended_ui_trigger_flow (see: getting_started_workflow_test.gd) to validate the UI-to-System architectural pattern.
• E2E Consistency: Includes test_injector_auto_wiring (see: all_systems_integration_tests.gd) which confirms that GBInjectorSystem correctly identifies the components.

Cross Test Validation

To verify the setup and initialization steps described in this guide, refer to the following test scripts and source files which demonstrate the correct configuration:

• Scene Setup & Injection: getting_started_workflow_test.gd
• System Entry: all_systems_integration_tests.gd
• Placement Rules: valid_placement_tile_rule_test.gd

Validation Sources

The following source files in GBInjectorSystem validate the injection behavior described in this guide:

• gb_injector_system.gd — Core implementation:
  • _ready() and _initialize(): Trigger automatic injection when composition_container is assigned
  • inject_recursive(): Performs initial scene tree injection
  • _on_child_entered_tree(): Handles runtime node injection via signal callback
  • _validate_after_injection(): Runs automatic validation after injection completes
• API Reference: GBInjectorSystem

Common Issues

Selecting a placeable exits build mode

If you press 2 to enter build mode, then click a placeable in the list, and the UI closes (Mode changed -> 0, Clearing selected placeable on mode change to OFF), the click did reach enter_build_mode(). Readiness failed, so 5.0.10 leaves BUILD.

Unfilter the Output panel. The useful lines are warnings such as:

• No placer set in _owner_context. Cannot identify object placer. → add GBOwner and assign owner_root
• No placed parent set / Property [target_map] is NULL / [maps] is empty. → GBLevelContext was not injected or its inspector fields are empty

GBLevelContext may sit under a sibling of Systems (for example a GB_References node). That is fine while injection_roots is empty. If you set injection_roots to Systems only, the sibling context is skipped.

There is no LevelBuildingContext node. That string is leftover wording inside GBLevelContext.

Injection Not Running

If injection doesn't seem to be running, verify that:

1. The GBInjectorSystem node is in your scene tree
2. The composition_container property is assigned (not null)
3. Nodes that need injection implement resolve_gb_dependencies(container: GBCompositionContainer)
4. injection_roots is empty, or includes every node that must be injected (GBLevelContext, GBOwner, the selection UI, IndicatorManager)

Validation Errors

If you see validation errors after setup:

1. Check that GBLevelContext has target_map, maps, and objects_parent assigned
2. Verify templates are loaded via GBConfig.templates
3. Ensure GBOwner exists and owner_root is assigned

Next Steps

After completing this setup, proceed to:

• Placement Rules Guide - Configure placement validation rules
• Targeting Flow - Understand cursor targeting
• Troubleshooting - Common issues and solutions