Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
NEVER assume 4.6 defaults (stretch mode, audio area_mask, RichTextLabel percent flags) without checking 4.7 migration notes.
Debugging & Profiling
Symptom โ monitor/API โ script routing for leaks, GPU, and CI โ Official Docs cover print/breakpoint basics.
NEVER Do
NEVER use print() without descriptive context โ print(value) is useless. Use print("Player health:", health) with labels.
NEVER leave debug prints in release builds โ Wrap in if OS.is_debug_build() or use custom DEBUG const. Prints slow down release.
NEVER ignore push_warning() messages โ Warnings indicate potential bugs (null refs, deprecated APIs). Fix them before they become errors.
NEVER use assert() for runtime validation in release โ Asserts are disabled in release builds. Use if not condition: push_error() for runtime checks.
NEVER profile in debug mode โ Debug builds are 5-10x slower. Always profile with release exports or flag.
--release
NEVER assume Engine.capture_script_backtraces(true) is cheap โ Capturing locals allocates significant memory and can prevent objects from being deallocated, causing artificial leaks [19].
NEVER call push_error() or print() inside a custom Logger._log_message override โ This causes infinite recursion and crashes as the logger intercepts its own output [20].
NEVER leave the Visual Profiler running during gameplay tests โ Continuous polling degrades framerates significantly, invalidating actual performance metrics [21].
NEVER rely on OS.get_ticks_msec() for microbenchmarking โ Milliseconds lack precision for logic timing; ALWAYS use Time.get_ticks_usec() for microsecond precision [22].
NEVER assume OBJECT_ORPHAN_NODE_COUNT works in production โ This monitor is strictly debug-only; it safely returns 0 in release builds, potentially hiding leaks [23].
NEVER benchmark with V-Sync enabled โ V-Sync throttles metrics to the monitor refresh rate, masking the true CPU/GPU processing overhead [24].
NEVER leave print_stack() or print_debug() in release builds โ These are often stripped or useless outside the debugger. Use structured logging for production [25].
NEVER strip debugging symbols if using external C++ profilers โ Stripping destroys call stack readability for external tools like Perfetto or VerySleepy [26].
NEVER forget to unregister an EditorDebuggerPlugin in _exit_tree() โ Failing to clean up leaves "ghost" connections in the engine's debugging loop [27].
NEVER trust the Visual Profiler on macOS when using the Compatibility renderer โ Platform-specific driver limitations severely restrict OpenGL profiling accuracy on macOS [28].
Symptom โ Monitor โ Script
MANDATORY for the matching row. Do NOT Load every debug script for one bug.
Profile release/--release with V-Sync off; never trust Debug-build timings.
Prefer structured logs over print_stack() in anything that might ship.
Escalate sustained FPS issues to godot-performance-optimization after the symptom tree identifies the bottleneck class.
MANDATORY for print/breakpoint workflow depth, profiler interpretation, and expert CI/GPU/thread patterns: debug-workflows.md. Do NOT Load when the symptom โ script table above already routes you.
Reference
Progressive disclosure: open Official Documentation links only when researching a specific API; load Related Skills when routing to a peer domain โ do not preload the whole lattice.
Official Documentation
Overview of debugging tools โ Map of remote scene tree, breakpoints, Output, and profiler entry points before picking a deeper page.
Debugger panel โ Stack, variables, breakpoints, errors, and monitors used for live remote debug sessions.
The profiler โ Time and visual profilers: why you profile release-like builds and how frame charts isolate CPU/GPU spikes.
Output panel โ How print / push_warning / push_error surface in the editor and why noisy release logs hide real faults.
ObjectDB profiler โ Before/after ObjectDB snapshots for RefCounted cycles and leaked instances that orphan monitors miss.
Custom performance monitors โ Performance.add_custom_monitor so game-specific metrics appear next to engine monitors.
Logging โ Custom Logger registration, file sinks, and recursion hazards when logging from inside log handlers.
Command line tutorial โ Headless --script / export flags for automated QA and CI exit-code runners.
CPU optimization โ Interpreting profiler hotspots into GDScript/server/thread fixes after measurement.
Using multiple threads โ Worker-thread rules that motivate thread-safety asserts and mutexed loggers.
Thread-safe APIs โ Which servers/APIs may be called off-main-thread without corrupting the SceneTree.
Performance โ Built-in monitors (OBJECT_ORPHAN_NODE_COUNT, memory, render) used by overlays and leak detectors.
Related Skills
Prerequisites
godot-project-foundations โ Debug/release feature tags, project settings, and Autoload layout must exist before debugger plugins or global monitors.
godot-gdscript-mastery โ Typed Callables, assert/push_error, and Time APIs underpin benchmarks, breakpoints, and stack helpers.
Complements
godot-performance-optimization โ After the profiler names a hotspot, apply pooling, culling, and MultiMesh fixes from that skill.
godot-testing-patterns โ GUT/assert/CI patterns pair with headless QA suites and deterministic quit exit codes.
godot-export-builds โ Profile and remote-debug against real export templates; debug symbols and strip settings matter for external profilers.
godot-scene-management โ Scene swap lifetime bugs show up as orphan-node growth; use tree dumps when loaders fail to free.
godot-signal-architecture โ Ghost listeners and deferred connects often explain โwhy is this still running?โ stack traces.
godot-autoload-architecture โ Global loggers, monitors, and error interceptors belong in Autoloads with clear boot order.
godot-server-architecture โ When debug draw or metrics push into Rendering/Physics servers, keep server ownership separate from nodes.
Downstream / consumers
godot-auditor โ Consumes debugger/profiler evidence when enforcing never-lists and architectural integrity reviews.
godot-platform-mobile โ Device remote debug and on-screen consoles are required when desktop Output is unavailable.
godot-monte-carlo-balancer โ Headless microbenchmarks and CI QA feed balance sims that need stable timing and exit codes.
godot-multiplayer-networking โ Networked games need remote inspectors and structured logs across peers without flooding the Output panel.
Master
godot-master โ Library router and mirrored module entry; open when discovering which Domain Skill owns a cross-cutting debug or perf concern.
