godot-project-foundations

プロジェクトの基盤

機能ベースの構成、一貫した命名、バージョン管理の徹底が、プロフェッショナルな Godot プロジェクトを支えます。

利用可能なスクリプト

コアの足場（状態を保持／永続）

• project_bootstrapper.gd：機能フォルダーと .gitignore を自動生成します。
• runtime_configurator.gd：高パフォーマンスプロファイルを適用し、override.cfg を保存します。
• managed_autoload.gd：RefCounted による委譲を用いた高度なシングルトンパターンです。
• global_event_bus.gd：疎結合なグローバルシグナルに必須です。チャット内で EventBus のサンプルを再度記述しないでください。
• node_pooling_system.gd：高頻度のシーンインスタンス化に対応する、スレッドセーフなオブジェクトプールです。
• async_resource_loader.gd：スレッドを使ったシーン遷移に必須です。チャット内で SceneManager のサンプルを再度記述しないでください。

ランタイムユーティリティ（状態を持たない／軽量）

• base_data_resource.gd：emit_changed() を使用するリアクティブな Resource の基盤です。
• advanced_telemetry_logger.gd：クラッシュレポート用のカスタム OS レベル Logger です。
• threaded_task_worker.gd：堅牢な WorkerThreadPool の実装です。
• action_buffer_input.gd：基礎となる _unhandled_input バッファーです。
• build_metadata_provider.gd：バージョンとビルドメタデータをネイティブに取得します。
• feature_scaffolder.gd ／ scene_naming_validator.gd：機能フォルダーと命名規則のチェック機構です。

読み込まないでください：読み込みエラーのトラブルシューティングを行う場合を除き、dependency_auditor.gd を読み込まないでください。

絶対に避けること（エキスパート向けアンチパターン）

グローバルアーキテクチャ

• ファイルの種類で分類しないでください — /scripts、/sprites フォルダーは保守性を著しく損ないます。機能ベースで /player、/ui のように構成してください。
• ファイル名に snake_case と PascalCase を混在させないでください — 標準は、ファイル名に snake_case、ノード名に PascalCase です。
• ハードコードした get_node() パスを使用しないでください — 親の付け替えに弱くなります。安定した参照には %SceneUniqueNames を使用してください。
• モノリシックな Autoload を使用しないでください — ビジュアルノードへの参照を保持するマネージャーは避け、シングルトンは純粋なデータまたは RefCounted による委譲に専念させてください。

リソース管理

• .gitignore を忘れないでください — .godot/ フォルダーをコミットすると、100MB 以上の肥大化と競合を招きます。
• 生のアセットに .gdignore を設定してください — ルートにあるデザインソースファイル（.psd、.blend）は、無視しないとインポートされます。
• グローバルで共有されている Resource を直接変更しないでください — 独立した状態を持つ固有のインスタンスには、必ず duplicate(true) を呼び出してください。

パフォーマンスとスレッド処理

• load() でメインスレッドをブロックしないでください — 非同期のシーン遷移には、必ず ResourceLoader.load_threaded_request() を使用してください。
• バックグラウンドスレッドから SceneTree を変更しないでください — スレッドからメインスレッドへの同期には、必ず call_deferred() を使用してください。
• プールへのアクセス時に Mutex ロックを省略しないでください — 共有の WorkerThreadPool またはオブジェクトプールを使用する際は、必ずスレッドセーフを確保してください。
• 正確な入力処理に _process() を使用しないでください — 描画フレームレートに依存します。フレームに依存しない正確なイベントを捕捉するには、必ず _unhandled_input() を使用してください。

---

所有権の判断ツリー

必要なもの	優先するもの	避けるもの
1 つの機能（プレイヤー、HUD パネル）に関するすべて	機能フォルダーのシーンモジュール	種類別フォルダー（/scripts、/sprites）
ライフサイクルを持つシーン間サービス（セーブ、オーディオバス）	managed_autoload.gd を使った Autoload	UI ノードをシングルトンに詰め込むこと
所有者を持たない、多数のパブリッシャー／サブスクライバー	EventBus → 必須の global_event_bus.gd	ゲームの半分をインポートする Autoload
1 つのシーン内のプライベートな接続	シーンローカルノード + %UniqueName	親から子への呼び出しにグローバルバスを使うこと

---

1. 命名規則

• ファイルとフォルダー：snake_case（C# の例外：クラス名と一致する PascalCase）。
• ノード名：PascalCase。
• エクスポート：snake_case。インスペクターではタイトルケースで表示されます。
• プライベート：メンバーと仮想メソッドの先頭に _ を付けます（_ready、_process）。
• シグナル：過去形の snake_case（health_changed）。
• 一意な名前：壊れやすい get_node() のパスではなく、%SceneUniqueNames を使用します。

2. 機能ベースの構成

ファイルの種類ではなく、機能ごとにグループ化します（/entities/player、/ui/main_menu）。/common、/levels、/addons は維持します。

3. バージョン管理

Godot 対応の .gitignore（.godot/ を無視）を設定し、生のデザインソースには .gdignore を配置します。

ワークフロー：新規プロジェクトのひな形作成

1. project.godot が存在することを確認し、project_bootstrapper.gd を実行するか、entities/、ui/、levels/、common/ を作成します。
2. Git の .gitignore を設定し、機能ベースの構成を README.md に記載します。
3. 所有権の判断ツリーに従って必要と判断された場合にのみ、最小限のオートロードを登録します。

型付き GDScript の厳格化（基盤のみ）

型付き GDScript への完全な移行については、godot-gdscript-mastery を参照してください。 新しい基盤プロジェクトでは、Project Settings → Debug → GDScript → Untyped Declaration を Warn または Error に設定します。

エキスパート向け基盤アーキテクチャ

シーン遷移

スレッド処理と進捗表示に対応した ResourceLoader を使うため、async_resource_loader.gd を必ず読み込みます。ここに SceneManager のサンプルを貼り付けないでください。

グローバルイベントバス

型付きのグローバルシグナルを使うため、global_event_bus.gd を必ず読み込みます。ここに EventBus のサンプルを貼り付けないでください。

プロジェクトのメタデータ

場当たり的な JSON ではなく、バージョンやビルドフラグには build_metadata_provider.gd と base_data_resource.gd を使用します。

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

命名規則の完全な一覧、型付き GDScript への移行、EventBus／SceneManager／メタデータのサンプルについては、references/foundations-deep.md を参照してください。

参考資料

段階的な情報開示：特定の API を調査するときにのみ公式ドキュメントのリンクを開き、関連分野に進むときにのみ関連スキルを読み込みます。関連スキル全体をあらかじめ読み込まないでください。

公式ドキュメント

• プロジェクトの構成 — インポートとリポジトリを保守しやすくする、機能ベースのフォルダー、.gdignore、VCS の衛生管理について説明しています。
• シーンの構成 — 所有権の境界と、壊れやすい get_node() パスより %SceneUniqueNames が優れている理由について説明しています。
• GDScript スタイルガイド — このスキルのバリデーターで使用される、正式な snake_case のファイル名、PascalCase のノード名、過去形のシグナル名について説明しています。
• GDScript 警告システム — 基盤を GDScript 2.0 に移行する際に、型付き宣言（Untyped Declaration → Warn/Error）を強制する方法について説明しています。
• シングルトン（Autoload） — シーンの変更後も存続する、軽量なグローバルサービスの登録方法について説明しています。
• Autoload と通常のノードの比較 — Managed Autoload / EventBus が適切な場合と、シーン内で所有する場合について説明しています。
• バックグラウンド読み込み — ブロックしないシーン遷移のための ResourceLoader.load_threaded_* パターンについて説明しています。
• リソース — 共有された Resource インスタンスと複製された Resource インスタンスの違い、およびグローバルな変更が機能モジュールを壊す理由について説明しています。
• ノードとシーンインスタンス — インスタンス化、プーリング、機能フォルダーにおけるシーンとモジュールの境界について説明しています。
• SceneTree の使用 — ツリーのライフタイム、遅延呼び出し、スレッドからメインスレッドへの同期ルールについて説明しています。
• Godot プロジェクトのファイルパス — スキャフォールドされたフォルダーと、保存された override.cfg / メタデータにおける res:// / user:// の規約について説明しています。
• ProjectSettings — コンフィギュレーターとビルドメタデータで使用される、実行時プロファイル、バージョン文字列、設定キーについて説明しています。

関連スキル

前提条件

• godot-gdscript-mastery — 命名規則とスキャフォールド規約を適用する前に必要となる、型付き GDScript、スタイル、警告システムへの習熟について説明しています。

補完

• godot-version-migration — 古いエンジンバージョンでプロジェクトを開く、またはひな形を作成する場合は、最新の基盤を適用する前にライブラリの対象バージョンへ切り替えます。
• godot-autoload-architecture — クリーンなプロジェクトルートから登録する Managed Autoload／EventBus シングルトンの起動順序と所有権のルールです。
• godot-composition — 機能フォルダーを組み合わせ可能なシーンモジュールにし、モノリシックなマネージャーを肥大化させるのではなく、親が子を接続します。
• godot-resource-data-patterns — BaseDataResource スタイルのリアクティブな Resource を、共有状態を変更しないデータ駆動型カタログへと拡張します。
• godot-signal-architecture — Autoload とシーンの所有権を整えた後の、型付き EventBus シグナルと接続のライフタイムです。
• godot-scene-management — スレッド化ローダーとシーンの切り替えは、このスキルの非同期 ResourceLoader ボイラープレートを基盤とします。
• godot-input-handling — _unhandled_input のバッファリングを、包括的なアクションマップとデバイスルーティングへと発展させます。

下流／利用側

• godot-export-builds — エクスポートプリセットと機能タグは、整ったフォルダーレイアウト、.gitignore、ビルドメタデータのフックを前提とします。
• godot-testing-patterns — 機能ベースのシーンと決定論的な Autoload によって、ユニット／統合テストのハーネスを組み込みやすくなります。
• godot-debugging-profiling — カスタム Logger のテレメトリーと依存関係の監査により、構造が安定した後のエディター実行時診断が可能になります。
• godot-performance-optimization — 基盤が CPU／メモリの上限に達した際は、ノードプール、WorkerThreadPool、ランタイムプロファイルを使った最適化に進みます。

マスター

• godot-master — ライブラリのルーターであり、ミラー化されたモジュールのエントリーポイントです。複数領域にまたがるアーキテクチャ上の課題を担当するドメインスキルを特定する際に開いてください。