godot-debugging-profiling

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.isdebugbuild() 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 --release flag.
• NEVER assume Engine.capturescriptbacktraces(true) is cheap — Capturing locals allocates significant memory and can prevent objects from being deallocated, causing artificial leaks [19].
• NEVER call pusherror() 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.getticksmsec() for microbenchmarking — Milliseconds lack precision for logic timing; ALWAYS use Time.getticksusec() for microsecond precision [22].
• NEVER assume OBJECTORPHANNODE_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 printstack() or printdebug() 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 exittree() — 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.

Available Scripts (full catalog)

Leaks & memory

• [orphannodedetector.gd](scripts/orphannodedetector.gd)
• [memoryusagethresholdalert.gd](scripts/memoryusagethresholdalert.gd)
• [scenetreedump.gd](scripts/scenetreedump.gd)

Timing & QA

• [highprecisionbenchmarker.gd](scripts/highprecisionbenchmarker.gd)
• [automatedqasuite.gd](scripts/automatedqasuite.gd)
• [pusherrorsafeexit.gd](scripts/pusherrorsafeexit.gd)
• [performanceplotter.gd](scripts/performanceplotter.gd)

Errors, stacks, threads

• [advancedbacktracerecorder.gd](scripts/advancedbacktracerecorder.gd)
• [stacktracelogger.gd](scripts/stacktracelogger.gd)
• [engineerrorinterceptor.gd](scripts/engineerrorinterceptor.gd)
• [threadsafelogger.gd](scripts/threadsafelogger.gd)
• [threadsafetyassert.gd](scripts/threadsafetyassert.gd)

Editor / remote / viz

• [customeditormonitor.gd](scripts/customeditormonitor.gd)
• [debuggertabplugin.gd](scripts/debuggertabplugin.gd) — unregister in exittree()
• [remotedebugconsole.gd](scripts/remotedebugconsole.gd)
• [debugoverlay.gd](scripts/debugoverlay.gd) — debug builds only
• [customdebugdraw.gd](scripts/customdebugdraw.gd)
• [propertywatchergizmo.gd](scripts/propertywatchergizmo.gd)
• [breakoncondition.gd](scripts/breakoncondition.gd)
• [engineeditorhintlogic.gd](scripts/engineeditorhintlogic.gd)

Expert Pointers

• 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](references/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 / pushwarning / 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.addcustommonitor 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 (OBJECTORPHANNODECOUNT, 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.