Troubleshooting

Historical 5.x guide. This page describes a legacy API and is not current integration guidance. For new projects, start with Getting Started.

GridBuilding 5.0.12 troubleshooting is mostly about understanding the maintenance wiring patterns:

• injector/container composition
• state-first signal flows
• preview/targeting interactions

If your issue involves targeting previews being cleared unexpectedly, see:

• Targeting Flow (5.0.12)

Selecting a placeable exits build mode

This is the most common first-setup failure on 5.0.12.

What you see: you press 2 to open build mode, click a placeable in the list, and the UI closes as if you pressed Escape. Output shows Mode changed -> 2 then Mode changed -> 0 and Clearing selected placeable on mode change to OFF.

What it is: the list click did call BuildingSystem.enter_build_mode(). Readiness failed, so 5.0.12 forces mode OFF and clears the selection. It is not a broken placeable scene by itself, and it is not a missing LevelBuildingContext node. That name is leftover wording inside GBLevelContext.

Unfilter the Output panel. The warnings from is_ready_to_place() are the useful ones:

Warning	Fix
No placer set in _owner_context	Add GBOwner on the player/controller and assign owner_root
No placed parent set	Assign GBLevelContext.objects_parent and make sure that node is injected
Property [target_map] is NULL / [maps] is empty	Assign GBLevelContext.target_map and maps

GBLevelContext can live under a sibling of Systems (for example GB_References). That is fine when Injection Roots is empty (the shipped systems.tscn default). If injection_roots is set to Systems only, the sibling context is never applied.

Do not rearrange a working placeable scene until those warnings are gone. See Getting Started for the required inspector fields.

Object preview sits between tiles (half-cell offset)

What you see: the cell indicator follows the grid correctly, but the object preview appears offset by about half a cell (16px on a 32×32 grid), "stuck between tiles".

What it is: GridBuilding seats the object scene's root node relative to the targeted tile — TileMapLayer.map_to_local() returns the tile center in Godot 4.x, and Placeable.cell_anchor_mode decides how the root uses it (CELL_CENTER unless changed). If the artwork is not centered on that root (a Sprite2D with centered = false, or a sprite position shifted away from (0, 0)), the visuals land half a cell off. If the artwork is lattice-authored across whole cells instead, the anchor mode is wrong for its cell count, not the scene.

Fix:

1. Open the object's .tscn.
2. Select the Sprite2D, set centered = true (default) and position = (0, 0).
3. Use the sprite's offset property for deliberate anchors (tree trunk, door hinge) instead of moving the root or position.
4. If the art spans cells, set Placeable.cell_anchor_mode from its cell count per axis — odd × odd CELL_CENTER, even × even CELL_TOP_LEFT, even × odd CELL_CENTER_LEFT, odd × even CELL_TOP_CENTER — or leave it on INHERIT and set the game-wide BuildingSettings.default_cell_anchor_mode.
5. Re-enter placement and confirm the preview seats flush in the cell.

See the anchor requirement in Getting Started.

5.0.12-specific checks

Move fails with “not movable”

In 5.0.12, try_move() enforces is_movable() before move starts.

• Verify the target has a valid Manipulatable component.
• Verify its settings allow movement (movable = true).
• If needed, customize ManipulationSettings.failed_object_not_movable for clearer UX.

Rotation / flip not preserved after move

5.0.12 preserves accumulated transform on successful placement. If this still appears broken:

• Verify your placement flow uses try_move(...) followed by try_placement(...).
• Verify no custom script resets transform after placement.
• Verify your test/object is not being replaced by unrelated scene logic after placement.

Save data contains temporary preview objects

In 5.0.12, preview/manipulation copies are marked with gb_preview metadata on the parent node.

• When saving, skip any placed object whose parent/root has gb_preview metadata.
• Query placed components by PlaceableInstance.group_name.

# Skip preview objects when saving
var parent_node= placed_component.get_parent()
if parent_node!= null and parent_node.has_meta("gb_preview"):
    continue  # Skip this object

---

Validated By

This guide's troubleshooting patterns are validated by diagnostic logs and test scenarios found in:

• res://addons/grid_placement/test/e2e/all_systems_integration_tests.gd — General troubleshooting for wiring and system interactions.
• res://addons/grid_placement/test/integration/grid_positioner_rotation_integration_test.gd — Troubleshooting transform/rotation persistence issues.
• res://addons/grid_placement/test/utilities/data/composition_container_subresources_test.gd — Troubleshooting configuration and resource loading errors.