Getting Started (6.3)

Development docs. This page describes the unreleased 6.3 build.

The shortest supported path from the download to one object placed with your own content. Every menu label and Inspector field below exists in the shipped addon; nothing here needs a demo scene from the repository.

This page describes the 6.3 line. The published 6.2 guide stays accurate for 6.2 projects; the difference is who places: the session owns the placer in 6.3, and no new setup needs a PlacementOwner node.

Before you start: Godot 4.5 or later, GDScript (the addon has no C# port).

1. Extract the archives

Your download contains three archives. Two of them are for this path:

Archive	Extract it so these paths exist	Needed for
plugin.tar.gz	addons/grid_placement/	Always. This is the addon.
templates.tar.gz	templates/grid_placement_templates/	The starter UI (Setup UI) and starter scenes. Skip it only if you supply your own panel.
demo.tar.gz	any folder, imported as its own Godot project	Learning only. It is not a dependency of your project.

Extract both into the project root — the folder that holds project.godot — so addons/ and templates/ sit beside it. Then enable the addon: Project → Project Settings → Plugins → Grid Placement → Enable.

templates/ is not inside addons/. A missing starter UI is therefore a missing archive, not a broken addon: Setup UI names that archive and the destination it expects when the panel template is absent.

2. Add the input actions

Project → Tools → Grid Placement → Setup Default Input Actions.

The dialog lists what it created and what it kept, and says whether an editor restart is needed. If it created actions, restart the editor so Project Settings → Input Map shows them.

The defaults you will use first:

Input	Action
2	Place (build) mode
1	Info mode
4	Demolish mode
Esc	Off
Left click	Confirm / place
R / T	Rotate left / right
F / G	Flip horizontal / vertical
E	Pipette (copy the object under the cursor)
Arrow keys, C	Move the cursor, re-centre it

3. Setup Scene

Open the scene you want to place in, then Project → Tools → Grid Placement → Setup Scene → Top-down 2D (or Platformer, Isometric, Hex, 3D).

Setup Scene builds the rig and nothing else. It adds or reuses:

Node	Job
GridPlacementHost	Owns placement input and dispatch, composes the placement services.
World	Container for the level surface, the placed objects and the cursor.
TargetMap (TileMapLayer) or TargetMap3D (GridMap)	The surface you place on. An existing one in the scene is reused, not duplicated.
Objects	Parent that receives every committed object.
PlacementLevelContext	Points at the surface (target_map / target_map_3d) and at objects_parent.
GridPositioner2D / GridPositioner3D	Turns the pointer into a target cell.
Camera2D (2D) / Camera3D (3D, child of the positioner)	The camera the pointer is projected through. An existing camera is adopted; one is added only when the scene has none.

It also writes the starter resources beside your scene, in <scene folder>/grid_placement/:

• session_<type>.tres — the PlacementSession (the host points at it),
• catalog_<type>.tres — the PlacementCatalog (your entries live here),
• bundle_<type>.tres — settings and the terrain palette,
• terrain_<name>.tres — one per terrain your surface exposes.

If the scene has not been saved yet, there is no folder to write beside, so the resources go to res://grid_placement/ and the report says so. Save the scene (Ctrl+S) and run Setup Scene again to move them next to it.

The 2D camera matters: 2D aims the pointer through the current Camera2D. If you delete it or disable it, nothing places — Validate Current Scene Setup reports that as an error.

4. Setup UI

Project → Tools → Grid Placement → Setup UI.

This adds (or reuses) a UI CanvasLayer with:

• PlacementPanel — the PLACEMENT panel: route switcher, entry selection, terrain palette,
• PlacementActionLog — what happened and why a placement was refused,
• TargetInformer — the target cell/object under the cursor,
• ModeSwitchBar — Info / Build / Move / Demolish.

The panel is bound to the session the rig already uses. A dialog that says incomplete delivered no usable panel: read its Needs config and Next step lines before clicking anything in the scene.

Order matters. Setup UI before Setup Scene produces a panel with no session to show; the report says to run Setup Scene first.

5. Bring your own content

The plugin does not invent a level or an object. Two things are yours:

A surface with ground. Give TargetMap a TileSet and paint tiles, or give TargetMap3D a MeshLibrary and paint GridMap cells. An unpainted surface is not an addon error — it is an empty level, and the validator reports it as optional content with the next step "paint the surface".

One entry.

1. Author the object as its own scene (Node2D root for 2D, Node3D for 3D) with a shape. A bare sprite has no footprint, so the plugin cannot tell two of them apart in the same cell and both commits succeed; a CollisionShape2D (2D) or a mesh plus collision/footprint (3D) is what makes the occupied-cell refusal work.
2. Create a ScenePlacementEntry resource: set display_name, assign packed_scene, and add one PlacementProfile to profiles (set its display_name). The profile is what puts the entry under a category tab in the panel — an entry with no profile has no tab and is invisible.
3. Add the entry to the catalog: select catalog_<type>.tres (or the session's catalog) in the Inspector and append it to scene_entries.

The panel lists catalog entries when a catalog is wired. scene_entries_folder on the panel is the no-catalog fallback only: with a session catalog assigned, the folder scan is skipped, so putting entries in a folder and leaving the catalog empty shows nothing.

Categories behave the same way: with nothing authored, the panel derives one tab per profile the listed entries use. An authored category_profiles list on the panel is a filter, not a seed — the tabs are the entries on show, so dropping a profile is how a project hides that content, and category_groups narrows the tabs further without adding any.

If you add entries from code at runtime, call rebuild() on the panel's SceneEntrySelectionUI afterwards; the panel does not poll the catalog. A catalog append alone leaves the tabs as they were.

Or start from a working one. The archive ships two optional samples under addons/grid_placement/examples/ — minimal_2d/ and minimal_3d/ — each a shaped scene, a profiled ScenePlacementEntry and a one-entry catalog. They are consumer-owned: copy one, point your rig at its catalog, or delete the folder. They are not a dependency of the addon and contain no game content.

6. Your first placement

1. Run the scene.
2. Press 2 (Place mode) or click Build on the mode bar.
3. Click your entry in the panel.
4. Move the pointer over painted ground. A preview follows the cursor, and the target informer shows the cell.
5. Left click to commit. The object appears under Objects.

Save, reopen, run again: the same rig, session and catalog come back, and the placed object is part of the scene you saved. Continue placing.

7. What a refusal looks like

A refused placement changes nothing and writes a reason to the action log — for example an occupied cell, a cell with no surface underneath, or a rule your entry's profile declares. The typed reason is also on the PlacementReport, which is what tests and game code read.

In 2D, an unpainted cell inside a tiled surface is legal by default: occupancy and your entry's rules decide what is refused, not a painted-ground requirement. Paint the ground because it is your level, not because the plugin demands it.

If a click seems to do nothing at all, check, in this order:

1. Validate Current Scene Setup — the first three lines are Rig configured, Available workflows, Ready to place, followed by the detailed [ERROR] / [OPTIONAL] list and a single Next step.
2. Mode — Off (Esc) and Info (1) do not place.
3. A full-screen Control with mouse_filter = STOP swallowing the click; the validator names it.
4. No Camera2D (2D) or an empty GridPositioner3D.camera (3D).

8. 3D in one breath

Same two menu actions, different surface:

1. Setup Scene → 3D. It reuses a GridMap already in the scene, else adds TargetMap3D, wires PlacementLevelContext.target_map_3d, and assigns a Camera3D to GridPositioner3D.camera. If the scene has no camera it adds an overview one under World (not under the cursor, which moves to the hovered cell), looking at the origin from above; move or replace it like any camera.
2. Assign a MeshLibrary to that GridMap and paint ground cells. Object placement works with no terrain entries in the catalog; that note is optional content, not a setup error.
3. Author a Node3D entry — mesh, collision, and one PlacementProfile — and add it to the catalog exactly as in 2D.
4. Setup UI, then place.

Mounting (CELL/EDGE/FACE/CORNER/TOP), GRID vs SMOOTH and support rules are covered in 3D Object Placement and Grid vs Smooth. They are refinements of a working first placement, not prerequisites.

9. Hand-wired setup (advanced)

If your game owns session lifetime — split-screen, devices, save/load-created sessions — skip Setup Scene and compose the rig yourself: GridPlacementHost, PlacementSession, PlacementLevelContext, GridPositioner2D/3D, then call host.configure(session), host.register_session(...) and host.bind_scene_consumers(...) from your controller. Keep auto_configure off in that shape. No PlacementOwner node is needed in either shape; a 6.2 scene that still has one keeps working — see Migrating from PlacementOwner.

10. Where to read next

• Placer Ownership — where the acting placer lives and which value wins.
• Actor-Free Placement — placing with no player.
• Placement Workflow — preview → validate → commit → manipulate → demolish.
• Troubleshooting — the long form.