Skip to content
ctChrisTutorials
Plugins
Menu

Grid Placement v6.1.0

Troubleshooting

Debug checks when placement, preview, terrain painting, or manipulation misbehaves.

Status
Current
Version
v6.1.0
Source updated
2026-09-24
Generated on
2026-09-23

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;
  • 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.