Troubleshooting

Start with the failure/report and Godot Output panel. Grid Placement is designed to explain invalid setup/placement; do not bypass validation before reading the reason.

Nothing responds to input

Check:

• plugin enabled;
• default input actions installed;
• host has an active/registered session;
• intended controller/device is routed to that session;
• UI is not consuming the input;
• targeting adapter/positioner is active.

If hiding the HUD makes placement work, fix UI mouse/input handling rather than placement code.

Preview does not appear

Check:

• a valid ScenePlacementEntry is selected;
• packed_scene exists;
• correct level surface/context is assigned;
• GRID/SMOOTH mode matches the selected workflow;
• the positioner/ray target is resolving a point/cell;
• entry footprint/configuration is valid for the selected mode.

SMOOTH entries require an explicit non-zero world footprint.

Preview appears but commit fails

This usually means targeting works and validation is rejecting the action.

Read the placement report for:

• occupancy/collision;
• custom rule/cost failure;
• unavailable/locked entry;
• GRID provider/mount conflict;
• slope/support failure;
• missing required physics support;
• world changed between preview and confirm.

Do not make commit skip final validation to match an earlier green preview.

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;
• 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 is 2D only in the 6.0 contract.

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/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 key is not already occupied;
• orientation/normal targets the intended side;
• preview and commit agree;
• removal actually freed the mount before re-placement.

A visually adjacent piece is not enough if its logical mount/provider contract is incompatible.

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

• object opts into manipulation;
• requested operation is enabled in manipulation settings;
• object can be targeted;
• destination is valid/available;
• GRID/SMOOTH/mount occupancy is updated through the manipulation path, not direct transform mutation.

Save/load looks right but future placement breaks

Visual restoration is not enough. Check whether restore also rebuilt:

• stable placement IDs;
• GRID/SMOOTH occupancy;
• EDGE/FACE/socket occupancy/provider relationships.

After restore, test a new placement, duplicate rejection, move/cancel, 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
• Targeting Flow
• Validation
• Placement Rules
• 3D Object Placement
• 3D Surface & Slope Support
• Save and Load
• Web Export