Grid Placement

Integration Guide (5.1 GDScript)

Goal

Get a minimal 5.1 scene running where:

  • The addon loads from res://addons/grid_building.
  • Your scene drives the runtime through a small set of entry points.
  • The backend logic remains traceable via the runtime chain (nodes → workflows → services → state).

What this page assumes (and does not assume)

  • Assumes: you are using Godot 4.x and the 5.1 GDScript addon.
  • Does not assume: you are using the 6.0 C# port.

If you are adopting 6.0, start at:

Install the addon

  • Ensure the addon folder exists in your project at:
    • res://addons/grid_building/
  • Enable the plugin in:
    • Project → Project Settings → Plugins

Notes:

  • The docs are branded GridPlacement (5.1+), but the addon folder name remains grid_building for backward compatibility.

The stable 5.1 pattern is:

  • Your gameplay node(s) talk to a composition container / registry.
  • Input is routed through GPInputService into input adapters.
  • Orchestrators produce GBOrchestratorOutput which is interpreted by GPEffectApplier.

Conceptually:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

Your scene node
  ↓
Composition container / registry
  ↓
Input adapters → workflow orchestrators
  ↓
GBOrchestratorOutput
  ↓
GPEffectApplier (signals)
  ↓
UI / preview / scene mutation

Practical “start here” files

These are good starting points when reading the demo wiring:

  • demos/grid_building_dev/godot/demos/shared/world/world.gd
  • demos/grid_building_dev/godot/addons/grid_building/resources/gb_composition_container.gd

Entry points you should treat as stable

In 5.1, stability means: keep your project code calling a small set of node-shaped APIs and avoid reaching deep into internal helpers.

Recommended entry points:

  • Mode switching via a mode service resolved from the container/registry.
  • Input routing through GPInputService.
  • Placement / manipulation through workflow orchestrators (usually reached via adapters).
  • Visual application through GPEffectApplier (interpret outputs, emit signals).

Debugging checklist (fast)

When something “does nothing”, trace in this order:

  1. Confirm the plugin is enabled and res://addons/grid_building/plugin.cfg is present.
  2. Confirm your scene resolves the container/registry.
  3. Confirm GPInputService is receiving events.
  4. Confirm the relevant input adapter is active.
  5. Confirm the orchestrator emits GBOrchestratorOutput.
  6. Confirm GPEffectApplier is connected and applying effects.

For the detailed chain (with examples), see: