Grid Placement

Getting Started

Getting started guide for GridBuilding 5.0.2

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

1) Add the plugin and confirm paths

  • Ensure the addon is installed at: res://addons/grid_building
  • Keep the 5.0.2 plugin files together; do not mix folders from older plugin snapshots.
  • Confirm your project can load 5.0.2 resources (no missing script/resource errors in the editor).

In GridBuilding 5.0.2, 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 Collector/Injector Pattern

  1. GBInjectorSystem: Add this to your Systems folder. It acts as the central hub for dependency resolution.
  2. GBCompositionContainer: Create a .tres resource for your rules and templates. Assign this to the composition_container export on the GBInjectorSystem in the Inspector.
  3. GBLevelContext: Add a GBLevelContext node to your level root. This node should have its target_map (your TileMapLayer) and world references assigned in the Inspector.
  4. GBOwner: The entity that “owns” the placement (e.g., the Player) should have a GBOwner node.

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

MainLevel (Node2D)          # Ideally NO script here
├── World (Node2D)          # The environment
│   ├── TileMapLayer        # Assigned to GBLevelContext
│   └── GBLevelContext      # Configured in Inspector
├── Systems                 # Shared systems folder
│   ├── BuildingSystem
│   ├── GridPositioner2D
│   └── GBInjectorSystem    # composition_container assigned here
├── Player (CharacterBody2D)
│   └── GBOwner             # The placement owner
└── UI (CanvasLayer)
    └── PlacementUITemplate # Handles BuildingSystem interactions

3) Use the Placement UI Template

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

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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# 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 not report.is_success:
        _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

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)

Validation Errors

If you see validation errors after setup:

  1. Check that GBLevelContext has a valid target_map assigned
  2. Verify templates are loaded via GBConfig.templates
  3. Ensure GBOwner exists for the entity doing placement

Next Steps

After completing this setup, proceed to: