godot-autoload-architecture

利用可能なスクリプト

autoload_init_order_diag.gd

複数の Autoload にまたがる依存関係グラフを信頼する前に必須です。起動順序を検証します。

singleton_dependency_diagram.gd

mermaid／順序図を使用する際に必須です。起動時にどのシングルトンがどれを呼び出せるかを示します。

global_event_bus.gd

システムをまたぐ Autoload バス（実績、UI、セーブイベント）を導入する前に必須です。

safe_scene_switcher.gd

Autoload が所有するシーン遷移（遅延解放／ルート管理）を導入する前に必須です。

service_locator.gd / service_registry.gd

Node ではないサービスに対して Engine.register_singleton による DI を導入する前に必須です。

persistent_data_holder.gd

change_scene_to_file() をまたいで保持する必要があるデータ（インベントリ、設定）に使用します。

static_state_manager.gd

SceneTree の Node が不要な場合の static var によるグローバル状態に使用します。

lazy_loaded_singleton.gd

起動時のコストをかけず、必要になったときにインスタンス化します。

cross_autoload_comms.gd

両方の準備ができた後に、安全にシングルトン間で呼び出します。

thread_safe_global_access.gd

バックグラウンドスレッドが Autoload の状態にアクセスする際に、Mutex／call_deferred を使用します。

autoload_reference_checker.gd / singleton_health_check_test.gd

登録とデフォルト値を検証します（デバッグ／CI）。

autoload_bootstrapper.gd / autoload_initializer.gd

重い処理には _ready が早すぎる場合に使用する、順序付きの初期化ヘルパーです。

debug_console_autoload.gd

PROCESS_MODE_ALWAYS の CanvasLayer コンソールです。

global_game_state.gd / stateless_bus.gd

状態保持クラスと、純粋なイベントバスを分けます。

AutoLoad アーキテクチャで絶対にしてはいけないこと

• _init() で AutoLoad にアクセスしないでください — AutoLoad は順次初期化されます。_init() でアクセスすると、参照が null になることがあります。
• _ready() でシングルトンのサイズや子ノードを変更しないでください — 起動時に複数のシングルトンが互いのツリーを参照すると、レイアウトや並べ替えのエラーが発生することがあります。
• AutoLoad に局所的でシーン固有のデータを保存しないでください — 「God Object」が生まれ、デバッグが難しいグローバルな副作用が発生します。
• Autoload から Parent.method() を呼び出さないでください — Autoload はルートに配置されており、最上位にあたります。アクティブなシーンとの通信にはシグナルを使用してください。
• 純粋なデータコンテナに Autoload を使用しないでください — _process() やシグナルが不要な場合は、代わりに class_name スクリプトの static var を使用してください。
• シングルトン間に循環依存を作成しないでください — A が B を必要とし、B も A を必要とすると、Godot はスプラッシュ画面でハングします。
• Autoload ノードを手動で解放しないでください — ルートからシングルトンを削除すると、参照が宙ぶらりんになり、エンジンがクラッシュすることがあります。
• グローバルではない UI 要素に AutoLoad を使用しないでください — 1 つのレベルにしか存在しないポップアップは、グローバルなシングルトンではなく、そのレベルに配置してください。
• _ready() で get_tree().current_scene が正確だと思い込まないでください — Autoload では、アクティブなシーンがまだ初期化中の場合があります。get_tree().root.get_child(-1) からアクセスしてください。
• process_mode の設定を省略しないでください — ゲームが一時停止中でもグローバルコンソールや音楽マネージャーを動作させる必要がある場合は、process_mode = PROCESS_MODE_ALWAYS に設定してください。

---

AutoLoad を使用する場面

適しています： ゲーム／オーディオ／セーブマネージャー、SceneTransitioner、グローバルなスコア／インベントリ、シーン間の EventBus。

避けてください： シーン固有のロジック、一時的な状態、純粋なデータ（static／Resource を優先）、小規模なプロジェクトでの過剰な設計。

---

エキスパート向けアーキテクチャパターン

1. 起動順序と依存関係図

必須：Autoload の順序を描画または信頼する前に、autoload_init_order_diag.gd と singleton_dependency_diagram.gd を読んでください。

Autoload はプロジェクト設定の上から下へ初期化されます。上位のシングルトンから下位のシングルトンを _ready() で呼び出してはいけません。依存する側をリストの下へ移動してください。

graph TD
    subgraph Autoloads [Project Settings order]
        B[1. GlobalAudio] --> C[2. ServiceLocator]
        C --> D[3. QuestManager]
    end
    D --> E[Current Scene]
    E -->|Queries| C

2. サービスロケーター（Node を使わない DI）

必須：Engine.register_singleton を使う前に、service_locator.gd と service_registry.gd を確認してください。

軽量な RefCounted サービスに使用してください。エンジンのシングルトンが宙ぶらりんになるのを防ぐため、_exit_tree で登録を解除してください。

3. イベントバスと状態保持オブジェクト

必須：システム間で過去形のイベントを扱うには、global_event_bus.gd を使用してください。変更可能な実行時状態はバスではなく、persistent_data_holder.gd と global_game_state.gd に保持してください。

4. Autoload から安全にシーンを切り替える

必須：safe_scene_switcher.gd を使用してください。遅延解放とルートの所有権を扱います。スレッド読み込みには godot-scene-management を併用してください。

5. ヘルスチェック

デバッグ／CI では必須：singleton_health_check_test.gd と autoload_reference_checker.gd を使用して、assert による存在確認と、登録済みサービスに対する Engine.has_singleton を行ってください。

専門家の知見（理由 — 本文に残してください）

• 起動順序 — 理由：Autoload はプロジェクト設定の上から下へ初期化されます。上位のシングルトンから下位のシングルトンを _ready() で呼び出してはいけません（autoload_init_order_diag.gd）。
• サービスロケーターと Node Autoload の比較 — 理由：RefCounted サービスは SceneTree のオーバーヘッドを回避できます。Engine.register_singleton で登録し、_exit_tree で登録を解除してください（service_locator.gd）。
• イベントバスと状態の比較 — 理由：バスは過去形のイベントを発行します。変更可能な実行時状態は、バスではなく persistent_data_holder.gd に保持します。
• _ready() 内の current_scene — 理由：アクティブなシーンのマウントがまだ完了していない場合があります。get_tree().root.get_child(-1) を使用するか、シーンの準備ができるまで処理を遅延させてください。

詳細なレシピ（必要に応じて）

トピック	参考資料／スクリプト
サービスロケーター／起動順序図／ヘルスチェック	expert-patterns.md
初心者向けの登録のみ	autoload-patterns.md

参考資料

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

公式ドキュメント

• シングルトン（AutoLoad） — AutoLoad が /root の下に登録され、グローバル名になる仕組みと、起動順序が「プロジェクト設定」のリスト順に従う理由を解説します。
• Autoload と通常のノードの違い — グローバルシングルトンを使うべき場合と、シーンが所有するノードや静的ヘルパーを使うべき場合を判断するためのガイドです。
• シーンの構成 — マネージャーがゴッドオブジェクト化しないよう、シーン固有のデータを AutoLoad に置かない方法を解説します。
• ロジックの選択基準 — ゲームプレイの制御では、Autoload のツリーを直接参照するより、シグナルと所有関係を優先する方法を解説します。
• SceneTree の使用 — Autoload の _ready() 実行中に current_scene が不確実になり得る理由と、ルートの子ノードとアクティブシーンの関係を解説します。
• シーンを手動で切り替える — 安全なグローバルシーン切り替えの背後にある、遅延解放とルートへの再親付けのパターンを解説します。
• ゲームの一時停止 — get_tree().paused 中も実行する必要があるコンソール、音楽、マネージャー向けの process_mode / PROCESS_MODE_ALWAYS を解説します。
• オーバーライド可能な関数 — 起動時に Autoload 間でアクセスした際に null に遭遇しないよう、_init と _ready の実行タイミングを解説します。
• シグナルの使用 — 固定のノードパスに依存せずシーンを疎結合にする、Autoload イベントバス向けのシグナル発行・接続モデルを解説します。
• Engine — SceneTree ノードではない軽量なサービスロケーター向けの register_singleton / get_singleton を解説します。
• スレッドセーフな API — バックグラウンドスレッドからグローバルな Autoload の状態にアクセスする際に、Mutex / call_deferred が必要となるエンジン API を解説します。
• ゲームの保存 — 長期間存続する Autoload のデータホルダーに保持されたインベントリや設定の永続化パターンを解説します。

関連スキル

前提条件

• godot-project-foundations — AutoLoad のエントリーは「プロジェクト設定」 / project.godot にあります。マネージャーを接続する前に、登録と命名を正しく設定してください。
• godot-gdscript-mastery — このスキルのパターンでは、型付きシグナル、static var / class_name、遅延呼び出しといった言語機能を前提としています。
• godot-signal-architecture — 循環するシグナル発行チェーンを避けながら Autoload の仲介役を実現する、イベントバスと Signal-Up の契約を解説します。

補完

• godot-scene-management — 安全なシーン切り替え機能と組み合わせることで、遷移処理がロード／アンロードを担い、AutoLoad がシーンをまたぐ状態を保持します。
• godot-save-load-systems — 永続的な Autoload ホルダーが保持するデータをシリアライズします。GameManager 内に別のセーブ経路を作らないでください。
• godot-resource-data-patterns — 共通設定には Resources を優先します。AutoLoad はライフサイクルとシグナル用に限定し、データの重複保持には使わないでください。
• godot-composition — 「マネージャー Autoload」が実際にはシーンスコープの動作を装っている場合に、コンポーネントの所有権という代替案を検討します。
• godot-audio-systems — 音楽／SFX プールは Autoload の典型的な用途です。それらのマネージャーの所有権と起動順序には、このスキルを使ってください。
• godot-state-machine-advanced — グローバルな MENU／PLAYING／PAUSED FSM は、Autoload がゲームロジック全体ではなく、単に所有者である場合にここで扱います。
• godot-debugging-profiling — 起動時に停止する場合、初期化順序の診断やシングルトンのヘルスチェックを、デバッガー／プロファイラーのワークフローへと発展させます。

下流／利用側

• godot-performance-optimization — Node Autoload の増えすぎ、先行プリロード、またはフレームごとのマネージャー処理がプロファイラーで確認された場合は、このスキルを使って詳しく調査します。
• godot-testing-patterns — 登録済みシングルトンの GUT／CI ヘルスチェックと、テスト間のグローバル状態のリセットに使います。
• godot-multiplayer-networking — グローバル状態を持つ Autoload は権限管理／レプリケーション上のリスクになります。オンラインでは、このスキルの DI パターンを慎重に使用してください。
• godot-inventory-system — change_scene_to_file() をまたいで保持する必要があるインベントリの永続的な Autoload ホルダーを、一般的に利用します。

マスター

• godot-master — ライブラリのルーターであり、ミラーされたモジュールのエントリーポイントです。複数領域にまたがるシングルトンの懸念をどのドメインスキルが担当するかを調べる際に開いてください。