godot-debugger
Diagnose runtime bugs, visual glitches, and unexpected behavior in Godot games by inspecting the live game via MCP tools. Adaptive — routes to different diagnostic paths based on symptoms. Triggers on
SKILL.md.claude/skills/godot-debugger/SKILL.md
GitHubGodot Debugger
Diagnose and fix Godot game issues using godot-mcp-pro runtime inspection tools.
Prerequisites
- Godot editor open with project loaded
- godot-mcp-pro server connected
- For runtime debugging: scene must be playable
Step 1: Classify the Symptom
| Symptom | Branch | Key Tools |
|---|---|---|
| Error in output, crash, script exception | A: Crash/Error | get_editor_errors, read_script, validate_script |
| Something looks wrong visually | B: Visual Glitch | get_game_screenshot, get_game_node_properties, capture_frames |
| Game logic doesn't work as expected | C: Logic Bug | execute_game_script, monitor_properties, analyze_signal_flow |
| Low FPS, stuttering, lag | D: Performance | get_performance_monitors, analyze_scene_complexity |
| Nothing happens at all | E: Silent Failure | get_collision_info, find_signal_connections, get_scene_tree |
Branch A: Crash / Error
mcp__godot-mcp-pro__get_editor_errors— read all error messages- Parse the error:
- Script error with line number:
mcp__godot-mcp-pro__read_scriptthe file, identify the line - Null reference / Invalid get index:
mcp__godot-mcp-pro__get_scene_tree— check if node exists at expected path. Common: node renamed, not yet in tree, accessed before_ready() - Type error: Check Godot 4.6 strict typing rules (see common-bugs.md).
mcp__godot-mcp-pro__validate_scriptto verify syntax - Resource not found:
mcp__godot-mcp-pro__search_filesto find actual resource path
- Script error with line number:
- Suggest fix with exact code change
- After fix:
mcp__godot-mcp-pro__validate_scriptto confirm compilation
Branch B: Visual Glitch
mcp__godot-mcp-pro__play_sceneif not running, thenmcp__godot-mcp-pro__get_game_screenshot- Analyze the screenshot for clues
mcp__godot-mcp-pro__get_game_scene_tree— check hierarchy, visibility, orderingmcp__godot-mcp-pro__get_game_node_propertieson suspect nodes:visiblepropertymodulate/self_modulatetransform/global_transformz_index(2D ordering)materialassignments
- If shader issue:
mcp__godot-mcp-pro__read_shader+mcp__godot-mcp-pro__get_shader_params - If particle issue:
mcp__godot-mcp-pro__get_particle_info— check AABB, emission settings - If intermittent:
mcp__godot-mcp-pro__capture_framesover multiple frames - Identify root cause and suggest fix
Branch C: Logic Bug
mcp__godot-mcp-pro__play_scenethenmcp__godot-mcp-pro__execute_game_script:var player = get_tree().get_first_node_in_group("player") return {"health": player.health, "state": player.current_state, "pos": player.global_position}mcp__godot-mcp-pro__monitor_properties— track suspect variables over N framesmcp__godot-mcp-pro__analyze_signal_flow— map signal connectionsmcp__godot-mcp-pro__find_signal_connections— verify specific wiringmcp__godot-mcp-pro__assert_node_state— test hypotheses:property: "health", operator: ">", value: 0- Narrow down: is the data wrong, the signal not firing, or the condition incorrect?
mcp__godot-mcp-pro__read_scriptto confirm the bug in code- Suggest fix
Branch D: Performance
mcp__godot-mcp-pro__get_performance_monitors— FPS, physics time, draw calls, memory, node count- Identify bottleneck:
- Low FPS + high draw calls: Too many visible objects
- Low FPS + high physics time: Complex collision shapes or too many physics bodies
- Low FPS + high memory: Resource leaks, oversized textures
- Stuttering: GC pauses, large instantiations, file I/O on main thread
mcp__godot-mcp-pro__analyze_scene_complexity— node counts, nesting, type distributionmcp__godot-mcp-pro__get_game_scene_treewith type filters — find heavy subtrees- Recommend specific optimizations:
- Draw calls: MultiMeshInstance3D, merge static meshes, LOD
- Physics: simplify shapes (box/capsule over trimesh), reduce body count
- Memory: compress textures, mipmaps, unload unused resources
- Stuttering: preload resources, object pools, defer heavy work
Branch E: Silent Failure
mcp__godot-mcp-pro__get_editor_errors— suppressed warningsmcp__godot-mcp-pro__get_scene_tree— verify node IS in the scene treemcp__godot-mcp-pro__find_signal_connections— check expected signals wiredmcp__godot-mcp-pro__get_collision_info— check layer/mask (very common cause)mcp__godot-mcp-pro__execute_game_script— manually call the expected function:var node = get_node("/root/Main/Enemy") node.take_damage(10) return {"health_after": node.health}- Trace the chain: Input -> Signal -> Method -> Effect. Find the broken link.
Iteration Strategy
- Don't give up after one pass. If first hypothesis is wrong, try next branch.
mcp__godot-mcp-pro__get_output_logfor context beyond errors.mcp__godot-mcp-pro__clear_outputbefore reproducing for clean logs.- Screenshot before AND after fixes to confirm resolution.
Common Gotchas
- Collision layers:
1 << (N-1)bitmask, NOT raw numbers. #1 cause of "bullets pass through." - Godot 4.6 typing:
:=with Variant-returning functions causes parse errors. Use: Type =. - RID leaks: Manually created resources not attached to nodes won't be freed.
Project Conventions
Check the project's .claude/skills/ and CLAUDE.md for project-specific debugging context such as collision layer conventions, entity system patterns, and known project gotchas.