godot-debugging-profiling

絶対にしてはいけないこと

• 説明のない print() は絶対に使用しないでください — print(value) では何の役にも立ちません。ラベルを付けて print("Player health:", health) のように使用してください。
• リリースビルドにデバッグ用の出力を絶対に残さないでください — if OS.is_debug_build() で囲むか、独自の DEBUG 定数を使用してください。出力処理はリリース時の速度を低下させます。
• push_warning() のメッセージを絶対に無視しないでください — 警告は潜在的なバグ（null 参照、非推奨 API など）を示しています。エラーになる前に修正してください。
• リリース時の実行時検証に assert() を絶対に使用しないでください — アサートはリリースビルドでは無効になります。実行時のチェックには if not condition: push_error() を使用してください。
• デバッグモードで絶対にプロファイリングしないでください — デバッグビルドは 5～10 倍遅くなります。必ずリリースエクスポートまたは --release フラグを使用してプロファイリングしてください。
• Engine.capture_script_backtraces(true) は負荷が低いと絶対に思い込まないでください — ローカル変数のキャプチャには大量のメモリが割り当てられ、オブジェクトの解放を妨げて、人為的なリークを引き起こすことがあります [19]。
• 独自の Logger._log_message オーバーライド内で push_error() や print() を絶対に呼び出さないでください — ロガーが自身の出力をインターセプトするため、無限再帰が発生してクラッシュします [20]。
• ゲームプレイのテスト中に Visual Profiler を絶対に実行したままにしないでください — 継続的なポーリングはフレームレートを大幅に低下させ、実際のパフォーマンス指標を無効にします [21]。
• マイクロベンチマークに OS.get_ticks_msec() を絶対に使用しないでください — ミリ秒単位では処理時間を計測する精度が不足します。マイクロ秒単位の精度を得るには、必ず Time.get_ticks_usec() を使用してください [22]。
• OBJECT_ORPHAN_NODE_COUNT が本番環境でも機能すると絶対に思い込まないでください — このモニターはデバッグ専用です。リリースビルドでは安全のため 0 を返すため、リークが見えなくなる場合があります [23]。
• V-Sync を有効にしたまま絶対にベンチマークしないでください — V-Sync により指標がモニターのリフレッシュレートに制限され、実際の CPU／GPU 処理負荷が隠れてしまいます [24]。
• リリースビルドに print_stack() や print_debug() を絶対に残さないでください — これらはデバッガーの外では削除されるか、役に立たないことがよくあります。本番環境では構造化ログを使用してください [25]。
• 外部の C++ プロファイラーを使用する場合は、デバッグシンボルを絶対に削除しないでください — シンボルを削除すると、Perfetto や VerySleepy などの外部ツールでコールスタックが読めなくなります [26]。
• _exit_tree() で EditorDebuggerPlugin の登録解除を絶対に忘れないでください — クリーンアップしないと、エンジンのデバッグループに「ゴースト」接続が残ります [27]。
• Compatibility レンダラーを使用している macOS では、Visual Profiler を絶対に信用しないでください — プラットフォーム固有のドライバーの制限により、macOS での OpenGL プロファイリングの精度は大きく制限されます [28]。

症状 → モニター → スクリプト

該当する行では必須です。1つのバグに対して、すべてのデバッグスクリプトを読み込まないでください。

症状	モニター／API	スクリプト
ノードを削除しても RAM が増加する	OBJECT_ORPHAN_NODE_COUNT（デバッグ）	必須 orphan_node_detector.gd
ObjectDB／インスタンス数の増加	カスタムモニター＋ダンプ	memory_usage_threshold_alert.gd、scene_tree_dump.gd
GPU／オーバードローの原因が不明	Visual Profiler（一時的に使用）	パフォーマンス用スキルと併用し、傾向の確認には performance_plotter.gd を使用します — Visual Profiler を有効にしたままにしないでください
ヘッドレス／CI の終了が不安定	終了コード＋アサーション	必須 automated_qa_suite.gd、push_error_safe_exit.gd
マイクロベンチマークの結果が不正確	Time.get_ticks_usec	必須 high_precision_benchmarker.gd
クラッシュ時にローカル変数が必要	バックトレース（デバッグのみ）	advanced_backtrace_recorder.gd、stack_trace_logger.gd
エンジンエラーをバックエンドに送信	ロガーによるインターセプト	engine_error_interceptor.gd — Logger 内で print しないでください
カスタムデバッガーメトリクス	Monitors タブ	custom_editor_monitor.gd、debugger_tab_plugin.gd
モバイル／コンソールで stdout が使えない	ゲーム内コンソール	remote_debug_console.gd、debug_overlay.gd（デバッグビルドのみ）
スレッドの競合／ログの破損	ミューテックスロガー／アサーション	thread_safe_logger.gd、thread_safety_assert.gd
見えないロジック（AI／物理）	デバッグ描画／ギズモ	custom_debug_draw.gd、property_watcher_gizmo.gd
条件付き停止	ハードコードされたブレーク	break_on_condition.gd
エディターと実行時のパス	Engine.is_editor_hint	engine_editor_hint_logic.gd

利用可能なスクリプト（全カタログ）

リークとメモリ

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

タイミングと QA

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

エラー、スタック、スレッド

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

エディター／リモート／可視化

• custom_editor_monitor.gd
• debugger_tab_plugin.gd — _exit_tree() で登録解除します
• remote_debug_console.gd
• debug_overlay.gd — デバッグビルドのみ
• custom_debug_draw.gd
• property_watcher_gizmo.gd
• break_on_condition.gd
• engine_editor_hint_logic.gd

エキスパート向けのヒント

• V-Sync をオフにして、リリース版／--release をプロファイルします。デバッグビルドの計測時間は決して信用しないでください。
• リリースされる可能性のあるものでは、print_stack() より構造化ログを優先してください。
• 症状ツリーでボトルネックの種類を特定した後も FPS の問題が継続する場合は、godot-performance-optimization にエスカレーションしてください。

必須：print／ブレークポイントを使ったワークフローの詳細、プロファイラーの読み解き方、エキスパート向けの CI／GPU／スレッドのパターンについては、debug-workflows.md を参照してください。上記の症状 → スクリプトの表ですでに案内されている場合は、読み込まないでください。

リファレンス

段階的な開示：特定の API を調査する場合にのみ公式ドキュメントへのリンクを開き、関連スキルは隣接する領域に案内された場合に読み込んでください。全体を一括して事前に読み込まないでください。

公式ドキュメント

• デバッグツールの概要 — 詳細なページを選ぶ前に、リモートシーンツリー、ブレークポイント、出力、プロファイラーの各入口を確認するための概要です。
• デバッガーパネル — ライブのリモートデバッグセッションで使用するスタック、変数、ブレークポイント、エラー、モニターについて説明します。
• プロファイラー — 時間プロファイラーとビジュアルプロファイラーについて説明します。リリース版に近いビルドをプロファイルする理由や、フレームチャートで CPU／GPU のスパイクを特定する方法を確認できます。
• 出力パネル — print／push_warning／push_error がエディターにどのように表示されるか、またリリースログが過剰なノイズで埋まると実際の問題が見えにくくなる理由を説明します。
• ObjectDB プロファイラー — RefCounted の循環参照や孤立したインスタンスを、孤立ノードのモニターでは検出できない場合に、ObjectDB の前後のスナップショットを確認します。
• カスタムパフォーマンスモニター — Performance.add_custom_monitor を使うと、ゲーム固有のメトリクスをエンジンのモニターと並べて表示できます。
• ログ — カスタム Logger の登録、ファイル出力先、ログハンドラー内からログを記録する際の再帰の危険性について説明します。
• コマンドラインチュートリアル — 自動 QA や CI の終了コードランナーで使う、ヘッドレスの --script／エクスポートフラグについて説明します。
• CPU 最適化 — 計測後に、プロファイラーのホットスポットを GDScript／サーバー／スレッドの修正に結び付ける方法を説明します。
• 複数スレッドの使用 — スレッドセーフのアサートやミューテックスを使うロガーが必要となる、ワーカースレッドのルールについて説明します。
• スレッドセーフな API — SceneTree を破損させずにメインスレッド以外から呼び出せるサーバー／API を確認できます。
• パフォーマンス — オーバーレイやリーク検出器で使う組み込みモニター（OBJECT_ORPHAN_NODE_COUNT、メモリ、レンダリング）について説明します。

関連スキル

前提条件

• godot-project-foundations — デバッガープラグインやグローバルモニターを追加する前に、デバッグ／リリースの機能タグ、プロジェクト設定、Autoload の構成が整っている必要があります。
• godot-gdscript-mastery — 型付き Callable、assert／push_error、Time API は、ベンチマーク、ブレークポイント、スタックヘルパーの基盤となります。

補完

• godot-performance-optimization — プロファイラーでボトルネックを特定した後、このスキルのプーリング、カリング、MultiMesh の修正を適用します。
• godot-testing-patterns — GUT／assert／CI のパターンは、ヘッドレス QA スイートや決定的な quit の終了コードと組み合わせて使用します。
• godot-export-builds — 実際のエクスポートテンプレートに対してプロファイリングとリモートデバッグを行います。外部プロファイラーでは、デバッグシンボルとストリップ設定が重要です。
• godot-scene-management — シーン切り替え時のライフタイムのバグは、孤立ノードの増加として現れます。ローダーが解放に失敗する場合は、ツリーのダンプを使用します。
• godot-signal-architecture — ゴーストリスナーや遅延接続が、「なぜまだ動いているのか？」というスタックトレースの原因であることがよくあります。
• godot-autoload-architecture — グローバルロガー、モニター、エラーインターセプターは、明確な起動順序を設定して Autoload に配置します。
• godot-server-architecture — デバッグ描画やメトリクスを Rendering／Physics サーバーに送る場合は、サーバーの所有権をノードから分離します。

下流／利用側

• godot-auditor — 禁止事項リストやアーキテクチャの整合性レビューを実施する際に、デバッガー／プロファイラーの証拠を利用します。
• godot-platform-mobile — デスクトップの出力を利用できない場合は、デバイスでのリモートデバッグと画面上のコンソールが必要です。
• godot-monte-carlo-balancer — ヘッドレスのマイクロベンチマークと CI QA の結果は、安定したタイミングと終了コードを必要とするバランスシミュレーションに活用されます。
• godot-multiplayer-networking — ネットワークゲームでは、Output パネルに大量のログを流さずに、ピア間でリモートインスペクターと構造化ログを利用する必要があります。

マスター

• godot-master — ライブラリのルーターであり、ミラーされたモジュールのエントリです。複数領域にまたがるデバッグやパフォーマンスの課題を担当するドメインスキルを探すときに開きます。