Table of Contents

Use this page to follow the setup order shown in the walkthrough video. The transcript is the source of truth for the getting-started.html 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.

Version note: This guide is validated for Grid Placement 6.0.0. Class names were unified under the Placement prefix in 6.0.0. Legacy GB-prefixed aliases (e.g. GBLevelContext, GBOwner) still work but emit deprecation warnings and will be removed in 6.0.0.

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 PlacementLevelContext and PlacementOwner 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 (place 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 (or systems_isometric.tscn) scene from the templates. If you want to inspect the wiring more easily, make the scene local after adding it.

The GridPlacementHost is the main orchestrator node. It owns all RefCounted services (TerrainPlacementService, ManipulationService, GridTargetingService, BrushCoordinator, PlacementInputHandler, PlaceModeMachine) and has the single _unhandled_input entry point. The optional PlacementInjectorSystem is a convenience that auto-wires the host from a PlacementSession in editor-composed scenes. By default, it includes essential placement rules like CollisionsCheckRule (checks for blocking objects) and WithinTilemapBoundsRule (ensures placement on valid tiles).

5.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:

  • PlacementLevelContext on the level scene (e.g., your game map).
  • PlacementOwner on the player character.
  • The GridPositioner2D in the main scene to parent indicators and handle targeting.

Configure the important inspector fields:

  • PlacementInjectorSystem.session (or GridPlacementHost.configure(session) for code-built paths)
  • PlacementLevelContext.target_map
  • PlacementLevelContext.objects_parent
  • PlacementOwner.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 Placement Definitions and the First Test Object

Create a folder for your placement resources and add a Placeable resource (planned to be renamed to PlacementDefinition in 6.0) for the first object.

The walkthrough 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 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 PlaceRouterUI and PlaceableSelectionUI templates.

The PlaceRouterUI allows switching between Object Placement and Terrain Painting.

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 rule_check_indicator_16x16.tscn (or isometric variant) to match your tile size, then reassign it in the PlacementSession templates.
  • Add the PlacementActionLog and PlacementActionBar templates to the HUD for clearer feedback.
  • Apply a theme to the HUD (e.g., Cool Blue or Warm Earth theme included in templates).
  • Use place mode (hotkeys 1–4) to place objects and confirm that success and failure messages appear.
  • Add a TargetHighlighter child to the GridPlacementHost 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 placement selection UI with two player-facing tools: Object Placement and Terrain Painting.
  • A first object that can be selected and placed with the mouse.
  • The foundations for move, rotate, flip, and custom rule work.
  • An optional refund system that returns build costs when buildings are demolished.

9. Optional: Add Demolish Refunds

If you want players to get materials back when they demolish a building:

  1. Add a RefundSystem node to your Systems scene.
  2. Configure the RefundSystem with a refund_ratio (e.g., 0.5) and point the locator at your inventory bridge.
  3. See [Refund on Demolish](./refund-on-demolish.html for the full inventory-wiring guide.

Next Steps

  • [Architecture Overview](./architecture-overview.html
  • [Composition & Injection](./composition-and-injection.html
  • [Placement Workflow](./placement-workflow.html
  • [Web Export Guide](./web-export.html — if you plan to export to web.

9. Optional: Add Demolish Refunds

If you want players to get materials back when they demolish a building:

  1. Add a RefundSystem node to your Systems scene.
  2. Configure the RefundSystem with a refund_ratio (e.g., 0.5) and point the locator at your inventory bridge.
  3. See [Refund on Demolish](./refund-on-demolish.html for the full inventory-wiring guide.

Next Steps

  • [Architecture Overview](./architecture-overview.html
  • [Composition & Injection](./composition-and-injection.html
  • [Placement Workflow](./placement-workflow.html
  • [Web Export Guide](./web-export.html — if you plan to export to web.
Edit this page