godot-performance-optimization

パフォーマンス最適化で絶対にしてはいけないこと

• プロファイリングを先に行わずに最適化してはいけません — データもなく「物理処理が遅いと思う」だけでは、時期尚早な最適化です。必ず Debug → Profiler（F3）を使って、実際のボトルネックを特定してください [20]。
• リリースビルドで print() を使ってはいけません — 毎フレームの print() は、ファイル I/O のボトルネックとログの大量出力を招きます。@warning_ignore または条件付きの if OS.is_debug_build(): を使ってください [21]。
• 画面外のエンティティで VisibleOnScreenNotifier2D を無視してはいけません — 画面外で敵の処理を続けると、CPU を無駄に消費します。screen_exited で set_process(false) を無効にしてください [22]。
• 負荷の高いループ内でノードをインスタンス化してはいけません — for i in 1000: var bullet = Bullet.new() は、1000 回のメモリ割り当てになります。オブジェクトプールを使い、インスタンスを再利用してください [23]。
• _process() 内で get_node() を使ってはいけません — get_node("Player") を毎秒 60 回呼び出すと、ツリーの走査が大量に発生します。@onready var player := $Player でキャッシュしてください [24]。
• 描画呼び出しをまとめ忘れてはいけません — 個別のスプライトが 1000 個あると、描画呼び出しも 1000 回になります。インスタンス描画には TextureAtlas（スプライトシート）と MultiMesh を使ってください [25]。
• 負荷の高い処理でメインスレッドをブロックしてはいけません — OS.delay_msec() や、時間のかかる同期データ処理は避けてください。WorkerThreadPool を使って、フレームレートを安定させてください。
• 物理クエリに複雑なコリジョン形状を使ってはいけません — ポリゴン数の多い凸形状は、解決コストが高くなります。単純化したプリミティブ（Circle、Rectangle、Box）を優先してください。
• ローカルのラムダシグナルを切断し忘れてはいけません — グローバルシグナルに接続された匿名ラムダは、キャプチャ対象のオブジェクトが解放されるとメモリリークの原因になることがあります。
• VRAM 圧縮なしで大きなテクスチャを使ってはいけません — VRAM には限りがあります。デスクトップ（DirectX/Vulkan）では S3TC/BPTC、モバイルでは ETC2 を使ってください。注：アーティファクトを避けるため、ピクセルアートでは圧縮を無効にしてください [13]。
• 物理ステップ中にツリーを変更してはいけません — _inter_ray または _physics_process 中にノードを追加・削除すると、物理サーバーがロックされることがあります。call_deferred を使ってください。
• Compatibility レンダラーでシェーダーの事前ウォームアップを省略してはいけません — Forward+ とは異なり、OpenGL には Ubershader がありません。カクつきを防ぐため、ロード画面の背後で、カメラの前にすべてのメッシュ／VFX を 1 フレームだけ事前インスタンス化してください [21]。

---

Debug → Profiler（F3）

タブ：

• Time：関数呼び出し時間
• Memory：RAM 使用量
• Network：RPC、帯域幅
• Physics：コリジョンチェック

Profiler タブの判断フロー

まず Debug → Profiler を開いてください。必須：問題のあるタブ／症状に対応するスクリプトだけを読み込んでください。

1 回のカクつきに対して、パフォーマンス関連のスクリプトをすべて読み込んではいけません。

Profiler／症状	考えられる原因	スクリプト
Time — 同じスクリプトが高負荷	割り当て／get_node／処理	object_pool_system.gd、@onready のキャッシュ；custom_monitor_profiler.gd
Time — 画面外の AI／VFX	非表示中も処理を継続	必須 manual_culling_logic.gd
Memory — 時間とともに増加	リーク／固有リソース	shared_resource_strategy.gd；孤立オブジェクトのデバッグツールと併用
Physics — コリジョンのスパイク	クエリ／ノードによる RayCast の大量実行	必須 low_level_physics_query.gd
GPU／描画呼び出し	固有のスプライト／メッシュ	必須 multimesh_optimizer.gd／multimesh_foliage_manager.gd／texture_array_batching.gd
大規模環境での SceneTree のオーバーヘッド	Canvas／メッシュアイテムの大量生成	必須 rendering_server_direct.gd
メインスレッドのカクつき（生成／解析）	負荷の高い同期処理	必須 worker_thread_pool_manager.gd
群衆の経路探索のスパイク	同一フレーム内のナビゲーションエージェント	navigation_agent_optimization.gd
カスタムゲーム指標	モニターの不足	custom_performance_monitor.gd

利用可能なスクリプト

object_pool_system.gd

ホットパスでの生成・破棄には必須です。再利用し、インラインで独自の Array pop プールを作らないでください。

manual_culling_logic.gd

VisibilityNotifier を使って、画面外にある CPU 負荷の高いエンティティの処理を無効化します。

rendering_server_direct.gd

SceneTree のオーバーヘッドが支配的な場合に使用する RenderingServer のキャンバス／メッシュ経路です。

low_level_physics_query.gd

何百もの RayCast ノードを使う代わりに、空間状態を直接クエリします。

worker_thread_pool_manager.gd

重いジョブを WorkerThreadPool に委譲します。

multimesh_optimizer.gd / multimesh_foliage_manager.gd

密集したメッシュ／植生にハードウェアインスタンシングを使用します。

texture_array_batching.gd

Texture2DArray によるバッチ処理でマテリアルの切り替えを減らします。

shared_resource_strategy.gd

共有リソースとシーン固有リソースのメモリ上のトレードオフです。

navigation_agent_optimization.gd

群衆の経路更新を時間差で行います。

custom_monitor_profiler.gd / custom_performance_monitor.gd

ゲーム固有のスパイクには Performance.get_monitor ／カスタムモニターを使用します。

専門家向けの要点（簡潔に）

• Compatibility レンダラー：パイプラインを事前ウォームアップします（非表示のカメラと固有のメッシュ／マテリアルを使い、1 フレーム処理します）。Forward+／Mobile：Ubershader でも一度だけのインスタンス化検出が必要です。
• VRAM：デスクトップでは S3TC／BPTC、モバイルでは ETC2 を使用します。ピクセルアートでは圧縮を避けてください。
• AStar／経路の予算は navigation_agent_optimization.gd で管理します。頻繁なキュー更新を招くスニペットを標準的な実装として貼り付けないでください。

詳細解説（必要に応じて）

• 経路の時間分割、Compatibility シェーダーの事前ウォームアップ、VRAM コーデック表 → profiler-budgets-and-prewarm.md

リファレンス

段階的な情報開示：特定の API を調査するときにのみ公式ドキュメントのリンクを開き、関連するドメインに引き継ぐときにのみ関連スキルを読み込んでください。依存関係全体を事前に読み込まないでください。

公式ドキュメント

• 全般的な最適化 — コードを変更する前に時間／メモリ／物理演算を計測する、プロファイラーを優先したワークフローです。
• CPU の最適化 — 処理コスト、ノード検索、アロケーション、そしてホットパスのパターンがフレーム時間の大部分を占める理由について説明します。
• GPU の最適化 — 描画コストを削減するドローコール、オーバードロー、VRAM 圧縮の選択肢について説明します。
• MultiMesh の使用 — 数千のメッシュに対するハードウェアインスタンシングと、空間分割によってカリングを回復する方法について説明します。
• サーバーとリソースの使用 — SceneTree のオーバーヘッドがボトルネックになった場合に使用する、RenderingServer／PhysicsServer の直接 API について説明します。
• 複数スレッドの使用 — 重い処理をメインスレッドの外で実行する WorkerThreadPool のタスクモデルについて説明します。
• スレッドセーフな API — ワーカータスクから安全に使えるエンジン API と、SceneTree 専用の呼び出しについて説明します。
• パイプラインのコンパイル — シェーダー／パイプラインによるカクつきの原因と、レンダラーごとの事前ウォームアップ方法について説明します。
• 3D パフォーマンスの最適化 — 3D シーンにおける LOD、カリング距離、メッシュ複雑度の予算について説明します。
• オクルージョンカリング — フラスタムカリングだけでは不十分な場合の OccluderInstance3D のトレードオフについて説明します。
• パフォーマンス — ゲーム固有のボトルネックダッシュボード向けの、組み込みモニターとカスタムメトリクスについて説明します。
• ナビゲーションパフォーマンスの最適化 — 大規模な群衆におけるエージェントの更新予算とベイクコストについて説明します。

関連スキル

前提条件

• godot-project-foundations — プロファイリングやプーリングのパターンを理解する前に必要となる、シーンツリー、リソース、インポートの基本について説明します。
• godot-gdscript-mastery — 最適化スクリプトの正確性を保つ、型指定されたホットパス、Callable、@onready によるキャッシュについて説明します。
• godot-resource-data-patterns — メモリや一意のインスタンスに関するトレードオフを左右する、共有リソースとシーン固有リソースの所有権について説明します。

補完

• godot-2d-physics — Physics プロファイラーのスパイクとして現れる衝突レイヤー、クエリ、ボディ数について解説します。
• godot-physics-3d — シミュレーション負荷の高いシーンを最適化する際の、3D シェイプのコストと RigidBody の予算について解説します。
• godot-raycasting-queries — 多数の RayCast ノードを使った重い構成に代わる、直接的な空間状態クエリのパターンについて解説します。
• godot-shaders-basics — GPU の状態変更を減らす、マテリアル／シェーダーの複雑さと Texture2DArray によるバッチ処理について解説します。
• godot-scene-management — ストリーミング中の引っかかりを防ぐ、スレッドを使った読み込みとシーンのパッキングについて解説します。
• godot-navigation-pathfinding — 間隔を空けた AI 更新と組み合わせる、エージェントのパス予算と非同期ベイクについて解説します。
• godot-3d-world-building — ドローコール予算の上限を決める、GridMap／LOD／オクルージョンを考慮したレベル設計について解説します。

下流／利用者

• godot-adapt-desktop-to-mobile — 性能の低い GPU でこれらの予算を適用する、解像度／シェーダーのフォールバックとバッテリーモードについて解説します。
• godot-export-builds — 圧縮と Compatibility の事前ウォームアップが重要となる、エクスポートプリセットとレンダラーの選択について解説します。
• godot-genre-open-world — 大規模な環境で MultiMesh、カリング、スレッドプールのパターンを活用する、チャンクストリーミングと HLOD システムについて解説します。

マスター

• godot-master — スキル間の探索に使う、ライブラリルーターおよびミラーされたモジュールのエントリポイントです。