godot-builder

Godot Builder スキル

godot-builder スキルは、Godot 4.7-stable CLI を使用したプログラムによるゲーム開発とヘッドレス自動化のための、エキスパートレベルの基盤を提供します。GODOT_PATH および GODOT_CONSOLE_PATH 環境変数でパスを上書きできます。

エキスパート向け自動化の考え方

• XDG によるヘッドレス分離：複数の Godot インスタンスを同時に実行する場合は、インスタンス間のキャッシュ破損を防ぐため、必ず XDG_DATA_HOME と XDG_CONFIG_HOME を上書きしてください。
• キャッシュの無効化（強制インポート）：変更されたグローバルインポート設定をエンジンに再評価させるには、プログラムから .godot/imported/ ディレクトリを削除してください。
• 明示的な所有権：シリアライズ時に破棄されないよう、シーンノードの owner プロパティはシーンのルートに設定する必要があります。
• レイテンシーに配慮したマルチスレッド：パイプラインの停止やデッドロックを避けるため、GPU とのやり取り（テクスチャ、画像データ）はメインスレッドで行う必要があります。

厳守すべきアンチパターン（絶対にしないこと）

• 絶対に、実行時に生成された UID をヘッドレスで保存しないでください。ResourceSaver.save() はヘッドレスモードでは UID をシリアライズしません。後処理として godot -e --headless --import を実行してください。
• Godot 4.4 以降では、絶対に Resource.duplicate(true) を使用しないでください。プロシージャルな状態の漏洩を防ぐため、duplicate_deep(Resource.DEEP_DUPLICATE_ALL) を使用してください。
• 絶対に .tscn または .tres 拡張子をハードコードしないでください。エクスポートされたバイナリビルドでの失敗を避けるため、常に uid:// を使用するか、拡張子なしで読み込んでください。
• 絶対に、GPU に依存する呼び出しをセカンダリスレッドで実行しないでください。RenderingServer.call_on_render_thread() を使用してください。
• 専用サーバービルドでは、絶対に Shader Baker を有効にしないでください。ヘッドレスバックエンドでは無視されます。
• has_id() を先に呼び出さずに、絶対に ResourceUID.set_id() を呼び出さないでください。致命的な CLI クラッシュが発生します。
• 最初のフレームにプログラムから低レベルの CanvasItems を移動するときは、絶対に RenderingServer.canvas_item_reset_physics_interpolation() を省略しないでください。省略すると、レンダリングシステムと物理システムの間で視覚的な同期ずれが発生します。

エキスパート向け自動化ワークフロー

単一のタスクのためにスクリプトカタログ全体を読み込まないでください。現在のワークフローで必須とされているスクリプトのみを読み込んでください。薄いプロセスラッパー（launch_editor.py、run_project.py、stop_project.py、get_*、list_projects.py）は付録にあります。該当する CLI 操作が必要でない限り、事前に読み込まないでください。

ワークフロー #1：堅牢な 3D アセットパイプライン

目的：正確な物理コリジョンを備えた、本番環境で使用可能なシーンに、生の 3D アセットを取り込む処理を自動化します。

• 必須 — CLI フラグを独自に試す前に読むこと：gltf_processor.py → collision_generator.py → save_scene.py。その後、godot -e --headless --import（または import_automator.py）を実行してください。別のフラグ順を独自に考案しないでください。
• 手順：gltf_processor.py -> collision_generator.py -> save_scene.py -> ヘッドレス --import。
• エキスパート向けの対策：すべてのノードに明示的な owner を設定します。UID のシリアライズ漏れを修正するため、最後にヘッドレスインポートを実行します。
• 失敗モード／フォールバック：
  • ヘッドレス保存後に UID がない：想定どおりです。ResourceSaver はヘッドレスでは UID をシリアライズしません。フォールバック：--import を再実行してください。それでも UID がない場合は、インポート完了後に update_project_uids.py を実行してください。
  • インポートがハングする／終了しない：スクリプトで quit() が省略されているか、エディターのインポートが GPU の待機中です。フォールバック：後処理スクリプトで get_tree().quit() が呼び出されることを確認してください。stop_project.py を使って PID を終了し、XDG_* による分離を行って再試行してください。
  • コリジョンメッシュが空／不正：ソースの glTF にメッシュ配列がないか、ノードパスが間違っています。フォールバック：コリジョンを再生成する前に、gltf_processor.py の出力シーンを確認してください。

ワークフロー #2：プロシージャルレベルの最適化と 4.4+ へのスケーリング

目的：インスタンス間で共有リソースの状態が破損することなく、最適化されたプロシージャルレベルのチャンクを生成します。

• 必須 — 独自の方法を試す前に読むこと：csg_optimizer.py → navmesh_baker.py。ベイクの各ステップの間に duplicate_deep(Resource.DEEP_DUPLICATE_ALL) を適用してください。duplicate(true) は使用しないでください。
• 手順：csg_optimizer.py -> duplicate_deep(ALL) -> navmesh_baker.py。
• 専門的な対策：duplicate_deep を使用してマテリアル／リソースを分離します。NavMesh のパス検索を実行する前に、CSG を静的ジオメトリにベイクします。
• 失敗モード／代替策：
  • 実行中の CSG に対する NavMesh のベイク：パス検索に穴ができる／領域が空になります。代替策：navmesh_baker.py の前に、CSG から静的メッシュへのベイクが完了していることを確認してください。
  • チャンク間でマテリアル／状態が漏れる：浅い複製を使用しています。代替策：インスタンスごとに DEEP_DUPLICATE_ALL を指定して再ベイクしてください。
  • ヘッドレスベイクのハング：ベイク後に quit() がありません。代替策：明示的に終了処理を追加し、XDG_DATA_HOME／XDG_CONFIG_HOME で分離してください。

ワークフロー #3：本番環境の CI/CD と強制インポート検証

目的：クロスプラットフォームビルドを検証し、グローバルなプロジェクト設定（VRAM 圧縮）が確実に適用されるようにします。

• 必須 — エクスポートフラグを独自に設定する前に読むこと：test_runner.py → profile_generator.py → ci_export_prepper.gd → ci_exporter.py。
• 手順：rm -rf .godot/imported -> test_runner.py -> profile_generator.py -> ci_exporter.py。
• 専門的な対策：完全な再インポートを強制し、アセット圧縮を検証します。XDG 変数を使用して CI の実行を分離します。環境変数から安全なキーストアのパスを設定します。
• 失敗モード／代替策：
  • エクスポートプリセットがない／対象プラットフォームが違う：対象に合わせて export_presets.cfg が変更されていません。代替策：--export-release の前に、ci_export_prepper.gd をヘッドレスで実行してください。プリセット名が CI マトリックスと一致することを確認してください。
  • ヘッドレス CI がハングする（終了しない）：スクリプトで quit() が呼び出されていません。代替策：-s スクリプトは必ず quit() で終了してください。終了しないハングは強制終了として扱い、XDG で分離して再試行してください。
  • キャッシュ消去後に UID／インポート検証が失敗する：再インポートが完了していません。代替策：--import を再実行してから update_project_uids.py を実行してください。インポートが正常に完了するまではエクスポートしないでください。

---

自動化と CI/CD パイプライン（Godot 4.7）

プロフェッショナルな Godot のビルドでは、アセットとバイナリエクスポートに「ゼロタッチ」の考え方が必要です。

1. プログラムによるアセットの再インポート

• 絶対に、圧縮設定を変更するために 500 個のテクスチャを手動で選択しないでください。
• ConfigFile を使用して .import ファイルを変更し、EditorFileSystem.reimport_files() を使用してメインスレッド上で安全に一括更新を実行してください。

2. 孤立アセットの検出（スロップスキャン）

• 絶対に、res:// がクリーンだと信頼しないでください。時間が経つと、削除したシーンが孤立したテクスチャやサウンドを残し、最終ビルドが肥大化することがあります。
• ResourceLoader.get_dependencies() を使用して、「メインシーン」にリンクされたアセットを正確に再帰的に追跡し、それ以外をスロップとして検出してください。

3. ヘッドレス CI/CD コンテキスト

• 最終的な --export-release を実行する前に、バージョン管理タスク（export_presets.cfg の変更）には --headless --script を使用してください。
• ヒント：ヘッドレススクリプトの最後には必ず quit() を呼び出してください。そうしないと CI ランナーが延々とハングします。

---

エキスパート向けパイプラインスクリプト（必要に応じて読み込む）

主要な自動化スクリプトです。該当するワークフローで必要になった場合にのみ開いてください。

シーンとアセットのパイプライン

• gltf_processor.py：.glb/.gltf の生アセットをヘッドレスで Godot シーンに変換します。
• collision_generator.py：メッシュデータから ConcavePolygonShape3D の物理形状を生成します。
• save_scene.py：現在のノードツリーを安全にパックしてディスクに保存します（先に owner を設定してください）。
• csg_optimizer.py：プロシージャルな CSG ブーリアン演算をベイクして静的メッシュにします。
• navmesh_baker.py：非同期のヘッドレス NavMesh 経路探索のベイク処理を実行します。
• tilemap_generator.py：JSON データから TileMapLayer グリッドをプロシージャルに構築します。
• ui_assembler.py：標準化された JSON 構造から複雑な GUI レイアウトを構築します。
• create_scene.py / add_node.py / load_sprite.py：プログラムでシーンツリーを構築します。
• export_mesh_library.py：3D シーンを GridMaps 用の .meshlib リソースに変換します。
• orphan_asset_scanner.gd：未使用リソースを特定するための再帰的な依存関係トレーサーです。

CI／インポート／エクスポートのパイプライン

• ci_exporter.py：マルチプラットフォームのリリースエクスポートをヘッドレスで統括します。
• ci_export_prepper.gd：export_presets.cfg のヘッドレスバージョニングスクリプトです。
• profile_generator.py：モジュール削除最適化用の機能プロファイルを生成します。
• test_runner.py：ヘッドレスで単体テストと統合テスト（GUT/doctest）を実行します。
• import_automator.py / asset_reimport_utility.gd：インポートを一括で適用します。
• update_project_uids.py / get_uid.py：ヘッドレス保存後に UID を同期します。
• config_compiler.py：JSON/CSV データを最適化された .cfg 設定ファイルにコンパイルします。

付録：薄いプロセスラッパー（事前ロードしないでください）

利便性を高めるための CLI のみです。専門的なパイプラインの説明ではありません。該当するプロセス操作が必要な場合に読み込んでください。

• launch_editor.py / run_project.py / stop_project.py：エディター／ゲームのプロセスのライフサイクルを管理します。
• get_debug_output.py / get_godot_version.py / get_project_info.py / list_projects.py：読み取り専用でプロジェクト／プロセスの内部情報を確認します。

リファレンス

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

公式ドキュメント

• コマンドラインチュートリアル — すべてのビルドラッパーが呼び出す --headless、--path、-s／--script、--import、--export-* フラグについて説明しています。
• プロジェクトのエクスポート — エクスポートプリセット、CLI でのリリース／デバッグエクスポートの流れ、CI で --export-release の前に export_presets.cfg を変更する必要がある理由について説明しています。
• 機能タグ — モジュールの除外や、OS.has_feature を使った CI スモークパスの制御に使用するカスタムタグ／機能プロファイルタグについて説明しています。
• 専用サーバー向けのエクスポート — GPU ベイクを前提としないヘッドレス／サーバー向けエクスポートの制約について説明しています。XDG 変数による CI 分離と組み合わせて使用します。
• インポート処理 — .import と .godot/imported のライフサイクル、およびインポートキャッシュを削除するとプロジェクト全体の再検証が必要になる理由について説明しています。
• 3D シーンのインポート — GLTFDocument／ResourceSaver による自動化の前段となる、glTF からシーンへのパイプラインの入口です。
• 利用可能な 3D 形式 — ヘッドレスコンバーターとコリジョン生成における glTF／GLB の前提について説明しています。
• CSG ツールの使用 — 出荷前や NavMesh のベイク前に、プロシージャル CSG を静的メッシュにベイクする必要がある理由について説明しています。
• NavigationMeshes の使用 — CSG／静的ジオメトリの追加後に行う、ヘッドレス NavMesh ベイクの管理とリージョン設定について説明しています。
• ResourceUID — ヘッドレス保存後に行う安全な has_id／set_id／uid:// 同期について説明しています（UID はヘッドレスの ResourceSaver ではシリアライズされません）。
• ResourceSaver — プログラムによる .tscn 書き込み用のパック／保存 API について説明しています。PackedScene.pack の前にオーナーを設定する必要があります。
• EditorFileSystem — @tool EditorScripts から一括インポートを強制するための reimport_files() について説明しています。

関連スキル

前提条件

• godot-project-foundations — CLI の起動／インポート／エクスポート自動化の前に、機能フォルダー、project.godot のメタデータ、VCS の除外設定が必要です。
• godot-gdscript-mastery — すべての -s スクリプトで使用する、ヘッドレスの SceneTree ワーカー、型付き Resources、quit() のライフサイクルパターンについて説明しています。
• godot-resource-data-patterns — ビルダーの実行間でプロシージャルな状態が漏れるのを防ぐ、PackedScene、UID パス、ディープ複製のルールについて説明しています。

補完

• godot-version-migration — CI／ヘッドレスのターゲットエンジンを更新する場合は、新しい API を使う前に移行ハブを経由して段階的に進めます。
• godot-export-builds — ci_exporter.py によるオーケストレーションに加えて適用する、プラットフォームテンプレート、コード署名／キーストア、フィルタールールを扱います。
• godot-3d-world-building — このスキルがヘッドレスでベイクおよびエクスポートする、CSG／GridMap／MeshLibrary の作成を扱います。
• godot-navigation-pathfinding — navmesh_baker.py が生成した NavMesh を使用する、ランタイムエージェントとレイヤーコストを扱います。
• godot-tilemap-mastery — tilemap_generator.py が生成するシーン向けの TileSet／TileMapLayer の規約を扱います。
• godot-ui-containers — ui_assembler.py が絶対座標での Control の位置指定ではなく、出力すべきコンテナレイアウトのルールを扱います。
• godot-physics-3d — collision_generator.py が作成するトライメッシュボディの、コリジョンレイヤー／形状を扱います。

下流／利用側

• godot-testing-patterns — インポート／エクスポート後に、CI で test_runner.py を通じて実行する GUT／統合テストスイートを扱います。
• godot-performance-optimization — 孤立ファイルのスキャン、インポート時の圧縮、エクスポートサイズが引き続き予算を超える場合に、対応を引き継ぎます。
• godot-monte-carlo-balancer — ビルダーの CI スモークテストに合格した後、バランスシミュレーション向けのヘッドレス test_runner 調整ループを扱います。
• godot-debugging-profiling — GUI なしでのヘッドレスインポート／エクスポートが失敗した場合に、get_debug_output.py のログを利用します。

マスター

• godot-master — ライブラリのルーターおよびミラーされたモジュールのエントリです。複数領域にまたがるビルド／自動化の課題を担当するドメインスキルを探す際に開いてください。