scenario-godot-expert

Godot のエキスパート（テクニカルディレクターとエージェントプロトコル）

対象：Godot 4.7.2.stable（標準ビルド、C# なし）、デフォルトで Metal を使用する macOS Apple Silicon、または D3D12 を使用する Windows。

Godot のエキスパート作業は、証拠に基づくループで進めます。予算を設定し、ステージを 1 つ構築して測定し、確認して修正し、次へ進みます。マウスを使えないエージェントは、適切なチャンネルを選び、機械可読な結果が得られた場合にのみ合格とし、単一のシグナルを決して過信しないことで、この作業を実現します。このスキルはそのプロトコルであり、すべての scenario-godot-* スキルが呼び出す共通ツールキット（scripts/）であり、チームの構成を示すマップです。ここに記載された兄弟スキルが利用可能なスキルにない場合は、ユーザーにインストールを依頼してください（npx skills add scenario-labs/skills --skill <name>）。無人で進める場合は、ツールのスキーマをもとに作業を続け、欠落を明示してください。

ステータス（2026-10-02）： 以下のすべてのツールキット関数は、ここで Godot 4.7.2 上で実行済みです（ライブテスト 23 件、オフラインテスト 17 件、すべて合格。詳細は references/procedures.md を参照）。

スタンス（専門家の見解との差分）

1. 真実を示すのはヘッドレス出力であり、エディターの「出力」パネルではありません。 その内容を取得するMCP サーバーは、「ディスク上にもう存在しない行のエラーを報告」し、プロジェクトのエラーをすべて一覧表示するわけでもありません（Fennara、2vSYP7GyA5U [00:02:51, 00:06:20]）。PixelLab のエージェントは Godot バイナリを直接実行し、コンソールを読み取ります（THwZYWuOdZI [00:13:45]）。AGENT_RESULT エンベロープとログスキャンを通過条件にしてください。「終了した」ことだけを条件にしてはいけません。パースエラーのあるスクリプトは、--check-only の有無にかかわらず終了コード 0 を返します。また、Godot が見つけられないスクリプトパスでも同様です（バージョン差分で検証済み。L6）。
2. プロジェクトごとに書き込み元は1つにしてください。 GUI エディターでプロジェクトを開いていると、開いているシーンの独自のコピーが保持されるため、その後の保存でヘッドレス編集が上書きされることがあります［追加］。マージされた .tscn ファイルはパースに失敗する可能性があります（Lilith Duncan、CAJ_iIedx_I [00:01:36]）。このツールキットは、GUI の Godot で開かれているプロジェクトを拒否します。そのエディター（MCP）を通じて作業するか、ユーザーに閉じるよう依頼してください。自分で起動していない Godot または Blender のプロセスを、決して終了してはいけません［追加］。
3. 対象環境で、予算に対するミリ秒を測定してください。 最適化の前に測定します（Dan Does Dev、s2C2RO_WMh0 [00:07:12]）。熱特性も含め、実際のデバイスクラスでプロファイリングしてください（Ian Bolton、WrjaUNAXYqk [00:09:35]）。ヘッドレスのフレーム時間はループ時間であり、ゲームの負荷ではありません。この Mac でウィンドウ表示時のフレーム時間はディスプレイのリフレッシュレートに固定されます。gpu_ms と cpu_ms で判断してください（観測結果）。
4. 目で見て、チェックもしてください。 すべてのフレームを gd_review.image_checks に通し、自分で開くコンタクトシートも確認してください。ヘッドレスでは描画されないため、キャプチャにはウィンドウ表示での実行が必要です（観測結果）。AI アセットのインポート後は、向き、アニメーションの方向、タイルの継ぎ目、カメラの揺れを目視で確認してください（PixelLab、THwZYWuOdZI）。
5. テストが仕様です。 内部実装ではなく、シグナルと公開されている結果に対してアサーションしてください（Godotneers、CreugthdgJ0 [01:08:36]、Butch Wesley、ImqhHLlPfZg [00:16:59]、Mike Schulze、x6GdTgIAFiU [00:24:19]）。すべての await にタイムアウトを設定してください（Godotneers は2秒、Schulze は5秒）。関数を空にしてテストが失敗することを確認し、テストが機能していると証明してください（Wesley [00:13:40]）。
6. マウスなしで操作することを前提に設計してください。 本体と頭脳を分離し、テスト用の頭脳でキャラクターを動かせるようにします（Godotneers [00:18:14]）。ヘッドレス環境にはマウスデバイスがありません（Wesley [00:48:33]）が、それでも GUI 入力でヘッドレスをテストできます。get_viewport().push_input(event, true) は Controls に届きますが、Input.parse_input_event は MOUSE_FILTER_STOP の Control には届きません（scenario-godot-gameplay、scenario-godot-ui、観測結果）。位置をウィンドウのピクセルではなく論理座標として扱うため、true を渡してください。レベルにはプレイヤーではなくスポーン地点を保持させます（Godotneers [00:56:56]）。
7. 編集を永続化するには owner の設定と保存が必要です。 add_child だけではシーンドックに表示されず、保存時に失われます（Godot のドキュメント「Running code in the editor」）。スクリプト編集は EditorUndoRedoManager を介さない限り、Undo の対象になりません（Queble、nW7YtSSJzbQ [00:04:41]）。
8. ビジュアルエディターについては正直に伝えてください。 VisualShader、AnimationTree、TileSet とテーマのエディター、パーティクルインスペクターはビジュアルエディターです。エージェントは .gdshader や .tres／.tscn のテキストを記述するか、コードでリソースを作成し、人間向けに GUI での操作手順を示します。MCP はツールの数ではなく、フィードバックの忠実度で選んでください（Fennara [00:09:22]）。

実行チャネル

チャネル	用途	コスト（ここでの測定値）	ルール
ヘッドレスジョブ gd_run.run_script	ロジック、データ、監査、シーン構築、インポート、テスト、エクスポート	小規模なジョブで 0.2 秒、--import は約 2 秒	デフォルトのチャネルです。ハングしたジョブはウォッチドッグが終了させます（終了コード 124）。
ウィンドウ付きジョブ capture_scene、capture_sequence、profile_scene	レンダリングが必要なものすべて：スクリーンショット、シーケンス、GPU 時間	4 ビューをウォーム状態で約 1 秒、新規プロジェクトでの初回キャプチャは 10.8 秒、5 秒間のプロファイルは 29.6 秒	160x90 のウィンドウ、指定サイズの SubViewport、フォーカスを元に戻します（実行ごとに 2 回の復帰を確認）。GD_MAX_WINDOWED は 2
ヘッドレスエディター run_script(editor=True)	EditorInterface：シーンのオープン、編集、保存。EditorFileSystem	1.1 秒	エディター呼び出しの前に 2 フレーム待機します。-e を付けないと EditorInterface の呼び出しは失敗します（確認済み）。
GUI エディター + MCP（hybridindie godot-editor-mcp）	ユーザーが開いているエディター：ライブツリー、選択、元に戻せる編集	stdio のプローブは 0.9 秒、デフォルトで 23 個のツールを公開	ユーザーがエディターを開いている場合に限ります。プロジェクトローカルの .mcp.json のみを使用します（gd_live.write_mcp_config）。
実行中のゲーム + MCP（tugcantopaloglu）	実行中のゲームを操作（入力、評価）	ここでは実行していません	クローンを作成し、npm run build を実行し、ポート 9090 でゲームのオートロードを起動します。

gd_live.channels(P) は現在可能な操作を報告します。ヘッドレスチャネルを優先し、ライブシーンの検査には MCP を追加してください。

まず確認すること

一度にまとめて確認してから、次を実行します：対象プラットフォームと最低スペックのデバイス、フレーム予算（デフォルトはデスクトップ 60 fps、モバイル 30 fps）、2D または 3D、レンダラー（デスクトップ 3D では Forward+、高負荷なスマートフォンでは Mobile、Web と最も広い互換性には Compatibility。Ray Hayes、KWhVVMpihsc [00:06:03] に基づく）、アートスタイルとピクセルアートを使うかどうか、ユーザーがエディターでプロジェクトを開いているか、成果物。その後、gd_live.channels(P) と gd_run.audit(P, "project") を実行し、レンダラー、物理エンジン（3D では Jolt）、ストレッチモード、メインシーン、オートロードを計画に記載します。

ワークフロー（エキスパートループ）

1. 数値で概要を定めます。 プラットフォームごとの予算、解像度、スケール、スタイルを決めます。GATE：以降のすべてのチェックで比較する数値を用意します。
2. プロジェクトを作成します。 gd_env.base_project("3d"|"2d", dest)（APFS クローン、0.01 s、専用の user:// フォルダー）または new_project(...) を使います。後者は、手書きの project.godot にないプロジェクトマネージャーのデフォルト設定を書き込みます。GATE：audit(P, "project") にフラグがありません。
3. ベースラインを確認します。 check_all(P)、audit(P, "scene", scene=...)、固定ビューからのキャプチャ、パフォーマンスが重要な場合はプロファイルを実行します。GATE：解析エラーとスクリプトエラーがゼロで、フラグは修正済みまたは一覧化され、シートが開かれています。
4. 小さく冪等なジョブ（取得または作成、owner の設定、明示的な保存）でステージを1つ構築します。ドメインの作業は担当者に割り当てます（下記参照）。
5. 測定します。 監査、テスト（run_tests）、profile_scene と gd_stat.budget_check、またはエクスポート結果を確認します。GATE：数値を概要の数値と照合します。
6. 目で見て、チェックします。 同じビュー、image_checks、コンタクトシートを開き、ドメインスキルの批評に基づいて評価します。GATE：ok を false にするフラグがなく、変更が見えること（compare の changed_fraction が 0 を超えること）。
7. 次へ進む前に修正します。 一度に1つ変更し、compare で同等性または改善を証明します。
8. 証拠を添えて納品します。 各ステップで使用したツールキットの呼び出しを示し、その後に 検証済み（実行内容、結果ファイル、数値またはフレーム）と 想定（未実行の内容、デフォルト設定）を記載します。数値と目視したフレームなしに、シーン、シェーダー、レベル、ビルドを完了と呼んではいけません。

共有ツールキット（scripts/、すべての scenario-godot-* スキルで共通の仕様）

import sys; sys.path.insert(0, "<scenario-godot-expert>/scripts")。システムの python3 と標準ライブラリを使用します（Pillow は任意）。

すべての gd_env、gd_run、gd_review、gd_stat、gd_live の呼び出しについて、デフォルト設定と戻り値は references/procedures.md のセクション1を参照してください。よく使うもの：gd_env.new_project、gd_run.run_script、gd_run.capture_scene、gd_run.profile_scene、gd_run.export、gd_review.image_checks。

すべての gd_run 実行は、ok、error、result（ジョブの辞書）、exit_code、timed_out、parse_errors、script_errors、shader_errors、engine_errors、warnings、leaks、log_path、result_path を返します。出力は <project>/.agent_out/ に保存されます（.gdignore を含みます）。並行実行：Godot プロセスは GD_MAX（6）、ウィンドウ表示プロセスは GD_MAX_WINDOWED（2）、プロジェクトごとに1つに制限し、すべて gd_run.godot_slot を経由します。GUI エディターがプロジェクトを開いている場合は GodotBusy になります。

ドメインジョブは、プロジェクト内の GDScript ファイルです（AgentKit の scripts/agentkit/ は res://addons/agentkit/ にコピーされます）。

extends "res://addons/agentkit/agent_job.gd"
func run() -> Dictionary:
	var scene := await load_scene("res://main.tscn", 2)   # in the tree, 2 frames waited
	note("children", scene.get_child_count())
	return {"ok": true, "speed": arg("speed", 4.0)}       # arg() typed by its default

または、任意の RefCounted スクリプトのメソッドを run_script(P, "res://tools/x.gd:build", args) で呼び出せます（ジョブが渡されます）。expect_errors が設定されていない場合、ジョブ中にログに記録されたエラーによって ok が false になります。スクリプトエラーが発生すると、型付きの run() -> Dictionary は中断され、{} を返します。空の結果は expect_errors の設定にかかわらず常に失敗となり（aborted: true）、そのため少なくとも {"ok": true} を返してください。export は書き込んだすべてのファイルの bytes（指定したファイルは main_bytes）を報告し、iOS の export_project_only Xcode プロジェクトを artifact として扱います。キャプチャは黒帯を付けてプロジェクトのストレッチ設定（keep、keep_width、keep_height、expand、ignore、整数スケール、スケール係数、ビューポートモード）を再現し、15ケース（L20）でエンジンと一致します。独自のジョブでは、make_viewport SubViewport を agent_capture.grab(vp) で読み取ってください。ヘルパー：arg、out_path、load_scene、wait_frames、wait_physics_frames、wait_seconds、note、is_headless、captured_errors。ライブラリは agent_build.gd（save_scene、プリセット）と agent_profile.gd（record）です。ドメインコードは scripts/gd_<domain>.py と scripts/agentkit/<domain>/ に配置します。

数値

値	比較対象	出典
16.67 / 33.33 ms	60 / 30 fps でのフレーム予算	算術
8.33 ms	この 120 Hz ディスプレイでのウィンドウ表示時の frame_ms の下限。--disable-vsync を指定した場合も同じです	実測
6.9 ms	ヘッドレス時のフレームペーシング：処理内容にかかわらず、低プロセッサ使用モードのスリープ（low_processor_usage_mode_sleep_usec 6900）。--fixed-fps 60 でベンチマークを実行し、処理時間を計測します	実測；scenario-godot-gameplay、scenario-godot-ui
1.4～1.8 ms / 0	Vulkan で 1080p において fx テストシーンを実行した際の GPU p95（4 回実行）／Metal での値	実測
0.2 s、10.2 s	小規模なジョブ；ウォッチドッグによって停止されたハングしたジョブ（タイムアウト 20 s）	実測
60.8 / 75.0 / 41.4 MB	Base3D の macOS ユニバーサル zip／Linux x86_64（バイナリと .pck）／Web（9 ファイル）向けエクスポート	実測、L9
430 MB	iOS Xcode プロジェクト（export_project_only）。大半はエンジンの xcframework です	実測、L9

品質ゲート

• 測定可能性： ok が true で、解析、スクリプト、シェーダーのエラーがゼロであること；check_all の failed_files == []；JUnit の failures == 0 かつ tests > 0；監査フラグが修正済み、または正当な理由が示されていること； budget_check が ok であること（p95 が目標値未満、ヒッチ比率が最大 1%）；エクスポートの終了コードが 0 で、アーティファクトのサイズが 記録され、verify_pack に期待するファイルが一覧表示されること。
• 視覚： すべてのキャプチャが image_checks に合格すること（all_black、all_white、uniform、 transparent の場合は ok が false）。また、コンタクトシートで開いて確認すること。同じビューで撮影した変更前と変更後を用意すること。

よくある間違い

間違い	どのような問題か	修正方法
終了コードを信用する	解析エラーでも終了コードは 0	run_script/check_allでログを確認します
オートロードを使うコードで--check-onlyを使う	「識別子が見つかりません：GameState」	check_all（プロセス内で読み込みます）；check_onlyではautoload_false_positivesにファイルを記録します
project.godotを手書きする	GodotPhysics3D、ストレッチが無効、UIが拡大縮小されない	new_projectを使うか、キーを設定します
新規プロジェクトでclass_nameを使う	「識別子が見つかりません」	最初にimport_projectを実行します
オートロードにclass_nameと同じ名前を付ける	「クラス"GameState"がオートロードシングルトンを隠しています。」（GDScriptアナライザー）	オートロードには別の名前を付ける（Gameなど）か、class_nameを削除します
ヘッドレスでキャプチャまたは--write-movieを使う	描画フレーム数が0；--write-movieはクラッシュします	ウィンドウ表示でcapture_sceneを使います
MetalでGPUの時間を計測する	gpu_msが0	profile_scene(driver="vulkan")を使います
プロジェクト内にエクスポート出力を置く	次回、ビルドがインポートされてパックされます	プロジェクトの外に置くか、.gdignoreを使います（自動）
macOSへエクスポートする	「ETC2 ASTC」または「無効なバンドル識別子」	import_etc2_astc=trueを設定します；ensure_presetがバンドルIDを設定します
クローン間でuser://を共有する	他のエージェントのクローンのセーブデータ、入力マップ、シェーダーキャッシュが表示されます（すべてのクローンの名前がBase3Dでした）	base_projectはデフォルトで分離します；その他の一時プロジェクトにはgd_env.isolate_user_dir(P)を使います
フレームごとにTIME_PROCESSを使う	すべてのCSV行で同じ値になります（モニターの更新は約1秒に1回；--fixed-fpsでは0）	profile_sceneのprocess_wall_ms列を使うか、センチネルノードを使います

チーム間のルーティングと引き継ぎ

スキル	ブリーフに次の内容が含まれる場合のルーティング先
scenario-godot-architecture	プロジェクト構成、シーンとノードの違い、シグナル、リソース、オートロード、コンポジション、型付け、セーブデータ
scenario-godot-2d	スプライト、TileMapLayer、TileSet、プラットフォーマーまたはトップダウンの操作感、Camera2D、ピクセルパーフェクト、2D ライト、パララックス
scenario-godot-3d-world	CharacterBody3D、ブロックアウト、CSG、GridMap、地形、GLB インポート、Jolt、プロシージャルメッシュ
scenario-godot-rendering-lighting	レンダラーの選択、SDFGI、VoxelGI、LightmapGI、環境、フォグ、シャドウ、ポストプロセス、Compositor
scenario-godot-shaders	.gdshader、VisualShader の代替手段、グローバルユニフォーム、画面の読み取り、コンピュート、ステンシル
scenario-godot-vfx	GPUParticles、トレイル、サブエミッター、パーティクルの衝突、インパクト、演出効果
scenario-godot-animation	AnimationPlayer、AnimationTree、トゥイーン、スケルトン、IK、リターゲティング、ルートモーション、カットシーン
scenario-godot-ui	Control のレイアウト、コンテナ、テーマ、メニュー、HUD、フォーカスとゲームパッド、ローカライズ、スマートフォンでのスケーリング
scenario-godot-gameplay	ステートマシン、インベントリ、会話、セーブとロード、ナビゲーション、AI、プロシージャル生成、入力
scenario-godot-audio	バス、エフェクト、空間オーディオ、アダプティブミュージック、SFX のバリエーション
scenario-godot-multiplayer	ハイレベルマルチプレイヤー、RPC、権限、スポーナーとシンクロナイザー、ロビー、専用サーバー
scenario-godot-pipeline-automation	CLI と CI、エディタープラグイン、GUT と gdUnit4、インポートプラグイン、GDExtension、MCP ワークフロー
scenario-godot-performance-export	プロファイラー、モニター、スタッター、モバイル、Web、デスクトップおよび Steam へのエクスポート、署名

複数の分野にまたがる項目には、担当チームを 1 つ割り当てます。シェーダーのスタッターと Web のスレッド処理は scenario-godot-performance-export にルーティングし、ブリーフには 2 つ目のスキルを記載します。すべての引き継ぎパケットには、プロジェクトのパスとチャンネル、番号付きのブリーフ、ツールキットの呼び出しで実施した内容、証拠（結果の JSON パス、コンタクトシートとフラグ、budget_check を含む CSV、JUnit の合計値、エクスポートサイズ）、確認済み事項、仮定、未解決の問題、および境界（受け手が変更できる範囲）を記載します。受け手は作業を進める前に、証拠のうち 1 つを再現します。関連チーム：blender-expert（GLB エクスポート前のアセット修正）、unreal-expert、unity-expert、maya-expert、zbrush-expert。

Scenario のアセットから Godot へ

アセット	生成元	配置先
スプライト、プロップ、アイコン、タイルセット、UI パーツ	scenario-game-assets	scenario-godot-2d、scenario-godot-ui
アニメーションフレーム、スプライトシート、VFX ループ	scenario-sprite-animation、scenario-sprite-pipeline	scenario-godot-2d（SpriteFrames）、scenario-godot-vfx（フリップブック）
パララックス平面	scenario-parallax-stage	scenario-godot-2d（Parallax2D）
GLB メッシュ	scenario-3d	scenario-godot-3d-world（インポート）、scenario-godot-animation（リグ）
PBR テクスチャ、タイリング可能なマテリアル	scenario-textures	scenario-godot-rendering-lighting、scenario-godot-shaders
スカイボックス、360 パノラマ	scenario-skyboxes	scenario-godot-rendering-lighting（スカイ）
音楽、SFX、環境音、ボイス	scenario-audio、scenario-elevenlabs	scenario-godot-audio

インポート前にアセットを確認し（scenario-quality-gate）、インポート後にもゲームカメラからのキャプチャを受け入れ先のスキルで評価して確認します。このスキルでは、GLB のスケール、ピボット、三角形数も監査します。

Godot 4.7 の落とし穴とプラットフォームに関する注意点

最初の作業の前に references/traps.md を読んでください。--check-only を通過してしまう Godot 3 の名前、ハングする --script、無視される不明なフラグ、標準入力待ちになる -d、ヘッドレスではできないこと（MultiMesh の書き込み、GPUParticles）、ProjectSettings.save() による project.godot の書き換え、インポート時のクラッシュ、非推奨 API について説明しています。さらに、macOS のバイナリ、テンプレート、user:// のパス、ウィンドウのフォーカス、Metal のプロファイリング、Windows のパスと PYTHONUTF8=1 のルールについても説明しています。

参考資料

• references/expert-notes.md：出典ごとの専門家の見解（タイムスタンプ付き）と、ツールキットの構築中に確認された落とし穴です。
• references/procedures.md：ツールキット API の全容、ジョブ作成のルール、および各手順の実地テストと結果です。
• references/critique.md：エージェントの Godot 出力と引き継ぎを評価するための基準です。
• references/gui-paths.md：同じ作業を行うためのエディターのメニューと設定です。
• references/sources.md：すべての出典と認証情報、URL、最適なタイムスタンプです。