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.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 --release flag.
• 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.

Available Scripts (full catalog)

Leaks & memory

• orphan_node_detector.gd
• memory_usage_threshold_alert.gd
• scene_tree_dump.gd

Timing & QA

• high_precision_benchmarker.gd
• automated_qa_suite.gd
• push_error_safe_exit.gd
• performance_plotter.gd

Errors, stacks, threads

• advanced_backtrace_recorder.gd
• stack_trace_logger.gd
• engine_error_interceptor.gd
• thread_safe_logger.gd
• thread_safety_assert.gd

Editor / remote / viz

• custom_editor_monitor.gd
• debugger_tab_plugin.gd — unregister in _exit_tree()
• remote_debug_console.gd
• debug_overlay.gd — debug builds only
• custom_debug_draw.gd
• property_watcher_gizmo.gd
• break_on_condition.gd
• engine_editor_hint_logic.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. 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.