Troubleshooting & FAQ (5.0)

Comprehensive troubleshooting guide and FAQ for GridBuilding 5.0

v5.0.0 has several critical gotchas and complex setup requirements. This FAQ covers the most common issues and setup complexities.

Critical Setup Issues

❌ Systems Not Running at All

Q: Why aren’t any systems working? A: You’re missing the LevelContext node. Without a properly configured LevelContext, ALL systems fail.

Immediate Checklist:

  • Do you have a GBLevelContext node in your level?
  • Is target_map assigned to your TileMapLayer?
  • Is maps array populated with your TileMapLayers?
  • Is objects_parent assigned to where buildings should spawn?

See: Level Context Integration - this is the #1 cause of complete system failure.

❌ Resources Not Working

Q: Why are my settings/resources not being applied? A: Resources must be manually assigned and saved. There is NO automatic assignment in 5.0.

Critical Steps:

  1. Create each resource manually (GBCompositionContainer, GBConfig, GBSettings, etc.)
  2. Save each resource immediately after creation
  3. Assign each sub-resource manually in the Inspector
  4. Save the parent resource after assigning sub-resources

Common Mistakes:

  • Creating resources but not saving them
  • Assuming automatic resource assignment occurs
  • Forgetting to assign individual settings (building, manipulation, targeting, etc.)

See: Composition Container Configuration

Architecture Gotchas

🔄 Signal vs State Confusion

Q: Why are my signals carrying state objects instead of data? A: This is the 5.0 architecture - state objects emit signals and listeners access state directly.

5.0 Pattern:

1
2
3

# State object emits signal AND maintains state
targeting_state.target_changed.emit(new_position)
# Listeners access targeting_state.current_target directly

This is normal for 5.0 but different from 5.1/6.0 which use EventData payloads.

🏗️ System vs Node Responsibilities

Q: Should I put logic in nodes or systems? A: 5.0 splits this specifically:

  • Systems: Handle business logic, validation, state management
  • Nodes: Handle visual transforms, input processing, scene hierarchy
  • Input: Keyboard/mouse handled by nodes, building logic by systems

Example: GridPositioner2D handles input toggling, BuildingSystem handles placement logic.

Node Hierarchy Issues

🎯 GridPositioner Hierarchy

Q: Why isn’t my grid targeting working? A: Check the GridPositioner hierarchy:

GridPositioner2D (Top of stack)
├── TargetingShapeCast2D (Child)
└── ManipulationParent (Child)
    └── IndicatorManager (Grandchild)

Common Issues:

  • TargetingShapeCast2D not enabled (check input toggling)
  • Wrong collision mask (should be 2048)
  • ManipulationParent missing (no visual feedback)

🔄 Manipulation Setup

Q: Why can’t I rotate or flip objects? A: Objects need a Manipulatable child node:

YourPlaceableObject
├── Sprite2D
├── CollisionShape2D
└── Manipulatable (Node) ← Required for rotation/flip
    └── script: manipulatable_marker.gd

Without this node, objects cannot be manipulated regardless of settings.

Resource Assignment Nightmares

💾 Data Loss Prevention

Q: Why did I lose all my resource configuration? A: You didn’t save resources immediately after creation.

Safe Workflow:

  1. Create resource
  2. Save immediately (Ctrl+S)
  3. Assign to parent
  4. Save parent resource
  5. Test in Inspector
  6. Commit to version control

Recovery: Check Godot’s autosave/ folder or restore from version control.

🔧 Manual Assignment Required

Q: Why aren’t my settings being applied? A: Every single sub-resource must be manually assigned:

  • GBCompositionContainer → GBConfig
  • GBConfig → GBSettings, GBTemplates, GBActions
  • GBSettings → BuildingSettings, ManipulationSettings, GridTargetingSettings, GBVisualSettings

No automatic assignment exists in 5.0.

Input and Interaction Issues

🖱️ Mouse/Keyboard Input

Q: Why isn’t my input being processed? A: Check input toggling on GridPositioner2D:

1
2
3
4

# Enable/disable input
grid_positioner.set_grid_input_enabled(true)
grid_positioner.set_mouse_input_enabled(true)
grid_positioner.set_keyboard_input_enabled(true)

Common Issue: Input disabled when UI menus are open but never re-enabled.

🎮 Collision Detection

Q: Why isn’t grid targeting detecting my tiles? A: Check TargetingShapeCast2D configuration:

  • Collision Mask: Must be 2048 (grid detection layer)
  • Shape: Proper size for your grid (16x16 for standard)
  • Enabled: Must be enabled for input processing

Testing and Debugging

🧪 Full Environment Required

Q: Why do my tests fail with missing nodes? A: 5.0 requires the full system stack for most operations.

Testing Requirements:

  • Complete scene with all systems
  • Proper LevelContext configuration
  • All resources assigned and saved
  • GridPositioner hierarchy intact

Unit tests work best for: Math, coordinate conversion, validation logic Integration tests needed for: Workflow, manipulation, targeting

🔍 Debug Tools

Q: How do I debug 5.0 issues? A: Use these approaches:

  1. Inspector Validation: Check for red indicators on missing resources
  2. Runtime Issues: Call get_runtime_issues() on composition container
  3. State Inspection: Check state objects in debugger
  4. Signal Debugging: Connect to signals and log emissions

Performance and Optimization

⚡ Signal Performance

Q: Why is my game slow with many objects? A: 5.0 state objects emit signals that many listeners receive.

Optimization Tips:

  • Disconnect unused signal listeners
  • Use state polling instead of signals where appropriate
  • Limit the number of active manipulatable objects

🗂️ Resource Loading

Q: Why is startup slow? A: Manual resource assignment and loading overhead.

Solutions:

  • Preload resources in a loading scene
  • Use resource references efficiently
  • Consider moving to 5.1/6.0 for better performance

Migration Considerations

🚀 Should I Upgrade?

Q: Should I stay on 5.0 or upgrade? A: Consider upgrading if:

  • You need better performance
  • You want cleaner architecture
  • You’re starting a new project
  • You need better testing support

Stay on 5.0 if:

  • You have a working 5.0 project
  • You can’t afford migration time
  • You need to maintain compatibility

📚 Migration Path

Q: How hard is it to upgrade to 5.1/6.0? A: Major architectural changes:

  • State objects become private
  • Signals use EventData payloads
  • Resource assignment becomes more automated
  • Testing becomes much easier

Plan: Allocate significant time for migration and testing.

Quick Reference

🔥 Top 5 Issues

  1. Missing LevelContext - Systems won’t run
  2. Unsaved Resources - Data loss
  3. Missing Manipulatable Node - No rotation/flip
  4. Wrong Collision Mask - No targeting
  5. Input Disabled - No interaction

✅ Pre-Flight Checklist

  • LevelContext configured and linked
  • All resources created, assigned, and saved
  • GridPositioner hierarchy correct
  • Manipulatable nodes on manipulatable objects
  • Input toggling working
  • Collision masks set to 2048
  • All systems present in scene

Still stuck? Start with the Level Context Integration guide - 80% of 5.0 issues are LevelContext-related.