godot-debug-profiler

name	godot-debug-profiler
description	Debug and profile Godot 4.6 games. Combines scene debugging, render/runtime/import/animation/resize/mobile input fixes, performance profiling, draw calls, primitives, textures, video memory, shader/post-processing cost, export size, and mobile content-scale/input issues.

Godot Debug Profiler

Godot Reference Links

Targets Godot 4.6.x (latest stable 4.6.3, June 2026). These links use /en/stable/, so they always resolve to the current stable docs — fetch them for up-to-date nodes, classes, and method signatures rather than relying on memory.

• Latest stable docs: https://docs.godotengine.org/en/stable/
• Class reference: https://docs.godotengine.org/en/stable/classes/index.html
• Debugging: https://docs.godotengine.org/en/stable/tutorials/scripting/debug/index.html
• Overview of debugging tools: https://docs.godotengine.org/en/stable/tutorials/scripting/debug/overview_of_debugging_tools.html
• Performance optimization: https://docs.godotengine.org/en/stable/tutorials/performance/index.html
• Optimization using MultiMeshes: https://docs.godotengine.org/en/stable/tutorials/performance/using_multimesh.html
• Occlusion culling: https://docs.godotengine.org/en/stable/tutorials/3d/occlusion_culling.html
• Mesh level of detail (LOD): https://docs.godotengine.org/en/stable/tutorials/3d/mesh_lod.html
• Performance class (monitors): https://docs.godotengine.org/en/stable/classes/class_performance.html

Purpose

Find root causes and optimize measured bottlenecks without breaking playability.

Debug Workflow

Load references/debug-profile-checklists.md as the first action when debugging render/runtime/mobile issues, asset import, audio bus/stream issues, animation, resize/content scale, input, blank viewport, physics/collision bugs, or profiling performance. Track it in a reference ledger with yes/no, path, and failure reason. Do not mark the debug/profile phase complete while this reference is skipped for debug or profiling work.

Load references/checklists/scene-debugging.md for render/runtime bug diagnosis, references/checklists/performance-profile.md for profiling work, and references/checklists/mobile-input.md for mobile render/input issues. Load references/prompt-templates.md only when the user asks for reusable debug/profile prompts or a task template.

1. Reproduce locally.
2. Read stdout/stderr SCRIPT ERROR / ERROR: lines and the in-editor/remote debugger.
3. Check viewport size, window size, and content-scale/stretch behavior.
4. Check rendering method, current_scene, and main loop ownership.
5. Check camera, aspect, near/far, lights, materials, WorldEnvironment, scene contents, transforms.
6. Check res:// paths, importers, .import metadata, and missing/reimport state.
7. Check _process(delta) vs _physics_process(delta) order, physics tick rate, body/collider ownership, InputMap/_input/touch behavior, resize, and audio bus/stream/playback errors when audio is involved.
8. Fix root cause in owning script/node.
9. Verify viewport screenshot, nonblank viewport pixels, stdout/stderr errors, and broken path.

Performance Workflow

1. Reproduce in correct rendering method and export/run mode.
2. Record baseline: FPS/frame time, draw calls, primitives, objects, nodes, orphan nodes, video memory, export size.
3. Identify CPU/GPU/memory/storage bottleneck.
4. Optimize one thing at a time: MultiMesh, shared resources, occlusion/distance culling, mesh LOD, content-scale cap, cheaper shadows/GI/post, texture VRAM discipline.
5. Re-measure same scenario and verify visuals/playability.

Final Response

Lead with root cause or bottleneck. Report the reference ledger, checklist items used, files changed, baseline/post metrics, commands, screenshots/artifacts, broken paths retested, and residual risks.