Getting Started

Use this page to get a clean GridBuilding 5.0.3 setup with the current runtime contract.

1) Add the plugin and confirm paths

  • ensure the addon is installed at res://addons/grid_building
  • keep the 5.0.3 plugin files together
  • confirm your project loads the plugin without missing script/resource errors

2) Create a composition container

Create a GBCompositionContainer resource and make sure its config contains:

  • settings
  • templates
  • actions

The most important fields plugin users usually configure first are:

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

3) Add the required scene nodes

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

MainLevel
  -> World
      -> TileMapLayer
      -> ObjectsRoot
      -> GBLevelContext
  -> Systems
      -> GBInjectorSystem
      -> BuildingSystem
      -> GridTargetingSystem
      -> GridPositioner2D
      -> TargetingShapeCast2D
      -> ManipulationSystem
      -> ManipulationParent
  -> Player
      -> GBOwner
  -> UI
      -> your placeable-selection / action UI

4) Configure the critical inspector fields

  • GBInjectorSystem.composition_container
  • GBLevelContext.target_map
  • GBLevelContext.objects_parent
  • GBOwner.owner_root

Optional but common:

  • GBLevelContext.maps
  • GBInjectorSystem.injection_roots
  • TargetingShapeCast2D.collision_mask

5) Let the injector wire the scene

Any node that implements resolve_gb_dependencies(container: GBCompositionContainer) will be injected automatically by GBInjectorSystem.

This includes core runtime nodes such as:

  • BuildingSystem
  • GridTargetingSystem
  • GridPositioner2D
  • TargetingShapeCast2D
  • ManipulationSystem
  • ManipulationParent
  • GBLevelContext
  • GBOwner
  • several shipped UI nodes

6) Start building through the system API

1
2
3
4
5
6
7
8

extends Control

@export var building_system: BuildingSystem

func _on_placeable_selected(placeable: Placeable) -> void:
    var report: PlacementReport = building_system.enter_build_mode(placeable)
    if not report.issues.is_empty():
        _show_build_error(report)

Why this matters:

  • it sets selected_placeable
  • it clears the previous preview
  • it resets the manipulation parent when needed
  • it switches mode to BUILD
  • it creates the new preview and rule setup

7) What happens after build mode starts

  • GridPositioner2D follows mouse/keyboard input and moves to tile centers
  • TargetingShapeCast2D updates the current target object
  • placement rules run against the active preview/indicators
  • confirm-build input or explicit build calls commit the placement

8) Common setup mistakes

  • missing GBLevelContext.target_map
  • missing GBLevelContext.objects_parent
  • missing GBOwner.owner_root
  • trying to place by mutating state directly instead of calling enter_build_mode(placeable)
  • forgetting to configure templates/actions inside GBConfig
  • expecting GridTargetingSystem to own mouse movement instead of GridPositioner2D

Next Steps