Getting Started

Use this page when you have downloaded Grid Placement and want to place your first object in your own Godot project.

Version note: This guide is for Grid Placement 6.0.0 on Godot 4.5.0 through 4.7. The supported buyer-facing setup path here is 2D placement on TileMapLayer. New projects should use the Placement* / GridPlacement* class names. Legacy Grid Building / GB* names are compatibility shims only where they still exist.

If you need the release-support boundary before you start, see 6.0 Surface and Brush Reference. It lists the shipped demos, supported vs advanced/deferred surfaces, terrain/object brush modes, and PlacementSettings.max_terrain_brush_cells.

What You Are Building

By the end, you should have:

• The plugin enabled under res://addons/grid_placement.
• Default input actions installed.
• A GridPlacementHost in your scene.
• A PlacementSession connected to the host.
• A PlacementLevelContext pointing at your ground TileMapLayer and object parent.
• A PlacementOwner on the player or placer node.
• A GridPositioner2D tracking the target cell.
• A simple placeable scene that can be selected and placed.

You do not need a custom inventory, a custom save system, or a full demo-project copy for the first successful placement.

1. Install the Plugin

1. Unzip the plugin archive.
2. Copy addons/grid_placement into your project.
3. Copy templates/grid_placement_templates if you want the starter scenes and UI pieces.
4. Open Godot.
5. Enable Grid Placement in Project Settings -> Plugins.
6. Run Project -> Tools -> Grid Placement / Setup Default Input Actions.
7. Restart the editor so the Input Map and plugin state refresh cleanly.

Quick check: after restarting, Project Settings -> Input Map should contain the placement actions created by the tool menu.

2. Add the Starter Systems Scene

For a beginner setup, start with the shipped systems template instead of hand-building every node.

Use a starter scene such as:

• templates/grid_placement_templates/systems.tscn
• templates/grid_placement_templates/systems_isometric.tscn if you are intentionally using the isometric starter path

The important runtime node is GridPlacementHost. It receives placement input and dispatches placement work through a PlacementSession.

Beginner mental model:

GridPlacementHost = the runtime coordinator
PlacementSession = the current player/controller placement state
GridPositioner2D = the cursor/target cell tracker
PlacementLevelContext = the level's target map and object parent
PlacementOwner = the player/controller that owns the placement action

If you make the starter scene local after adding it, you can inspect the wiring directly in the editor.

3. Wire the Level

Add PlacementLevelContext to the level scene, usually near your map/world root.

Assign these inspector fields:

Common beginner mistake: target_map is the tilemap you click against. objects_parent is the node that receives placed object instances. They are not the same thing.

4. Wire the Player or Placer

Add PlacementOwner to the player, controller, or placer node.

Assign:

Add or instance GridPositioner2D for the human-controlled targeting cursor. The positioner is the node that follows the grid cell under the cursor/controller and feeds targeting state to the session.

If your tiles are larger than the starter template, scale or customize the positioner visuals so the preview matches your tile size. For example, a project using 64x64 tiles should not keep a tiny 16x16-looking positioner sprite unless that is intentional.

5. Configure the Session

A PlacementSession is the per-player/per-controller state object. It holds the selected object or terrain, targeting state, action names, logger, settings, and contexts.

For editor-composed scenes, the starter templates normally wire this through PlacementInjectorSystem.session.

For code-built scenes, call:

host.configure(session)

For per-controller setups, register the controller/session with the host:

host.register_session(controller_node, session, device_id)

Use device_id only when you need per-device input routing. For a basic single-player mouse setup, the default/single session path is enough.

6. Create the First Placeable Object

Create a simple object scene, such as a bush, crate, or building foundation.

Minimum recommended scene shape:

BushRoot (Node2D)
- Sprite2D
- StaticBody2D or Area2D
  - CollisionShape2D

Then create a ScenePlacementEntry resource for it:

1. Set packed_scene to your object scene.
2. Add a display name/icon if your UI uses them.
3. Assign one or more PlacementProfile resources if you want category behavior, supported tools, or profile-level rules.
4. Add placement rules only when you need extra checks beyond the starter rules.

For collision-based validation and manipulation targeting, the placed scene must have sensible collision layers. If placement fails with no obvious reason, check collision layers before rewriting plugin code.

7. Add the UI

Use the shipped UI templates for the first pass:

• PlaceRouterUI — switches between object placement and terrain painting.
• PlaceableSelectionUI — displays/selects placeable object entries.
• TerrainPaletteUI — displays/selects terrain entries when terrain painting is used.
• PlacementActionLog / PlacementActionBar — optional feedback and action controls.

Put the UI under a CanvasLayer.

Important: large full-screen Control nodes can block mouse input. For HUD panels that should not capture placement clicks, set Mouse Filter to Ignore or Pass. Only buttons and interactive UI controls should consume clicks intentionally.

8. Run the First Placement Test

Run the scene and check this order:

1. The UI appears.
2. A profile/placeable entry appears.
3. Selecting the entry creates or enables a preview.
4. Moving the cursor updates the target cell.
5. Confirming placement adds an object under PlacementLevelContext.objects_parent.
6. The Output panel has no missing-context warnings.

If any step fails, check the Output panel and the Troubleshooting guide before changing code.

Most first-run issues are one of these:

• Plugin was not enabled.
• Default input actions were not installed.
• PlacementLevelContext.target_map is empty.
• PlacementLevelContext.objects_parent is empty.
• PlacementOwner.owner_root is empty.
• The positioner is not inside the active session/injection scope.
• A UI Control is consuming clicks meant for placement.
• Collision layers do not match the placement or targeting rules.

9. Optional: Terrain Painting

For terrain painting, add one TerrainPreview node under the same injected scene scope as the host and target map.

You do not need to add preview layers manually. TerrainPreview creates and manages its own runtime preview layers.

Terrain painting works through terrain entries/palettes and the active session's selected terrain. Start with a single terrain entry before adding brush shapes or multiple palettes.

Terrain brush input flow:

Large brush operations are capped by PlacementSettings.max_terrain_brush_cells (default 4096, hard ceiling 16384). See 6.0 Surface and Brush Reference for the full matrix.

10. Optional: Manipulation and Refunds

To allow placed objects to be moved, rotated, flipped, or demolished:

1. Add a Manipulatable component to the object scene.
2. Configure ManipulatableSettings for the operations the object supports.
3. Make sure the object can be detected by the targeting shapecast/layers.

To refund materials when an object is demolished:

1. Configure RefundService through the supported service/template path.
2. Set refund_ratio, such as 0.5 for half refund.
3. Point the service at your inventory/container bridge.
4. See Refund on Demolish for the full inventory-wiring guide.

Refund support expects an id-keyed inventory bridge. The demo inventory is only a prototyping example.

Demo Node Naming

The shipped demos are also documentation examples. Demo nodes that demonstrate a plugin class_name should use that class name as the node name unless a documented exception exists.

This keeps screenshots, videos, guides, and scene-tree inspection aligned for beginners.

Next Steps

• Placement Workflow
• 6.0 Surface and Brush Reference
• Choosing Terrain vs Objects
• Placement Rules
• Manipulation: Service vs Parent
• Refund on Demolish
• Troubleshooting
• Web Export Guide