Getting Started

Use this page to follow the setup order shown in the 5.0.3 walkthrough video.

The transcript is the source of truth for the getting-started flow. The order matters because the plugin expects the addon, templates, default actions, scene wiring, and UI to be in place before the first placement test.

For buyers and installers

If you downloaded the plugin to add it to a project, this is the minimum path:

  • copy the addons folder into your project so the plugin ends up at res://addons/grid_building
  • copy the templates folder if you want the shipped starter scenes and UI pieces
  • enable the plugin in Godot
  • let the plugin add its default input actions
  • wire GBLevelContext and GBOwner into your own scene

What you do not need for the first successful placement:

  • a custom build pipeline
  • a custom state framework
  • a full demo project copy

The demo archives are useful as reference material, but they are optional if you only want to consume the plugin in your own project.

1. Install the plugin archive and templates

  • Unzip the plugin archive.
  • Copy the addons folder into your project so the plugin ends up at res://addons/grid_building.
  • Copy the templates folder into your project as well.
  • Keep the plugin files together so the scene templates and scripts stay aligned.
  • If you want a complete reference setup, start from one of the demo archives from the video.

2. Enable the plugin and set up input actions

  • Open Project Settings -> Plugins and enable the plugin.
  • Open Project -> Tools and click Grid Placement/Setup Default Input Actions.
    • This registers the 16 default placement actions (build mode, confirm/cancel, rotate, flip, etc.).
    • After setup completes, restart the editor so the Input Map UI reflects the new actions.
  • Open Project Settings -> Input Map to verify the actions were registered.

3. Drop in the starter systems scene

Drag in the systems.tscn scene from the templates.

If you want to inspect the wiring more easily, make the scene local after adding it.

The GBInjectorSystem is the main wiring node. It owns the TDCompositionContainer (or alternative template) and drives the config, templates, and action names used by the runtime. By default, it includes essential placement rules like CollisionCheckRule (checks for blocking objects) and WithinTileMapBoundsRule (ensures placement on valid tiles).

4. Wire the level context and player nodes

Add the runtime scene nodes shown in the video:

  • GBLevelContext on the level scene (e.g., your game map)
  • GBOwnerNode on the player character
  • The PositionerStack (or PositionerStackIsometric) in the main scene to parent indicators and handle targeting

Configure the important inspector fields:

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

The level context should point at the ground tilemap layer (target_map) and the Node2D that will act as the parent for spawned instances (objects_parent).

The positioner should be adjusted to match your tile size. For example, for 64x64 tiles, you can duplicate the positioner scene, increase its sprite scale by four, and optionally set project rendering to Nearest for pixel art.

5. Create placeables and the first test object

Create a folder for placeables and add a Placeable resource for the first object.

The transcript uses a bush as the example:

  • assign an icon (e.g., bush graphic)
  • add a CategoricalTag resource (e.g., foliage) and save it to a tags folder for reuse
  • create the actual bush scene (PackedScene) with a Sprite2D
  • add a collision shape (e.g., Area2D or StaticBody2D) on the correct collision layer (e.g., layer 1 or 10) so the collision rule evaluates properly

The guide assumes your placeable tags and scenes live in clean folder structures (e.g., placement/tags and placement/placeables) so the selection UI can discover them automatically.

6. Add the UI and verify the first placement

Set up the UI with:

  • a CanvasLayer
  • a Control node for the HUD (Important: set Mouse Filter to Ignore so it doesn’t block game input)
  • the PlaceableSelectionUI template

Assign your tags folder and placeables folder to the selection UI parameters in the inspector.

Then run the scene:

  • the foliage tag should appear
  • you should be able to select the bush
  • left click should place it successfully

7. Add the finishing pieces from the video

After the first placement works, apply the rest of the walkthrough setup:

  • add collision shapes and set collision layers so the collision check rule can work
  • duplicate and customize the IndicatorTemplate to match your tile size, then reassign it in the GBInjectorSystem templates
  • add the ActionLog and ActionBar (hotbar) templates to the HUD for clearer feedback
  • apply a theme to the HUD (e.g., Warm Earth theme included in templates)
  • use build mode (hotkeys 1-4) to place objects and confirm that success and failure messages appear
  • add a TargetHighlighter child to the GridTargetingSystem for visual feedback in move mode
  • add a ManipulatableNode to objects that should support move, rotate, or flip operations
  • configure ManipulatableSettings (rotatable, flip horizontal/vertical, movable, demolishable) for your scenes

8. What the setup should give you

At the end of the walkthrough you should have:

  • a working addon install under res://addons/grid_building
  • default input actions loaded into the project
  • a wired level context and owner context
  • a placeable selection UI backed by folder-based placeables and tags
  • a first object that can be selected and placed with the mouse
  • the foundations for move, rotate, flip, and custom rule work

Next steps