Grid Placement reports two different kinds of problems:
- Configuration/readiness problems — the runtime is not wired correctly.
- Placement failures — the runtime is healthy, but the requested target/action is not allowed.
Treat them differently. Disabling placement rules will not fix a missing session/context, and fixing setup warnings will not make an occupied EDGE mount valid.
Project/setup checks
After installing the addon:
- Enable Grid Placement in Project Settings → Plugins.
- Install the default input actions from the plugin Tools menu.
- Restart/reload the editor.
- Confirm the intended host/session/context/owner wiring exists.
- Run the smallest placement path before adding advanced systems.
GridPlacementHost.is_ready() / runtime issue reporting can help diagnose setup after the required scene/context nodes have entered the tree.
Common configuration failures:
- no active/registered
PlacementSession; - missing level target/object parent;
- missing placement owner;
- missing/incorrect targeting adapter;
- required settings/resources not assigned;
- wrong dimension/surface configuration.
Placement validation
Once setup is valid, each placement workflow owns its correctness checks.
| Workflow | Examples of placement failures |
|---|---|
| 2D object | outside valid map area, collision/occupancy, custom rule/cost failure |
| 2D terrain | invalid terrain target/brush cell, paint gate failure |
| 3D GRID | occupied footprint, invalid or occupied EDGE/FACE/CORNER/TOP mount/provider, slope/support failure |
| SMOOTH | missing footprint, world-space overlap, optional physics/ground/socket failure |
| Manipulation | destination invalid/occupied or operation disabled for the object |
Final validation runs again at commit. A preview that was valid earlier can become invalid if the world changes.
Placement reports
For user-facing attempts, prefer the report/result surface produced by the placement action. The UI should display its issues rather than reconstructing the validator.
Use cell/indicator-level results only when the workflow actually needs per-cell feedback, such as 2D multi-cell previews.
For 3D, preserve typed reasons such as support/slope/mount failure rather than collapsing every rejection into a generic occupancy error.
Configuration vs placement examples
| Problem | Type |
|---|---|
PlacementLevelContext has no target surface |
Configuration |
| UI consumed input before the positioner received it | Configuration/input |
| A 2D object overlaps an existing object | Placement |
| EDGE/TOP mount is already occupied | Placement |
| CORNER is missing its required host topology | Placement |
| 3D slope exceeds the configured maximum | Placement |
PHYSICS_REQUIRED cannot evaluate support |
Placement/support configuration result; fail closed |
| SMOOTH placeable has no footprint | Entry configuration exposed as placement failure |
Do not hide failures
Avoid “fixes” that make the plugin continue without enough information:
- do not make missing required context silently succeed;
- do not treat missing physics evidence as valid in a physics-required mode;
- do not ignore occupancy because a visual preview looks clear;
- do not bypass final validation from UI/game code.
Fail with an actionable message instead.
Export readiness
Before release/export, validate using the actual packaged addon/resources. External .tres resources are generally easier to inspect and more reliable across export paths than relying on fragile implicit/embedded setup.
See Web Export for browser-specific checks.