Getting Started

Use this page to follow the setup order shown in the 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.

\n**Version note: This guide is validated for Grid Building 5.0.8 (maintenance stable). If you are upgrading from 5.0.5, see the Patch Notes for changes.

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

  1. Unzip the plugin archive.
  2. Copy the addons folder into your project so the plugin ends up at res://addons/grid_building.
  3. Copy the templates folder into your project as well.
  4. Keep the plugin files together so the scene templates and scripts stay aligned.
  5. 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

  1. Open Project Settings → Plugins and enable the plugin.
  2. 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.).
  3. After setup completes, restart the editor so the Input Map UI reflects the new actions.
  4. 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 GBCompositionContainer (or alternative template) and drives the config, templates, and action names used by the runtime. By default, it includes essential placement rules like CollisionsCheckRule (checks for blocking objects) and WithinTilemapBoundsRule (ensures placement on valid tiles).

\n5.0.4 update: Templates now use project-agnostic collision layers (collision_mask = 1, apply_to_objects_mask = 1) so they work out-of-the-box in any project without demo-specific layer configuration.

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).
  • GBOwner on the player character.
  • The GridPositioner2D 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 64×64 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 GBActionLog and GBActionBar (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 Manipulatable component 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