Skip to content
ctChrisTutorials
Plugins
Menu

Grid Placement v6.0

Troubleshooting

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

Status
Current
Version
v6.0
Source updated
2026-09-04
Generated on
2026-09-06

Start with the failure/report and Godot Output panel. Grid Placement is designed to explain invalid setup or 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/CORNER 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:

  • 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;
  • CELL/EDGE/FACE/CORNER 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.