godot-scene-management

利用可能なスクリプト

以下のトリガーは必須です — 該当するスクリプトを読み、未完成の Autoload ローダーを貼り付けないでください。

• async_scene_manager.gd — ローディング画面／スレッドを使ったレベル切り替えの前に必須です（THREAD_LOAD_FAILED の場合も含みます）。
• background_resource_loader.gd — ゲームプレイ中に次のレベルを事前ロードする場合（引っかかりの回避）に必須です。
• scene_transition_manager.gd — 安全な切り替えを包むフェード／ワイプの Tween。
• scene_pool.gd — 頻繁にスポーン／デスポーンする前（弾、敵、VFX）に必須です。
• scene_instancing_pooling.gd — プールへの補充／再利用のパターン。
• additive_ui_layering.gd — ワールドシーンを破棄せずにメニュー／オーバーレイを表示します。
• subviewport_scene_layering.gd — 複数のワールド／ミニマップ（SubViewport の入力計画が必要です）。
• persistent_data_preservation.gd — 切り替えをまたいで Autoload ／ルートホルダーを保持します。
• scene_state_manager.gd — 遷移をまたいで Persist グループの状態を保存／復元します。
• node_unparent_reparent.gd — トランスフォームを保持した再親付け（物理処理中に不用意に行わないでください）。
• node_path_safe_retrieval.gd — %UniqueName ／ガード付き @onready。
• dynamic_script_attachment.gd — Mod ／動的エンティティ用の実行時スクリプトアタッチ。

シーン管理で絶対にしてはいけないこと

• 大きなシーンを同期的にロードしてはいけません — メインスレッドでの load("res://large_scene.tscn") は、レベル遷移中に「カクつき」や完全なフリーズを引き起こします。進捗バー付きの非同期ロードには ResourceLoader.load_threaded_request() を使用してください。
• 一時的な状態に get_tree().change_scene_to_file() を使用してはいけません — このメソッドは現在のシーンとそのローカル変数をすべて破棄します。レベル間で状態を保持するには、Autoload（シングルトン） または永続的な「Game」ノードを使用してください。
• 1 フレームあたり 100 個以上の同一ノードをインスタンス化してはいけません — 弾、破片、敵の再利用には オブジェクトプーリング を使用してください。instantiate() と queue_free() を繰り返し呼び出すと CPU 負荷が急増し、ガベージコレクターが頻繁に起動します。
• get_node("../../Path/To/Node") をハードコードしてはいけません — エディターでノードを移動すると、このようなパスはすぐに壊れます。堅牢な参照には シーン固有名（%NodeName）または @export var target_node: Node を使用してください。
• 注意せずに物理処理中にノードを再親付けしてはいけません — 再親付けによって、トランスフォームが 1 フレームだけ「テレポート」する場合があります。必ず global_transform を保存し、add_child() の呼び出し後に再適用してください。
• 10,000 個以上のオブジェクトを SceneTree に依存して管理してはいけません — SceneTree の機能（シグナル、ノードごとのスクリプト）が不要な場合は、生のパフォーマンスを得るために PhysicsServer と RenderingServer を直接使用してください。
• NOTIFICATION_WM_CLOSE_REQUEST の処理を忘れてはいけません — デスクトップでは、永続ノードで終了リクエストを処理しないと、重要な保存処理中にゲームが終了することがあります。
• ノードのクリーンアップに深い再帰処理を使用してはいけません — Godot 4 では queue_free() がネイティブに再帰処理を行います。ルートノードを解放すると、すべての子ノードも自動的にクリーンアップされます。手動ループは冗長で非効率です。
• 計画なしに SubViewport とメインワールドの入力を混在させてはいけません — デフォルトでは、入力イベントは親へ伝播します。set_input_as_handled() を使用して、サブビューポートでの UI クリックがメインワールドのゲームプレイをトリガーしないようにしてください。
• レベルの「リセット」に change_scene を使用してはいけません — すべてをディスクから再ロードします。素早くリスポーンするには、変数をリセットしてプレイヤーを開始位置に移動するだけにしてください。

---

コンテンツ変更のための判断ツリー

目的	推奨	必須スクリプト
進行状況 UI を表示しながらレベルを完全に切り替える	スレッドで読み込み → THREAD_LOAD_LOADED のときに切り替え	async_scene_manager.gd
ドアやトリガーの手前で一時停止を隠す	ゲームプレイ中にスレッドリクエストを早めに開始	background_resource_loader.gd
切り替えの前後にフェード／ワイプを表示する	Transition Autoload でマネージャーをラップ	scene_transition_manager.gd
ワールドを維持したままポーズ／マップ／インベントリを表示する	加算型 UI レイヤー（change_scene は使用しない）	additive_ui_layering.gd
ルートを手動で切り替える／遅延解放する	current_scene のライフサイクルを独自に管理	関連ドキュメントと godot-autoload-architecture の safe パターン
同一のアクターを多数生成する	プールを使用し、instantiate／free を大量に直接呼び出さない	scene_pool.gd / scene_instancing_pooling.gd
ミニマップ／分割レンダリング	SubViewport ＋更新モード＋入力の分離	subviewport_scene_layering.gd
シーンの破棄後も維持する	Autoload／永続化グループを使用し、ローカル変数は使用しない	persistent_data_preservation.gd / scene_state_manager.gd
すばやくリスポーンする	状態をリセットしてテレポート — change_scene は使用しない	—
DLC／シーンのホットパッチ	ProjectSettings.load_resource_pack の後にパスを読み込む	（PCK）Official Docs を参照

専門的な理由（ステージング／整合性）

• プールの事前充填 — ロード画面中（PROCESS_MODE_DISABLED ＋非表示）に scene_pool.gd でインスタンス化のコストを先に吸収します。
• バックグラウンドでのステージング — ゲームプレイ中に load_threaded_request を実行し、読み込み完了後にのみ切り替えます（background_resource_loader.gd）。
• PCK オーバーライド — パックをマウントした後、同じ res:// パスに対して change_scene／load を実行し、パッチ済みのコンテンツを読み込みます。
• 孤立ノードの監査 — 切り替え後に Performance.OBJECT_ORPHAN_NODE_COUNT > 0 となっている場合、解放済みノードを参照し続ける参照が残っています。
• クリーンアップ — Godot 4 ではルートに対する queue_free() が再帰的に処理されるため、子ノードを手動でループする必要はありません。
• すばやいリスポーン — 状態をリセットしてテレポートします。レベルを再起動するためだけに change_scene を実行することは絶対に避けてください。

詳細（必要に応じて読み込む）

フェード用 Autoload、ロード画面、スポーン追跡、永続化用ホルダー、PCK パッチについては、references/scene-patterns-deep.md を参照してください。

参考資料

段階的な情報開示：特定の API を調査するときにのみ Official Documentation のリンクを開き、関連ドメインに移るときにのみ Related Skills を読み込みます。関連資料全体をあらかじめ読み込まないでください。

公式ドキュメント

• バックグラウンド読み込み — ResourceLoader.load_threaded_request／ステータスのポーリングを使って、カクつきのないレベル読み込みやプログレスバーを実現します。
• シーンを手動で変更する — 安全な切り替え処理で使われる、遅延解放とルートの再親化のパターンです（段階的な遷移では、無条件に change_scene_to_file を使うよりもこちらを優先してください）。
• SceneTree の使用 — current_scene、一時停止、グループ、およびシーンの切り替え時にツリーが Autoload のルート子ノードとどう関係するかを解説します。
• シーンの構成 — サブシーンをネストする際、ローダーや UI レイヤーが巨大なオブジェクトにならないようにする所有関係について説明します。
• ノードとシーンインスタンス — PackedScene.instantiate()、所有関係、事前読み込みと実行時読み込みの使い分けについて説明します。
• シーン固有ノード — 階層を編集しても、壊れやすい get_node("../../…") パスより維持しやすい %Name 参照について説明します。
• Autoload と通常のノードの比較 — シーン間で共有する状態はシングルトンに保持し、レベルのコンテンツはツリーからアンロードできるシーンに保持します。
• Viewport の使用 — メインシーンを切り替えずに、ミニマップ、画面分割、レイヤー化されたレンダリングを実現する SubViewport のワールドについて説明します。
• グループ — シーン遷移をまたぐ、永続グループの保存・復元と一括クリーンアップについて説明します。
• パック、パッチ、MOD のエクスポート — res:// パスにある DLC／MOD 用シーンの上書きに使う ProjectSettings.load_resource_pack について説明します。
• ResourceLoader — 非同期マネージャーが使用するスレッド読み込み API（load_threaded_*、exists）について説明します。
• PackedScene — プーリング、change_scene_to_packed、インスタンスキャッシュに使うシーンリソースの型について説明します。

関連スキル

前提条件

• godot-project-foundations — ローダーや Autoload レジストリが前提とするプロジェクトのレイアウト、シーンツリーの基本、インポートパスについて説明します。
• godot-gdscript-mastery — スレッド読み込みループや遷移の段階的な処理に必要な、型付きシグナル、await、プロセスフレームごとのポーリングについて説明します。
• godot-autoload-architecture — Game／状態保持オブジェクトが巨大なオブジェクトにならずに change_scene 後も存続するための、シングルトンの起動順序と所有関係について説明します。

関連スキル

• godot-signal-architecture — シーンの入れ替え後に再接続するか、バス経由でシグナルを送信し、ローダーが解放済みシーンにゴーストリスナーを残さないようにします。
• godot-resource-data-patterns — IDをハードコード文字列ではなく.tscnパスに対応付ける、レベルレジストリとペイロード用Resourceです。
• godot-save-load-systems — persist-group／Autoloadの状態をシリアライズします。シーンの入れ替えで別のセーブ経路を新たに作らないようにします。
• godot-tweening — ロードスレッドをブロックせずにシーン変更を包み込む、フェードやワイプのTweenです。
• godot-ui-containers — 永続的なUIルートの下に配置するローディング画面と追加メニューのレイヤーです。
• godot-performance-optimization — プールの予算、孤立ノードの監視、密集したスポーン時にSceneTreeがサーバーに処理を譲るべきタイミングについて説明します。
• godot-composition — パスへの依存なしにインスタンス化されたゲームプレイ要素を入れ替えられるようにする、コンポーネントシーンと所有関係です。

下流／利用側

• godot-genre-open-world — このスキルのスレッド化されたResourceLoaderキューを基盤とする、チャンクのストリーミングとバックグラウンドでの事前ロードです。
• godot-export-builds — 実行時にシーンパッチャーがマウントするPCK／パッチのパッケージングを提供します。
• godot-multiplayer-networking — プーリングと安全な変更パターンを再利用する、権限を考慮したシーンのスポーンと途中参加時の同期です。

マスター

• godot-master — ライブラリのルーターとミラー化されたモジュールのエントリです。ロード、永続化、UIのどれをドメインスキルが担当するかを調べる際に開いてください。