Troubleshooting

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.

Preview does not appear

Check:

• a valid ScenePlacementEntry is selected;
• its packed_scene actually 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_bodies must 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, maps lists every gameplay TileMapLayer (one-layer levels fall back to target_map automatically);
• selected terrain exists in that map's TileSet;
• coordinate conversions are not mixing local/global space;
• brush interaction matches the selected mode;
• TerrainPreview owns 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.

Terrain painting covers 2D TileMapLayer and 3D GridMap alike — see 3D Terrain Painting for the 3D rule model.

3D CELL placement floats, sinks, or uses the wrong height

Check:

• GridMap surface 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_mode for the entry;
• consumer snaps_with accepts the provider family;
• 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_REQUIRED world/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 .tres resources 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

1. Reproduce with the smallest entry/workflow that still fails.
2. Read configuration/runtime issues.
3. Verify session/context/target.
4. Verify preview transform.
5. Read placement validation/report reason.
6. Inspect only the subsystem named by that reason: occupancy, mount, support, rule, physics, etc.
7. 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

• Getting Started
• 2D Object Scene Setup
• Targeting Flow
• Validation
• Placement Rules
• 3D Object Placement
• 3D Surface & Slope Support
• Save and Load
• Web Export