debug-issue

Debug Issue

Systematic debugging using domain-specific decision trees. Start by identifying the symptom category, then follow the corresponding tree.

Category Detection

Map user's symptom to the right tree:

Physics Decision Tree

Check in this order -- each step is the most common cause at that point:

1. Collision layer/mask mismatch (most common):

   • Check defined layer names: physics(action="layers")
   • Check node properties:

     nodes(action="get_property", scene_path="<scene>.tscn", name="<body>", property="collision_layer")
     nodes(action="get_property", scene_path="<scene>.tscn", name="<body>", property="collision_mask")
     

   • Rule: Object A detects Object B only if A's collision_mask has a bit that matches B's collision_layer. Both must be set correctly.

2. Missing CollisionShape2D/3D:

   • Inspect the scene tree: scenes(action="info", scene_path="<scene>.tscn")
   • Verify every physics body and Area has a CollisionShape child. A body without a shape = invisible to physics.

3. Wrong body type:

   • StaticBody2D: immovable (walls, floors)
   • CharacterBody2D: player/NPC movement via move_and_slide()
   • RigidBody2D: physics-driven (projectiles, debris)
   • Common mistake: using RigidBody2D for a player character, then fighting the physics engine

4. Script velocity issues:

   • Read the script: scripts(action="read", script_path="res://scripts/<name>.gd")
   • Check if velocity is being set before move_and_slide()
   • Check if gravity is applied in _physics_process (not _process)
   • Check if delta is used for frame-independent movement