Troubleshooting (6.0)

This page covers common 6.0 runtime issues and where to inspect first.

Validation always fails

• Verify entity has PlaceableComponent, GridPositionComponent, and PlacementRequestComponent.
• Ensure placeable template includes a valid collision shape when collision rules are enabled.
• Inspect request.get_validation_issues() for exact failure reasons.

Preview not visible or unstable

• Confirm PlacementComponent.is_placing remains true.
• Confirm request is active and target position is updating.
• Verify scene contains cursor/manipulation parent structure used by preview reparenting (Cursor2D + ManipulationParent).

Placement never executes

• Ensure request reaches a successful validation result before execution.
• Confirm PlacementExecutionSystem is added to world.
• Check for lockouts: placement_attempts / is_placement_locked in PlacementComponent.

Save/load mismatch

• Persist GECS-serialized entities/components instead of ad-hoc node state.
• Keep persistent fields as @export component properties.
• Re-test with integration patterns from serialization tests.

Manipulation actions don’t apply

• Ensure manipulation systems are registered in runtime (Movement, Rotation, Placement, Removal).
• Confirm entity has ManipulationComponent and required supporting components.
• Test with ManipulationSystem.try_move/try_rotate/try_place/try_demolish to isolate UI wiring issues.

Start here for deeper context

• Architecture overview (6.0)
• Validation and Rules
• Save, Load, and History
• Events and UI Integration