Start with the failure report and the Godot Output panel. Grid Placement is built to explain why a setup or placement is invalid — read the reason before trying to work around it.
Nothing responds to input
Check, in this order:
- is the plugin enabled?
- are the default input actions installed?
- does the host have an active/registered session?
- is your controller/device routed to that session?
- is a UI panel swallowing the input?
- is the targeting adapter/positioner active?
Quick test: hide the HUD and try again. If placement suddenly works, the fix is in your UI's mouse/input handling — not the placement code.
Placement does nothing because the host never started
auto_configure is off by default. A scene that assigns a PlacementSession to GridPlacementHost but leaves the box unticked has no composed services — nothing responds, and no service exists to report an error.
Check:
- is
auto_configureenabled onGridPlacementHost? With it off, the scene has to start the host itself:configure(),register_session(),bind_scene_consumers(),watch_scene_consumers(); - is
sessionactually assigned?auto_configureon with no session logs a warning and stays idle instead of failing silently; - if a controller configures the host and
auto_configureis on, that is not a double startup: a controller that configures first wins, because its_enter_treeruns before the host's_ready, so services are composed once.
See Session Ownership for both startup shapes.
Preview does not appear
Check:
- a valid
ScenePlacementEntryis selected; - its
packed_sceneactually exists; - the correct level surface/context is assigned;
- GRID/SMOOTH mode matches the selected workflow;
- the positioner/ray target is finding a point/cell to place at;
- the entry's footprint/configuration fits the selected mode.
SMOOTH entries need an explicit non-zero world footprint — a zero footprint gives the plugin nothing to show.
Object preview sits between tiles (half-cell offset)
If the cell indicator follows the grid but only the object art is offset, first check how the packed scene is authored and its cell_anchor_mode.
For centered artwork spanning whole cells, each axis uses the cell center for an odd cell count and the cell edge for an even cell count. The common reported case — centered 256×96 art on a 32px grid — uses CELL_CENTER_LEFT. Re-select the entry after changing the mode so the preview rebuilds.
See 2D Object Scene Setup for the authoritative anchor table, root-versus-child offset rules, collision alignment, and non-centered artwork cases.
Preview appears but commit fails
This usually means aiming works fine and validation is refusing the placement.
Read the placement report — it names the reason. The usual ones:
- the cell is occupied or something collides there;
- a custom rule or cost check failed;
- the entry is unavailable or locked;
- a GRID provider/mount conflict;
- a slope/support failure (3D);
- required physics support is missing;
- the world changed between preview and confirm.
Don't make commit skip its final validation just to match an earlier green preview — the check exists for a reason.
2D object targeting cannot find placed objects
For TargetingShapeCast2D:
- target object must be on a collision layer that the shapecast mask checks;
collide_with_areas/collide_with_bodiesmust match the target type;- avoid several nested nodes all claiming the same target layer if the intended root becomes ambiguous.
See Targeting Flow.
2D terrain preview/paint is wrong
Check:
- target is the intended
TileMapLayer; - for multi-layer levels,
mapslists every gameplayTileMapLayer(one-layer levels fall back totarget_mapautomatically); - selected terrain exists in that map's
TileSet; - coordinate conversions are not mixing local/global space;
- brush interaction matches the selected mode;
TerrainPreviewowns the preview layers;- generated region is below
max_terrain_brush_cells.
Brush reminder:
SINGLE: confirm one cell;- LINE/rectangles: drag then commit;
FLOOD_FILL: anchor/preview, second confirm commits.
This checklist covers 2D TileMapLayer painting. For 3D GridMap cells and rules, see 3D Terrain Painting.
3D CELL placement floats, sinks, or uses the wrong height
Check:
GridMapsurface scan range covers the terrain;- selected support mode matches the world setup;
- support/collision mask sees the intended ground when physics is enabled;
- preview and commit use the same support evidence;
surface_offset/entry overrides are intentional;- the supporting terrain is inside configured slope/height/planarity limits.
See 3D Surface & Slope Support.
3D structure cannot complete a wall/house
For CELL/EDGE/FACE/CORNER/TOP or SMOOTH-socket structures, inspect the first rejected piece:
- correct
snap_modefor the entry; - consumer
snaps_withaccepts the providerfamily; - intended provider actually exposes the required face/socket;
- canonical EDGE/FACE/CORNER key is not already occupied;
- CORNER has two perpendicular hosts when required;
- orientation/normal targets the intended side;
- preview and commit agree;
- removal actually freed the mount before re-placement.
A visually adjacent piece can still be invalid when its logical mount or provider relationship does not match the entry configuration.
3D slope placement rejects unexpectedly
Check:
- maximum slope threshold;
- minimum support ratio;
- center/edge support policy;
- height/planarity tolerance;
- entry-specific overrides;
PHYSICS_REQUIREDworld/mask/support collider setup.
A footprint with one unsupported corner may be valid for a permissive prop and invalid for a strict foundation. That behavior is configurable by policy.
Structures should remain world-up unless a prop explicitly opts into surface alignment.
SMOOTH placement overlaps or never snaps
Check:
- non-zero
footprint_2d/footprint_3d_world; - existing placement occupancy;
- optional obstacle mask;
- 3D ground/support ray if configured;
- socket provider role, consumer
snaps_with, snap radius, and whether the socket is already occupied.
Do not clear occupancy merely to make a target green; determine whether the existing committed record is stale or correctly blocking the target.
Move/rotate/demolish does nothing
Check:
- does the object opt into manipulation?
- is that operation enabled in the manipulation settings?
- can the object actually be targeted?
- is the destination valid and free?
- GRID/SMOOTH/mount occupancy must be updated through the manipulation path — moving the node directly skips all of that bookkeeping.
Save/load looks right but future placement breaks
Visual restoration is not enough. Check whether restore also rebuilt:
- stable placement IDs;
- GRID/SMOOTH occupancy;
- CELL/EDGE/FACE/CORNER/TOP mount occupancy and provider relationships;
- SMOOTH socket occupancy and provider relationships when used.
After restore, test a new placement, duplicate rejection, move/cancel, and remove/re-place.
See Save and Load.
2D world-facts rule never blocks
For PlacementWorldFactsProvider2D / ProviderCellBlockRule2D:
- provider is assigned to the active session's 2D targeting path;
- rule is attached at the intended settings/profile/entry scope;
- provider returns the expected blocked cell + reason;
- UI is showing the real placement report, not a separate check.
Web/export works in editor but not build
Check:
- required resources are included/exportable;
- important rule/settings resources are explicit
.tresresources where practical; - paths/case match exported files;
- exported addon/plugin enables cleanly;
- run an actual exported smoke, not only editor tests.
See Web Export.
Debug in this order
- Reproduce with the smallest entry/workflow that still fails.
- Read configuration/runtime issues.
- Verify session/context/target.
- Verify preview transform.
- Read placement validation/report reason.
- Inspect only the subsystem named by that reason: occupancy, mount, support, rule, physics, etc.
- Compare preview vs commit/restore state when the problem is parity-related.
This avoids “fixing” a targeting bug by weakening validation, or a stale occupancy bug by changing visuals.
Related guides
Using this in a game?
Grid Placement v6.3.2 — full source, playable demos, commercial license
The guide above is the same setup the shipped demos use. Try the build in your browser before you buy it.
Tutorials built on Grid Placement
- Godot multiplayer grid placement: one host, four sessions
- Godot 2D grid building system: paint, place, save
- Godot 3D grid building system: the runtime loop
- Godot 4 grid-building plugins: build mode vs editor tools
- 3D room placement in Godot: build rooms and stack storeys
- 3D grid placement in Godot 4: full setup tutorial
- Snap to a TileMap in Godot: 2D grid placement
- How to make a farming system in Godot
- How to snap objects to a 3D grid in Godot