scenario-godot-3d-world

Godot 3D ワールド（レベルおよび環境アーティスト）

対象：Godot 4.7.2.stable、macOS Apple Silicon、Jolt Physics、Forward+。

必須の背景知識： scenario-godot-expert（チャンネル、gd_run、レビューループ、4.7 の注意点）。ここに記載されている兄弟スキルが利用可能なスキルにない場合は、ユーザーにインストールを依頼してください（npx skills add scenario-labs/skills --skill <name>）。無人で進める場合は、ツールのスキーマに基づいて作業を続け、不足している点を明記してください。

ステータス（2026-10-02）： tests/code/godot-3d-world/test_world_live.py のライブテストグループ全14件が合格しました（live_20261002-215949.json）。L8 と L12 はラウンド2で拡張され、再度合格しました（live_20261002-223935.json）。オフラインチェック11件も合格しています。詳細はreferences/procedures.mdを参照してください。

ツールキット：scripts/gd_world.py（ランナー側）とscripts/agentkit/world/*.gd（ジョブ、インポート後スクリプト1つ、ランタイムスクリプト2つ）。gd_world.install_world(P) でインストールします。

姿勢（専門家による補足）

1. カメラ相対方向を正規化する前に、Y をゼロにします。 GDQuest（JlgZtOFMdfc 00:22:00）： そうしないと、下を向くと歩行速度が落ちます。順序を正しくすれば、ピッチが -60 度でもコントローラーは 6.00 m/s を維持しました。
2. CharacterBody3D には階段モジュールが必要で、段差の高さは踏み面から取得します。 Majikayo （Tb-R3l0SQdc 00:17:01）は、body_test_motion で上方向にスナップし、レイで踏み面を確認します。カプセルが段差の先端に触れるためです。標準の半径 0.35 のカプセルは、高さ 0.18 m の段差で止まります。カプセルの移動量から高さを取得すると、上限 0.45 m の設定に対して 0.6 m の段差を登れてしまいましたが、踏み面のレイで修正できました。
3. スナップダウンには、下方に床があるか確認するレイを設けます。 Majikayo（00:14:58）：これがないと、どの段差から歩いて降りてもスナップダウンします。このガードでは急な階段は解決できません。スムーズに降りるには、蹴上げを約 0.25 m 以下に保ちます。
4. CSG でグレーボックスを作成してからベイクし、アニメーションさせないでください。 Four Games（gIK02BgCCBI）と PiCode （S5kRpEKIh38 00:01:51）：静的な CSG のコストはモデリング済みのジオメトリとほぼ同じですが、動く CSG は遅く、コストはオペランドに応じて変わります（128 セグメントの球体を使った切り抜きは、移動 1 回あたりボックスの切り抜きの 1,000 倍のコストがかかりました）。 CSG には閉じたメッシュが必要です。開いた CSGMesh3D オペランドはエラーなしで無視されます。
5. プロップにはシンプルなコリジョンを優先します。 Four Games（00:05:37）は、手作業で作成した -colonly 形状を推奨しています。トライメッシュ（-col）は静的なレベルジオメトリのみに使用し、プロップや動的なオブジェクトにはボックスまたは凸形状を使用します。参照ジオメトリには -noimp を使用します。
6. インポート後のスクリプトはツリーの外でも動作します。 Allard（5fDuf2IlizU 00:11:14）：オーナーを設定し、ローカルトランスフォームを使い、reparent(node, false) を使用します。コリジョンレイヤーも忘れないようにスクリプト内で設定します（00:15:15）。再現を確認済みです。オーナーが設定されていないノードは保存されず、global_transform は単位変換を返し、デフォルトの reparent() は位置をゼロにします。
7. プレイヤーを除外した球体付きスプリングアームを使います。 Octodemy（ZCb12AHKMfE 00:07:40、00:08:35）： SphereShape3D の半径を 0.3 にし、top_level ピボットを設定して、add_excluded_object(player) を使います。アームは壁の手前で、半径 1 つ分の距離を残して止まります。
8. AI 生成の GLB は、マニフェストで別途指定されない限り、正規化前のプレースホルダーとして扱います。 シナリオ提供の Tripo、Meshy、Hitem3D のファイルは、単位立方体に収まり、ピボットが中央にあり、両面表示、メタリック値 1.0、4K マップ、15k～1M トライアングルの状態で届きました。Jan（L5emNlNYVfY 00:02:00、ベンダー）は、まず 6k～8k トライアングルにリメッシュします。サイズ、ピボット、向き、コリジョン、予算は、インポートスクリプトが適用するマニフェストで指定します。
9. Terrain3D：リージョンの配置を確認し、テクスチャを準備して、バイナリ形式で保存します。 Tokisan（oV8c9alXVwU 00:20:22）：リージョンの配置が悪いと、メモリ使用量が増大します。1.0.2 では、原点を中心とする 1,024 m の地形に、256 のリージョンを 16 個、または 512 のリージョンを 4 個使うと、割り当て面積は 1.05 km² ですが、1,024 のリージョンを 4 個使うと 4.19 km² になります。 テクスチャはシームレスで正方形、サイズは 2 のべき乗で統一し、チャンネルをパックします（アルベド＋高さ、法線＋ラフネス）。すべて同じ圧縮方式を使います（00:04:33；Four Games ejlD8cM9kk4 00:10:06）。.tres は読み込みが遅いため、.res として保存します（YtiAI2F6Xkk 00:01:30）。
10. 実行可能なコードを引き継ぎ、測定値には注記を付けます。 このキットを持たない人向けの計画では、gd_world.* の呼び出しだけでなく、ヘルパーが実行する GDScript も提示します（procedures.md に記載）。ここで測定した数値は M シリーズ Mac での効果量です。その旨を明記し、対象環境でも再測定してください。

意見の相違：カプセル（GDQuest）か円柱（Juli、U5A_JArREUc）。段差への許容度を重視するならカプセル、壁走りやスライド時の法線をきれいに保つなら円柱です。CharacterBody3D（GDQuest、Juli）か RigidBody3D（Bramwell、sVsn9NqpVhg）。プレイヤーを物理シミュレーションの対象にする必要がある場合に限り、RigidBody を使います。

まず決めること

入力項目	計画に影響する理由	デフォルト
カメラ	スプリングアームまたは頭部のピボット	三人称視点、スプリングアーム 4.5 m
キャラクターサイズ	カプセルがドア、段差、廊下のサイズを決める	r 0.35、h 1.8、step 0.45
レベルタイプ	GridMap キット、Terrain3D、標準のハイトマップ	まずブロックアウト、その後キット
ワールドサイズ	精度とストリーミング	単精度（float32 は 1 km で 0.12 mm、8 km で 1 mm の刻み幅）。一定のサイズで開始するのではなく、プロファイリングで最悪のビューまたは読み込み時間が予算を超えたらストリーミングする
アセットソース	Blender のサフィックス、または AI GLB マニフェスト	AI GLB ＋ マニフェスト
ターゲット	レンダラー、予算、圧縮	デスクトップ Forward+。Web とモバイルは Compatibility（Juli 00:24:02）
物理エンジン	4.6 以降のデフォルトは Jolt（新規プロジェクトのみ）	Jolt、ゲートで確認

ワークフロー

1. プロジェクトのゲート（P1）。 gd_world.physics_gate(P) でエンジンを検証します。Jolt では、凹形状へのレイが face_index -1 を返します（Godot Physics では 8）。手書きの project.godot では Godot Physics が選択されます。set_layer_names でレイヤーに名前を付けます。GATE：engine_running が "Jolt Physics" で、フラグがないこと。
2. プレイヤー（P2）。 build_player の後に controller_suite（ヘッドレス、--fixed-fps 60）を実行します。GATE：移動速度が move_speed と一致すること、下を向いても同じ速度であること、ジャンプの頂点が v²/2g から 0.1 m 以内であること、max_step_height までの階段を上れることと、それを超える高さでは上れないこと、段差でスナップしないこと、40 度の斜面は上れて 50 度は上れないこと、壁際ではアームが短くなること。
3. ブロックアウト（P3）。 オフラインで validate_layout(layout) を実行し、次に build_village、door_test、ベイクを行います。GATE：すべてのドアを実際のカプセルが通れること（幅 0.70 m は通れず、0.72 m は通れる（r 0.35 の場合）。オフラインのルールでは 1.00 m を要求します［余裕を追加］）、ベイクした三角形の数が CSG の三角形の数と一致すること、キャプチャが意図どおりに見えること。
4. キット（P4）。 build_kit、build_grid、stairs_walk を実行します。マテリアルはメッシュのサーフェスに割り当て、各アイテムには StaticBody3D と NavigationRegion3D をそれぞれ 1 つずつ配置します（ドキュメントを参照）。ライブラリをビルドする前にライトマップのテクセルサイズを設定し（GridMap の自動 UV2 はドキュメントに従って 0.1 です。再計測はしていません。.import のデフォルトは 0.2 です）、ナビメッシュのセルサイズをマップの 0.25 と一致させます（ドキュメントを参照）。GATE：使用するすべてのセルでレイがヒットすること、プレイヤーが各階段アイテムを上れること（3 m の階高には 8 段必要で、6 段では上れません）。
5. 地形（P5、P6）。 小規模なワールドでは build_island（チャンク化した ArrayMesh と HeightMapShape3D 1 つ）を使い、続いて collision_check を実行します。スカルプトまたはペイントしたワールドでは gd_world.terrain3d を使い、change_region_size()（region_size の設定は無視されます）とリージョンに合わせた配置を行います。ペイントは人手で行うステップです。大きく均一な領域にベースペイントを施してからスプレーし、オートシェーダーの領域には絶対にスプレーしないでください（YtiAI2F6Xkk 00:05:45 から 00:07:25）。GATE：400 本のレイで衝突位置が 0.1 m 以内であること、リージョン数とサイズが記録されていること、.res データがあること、キャプチャを開いて確認できること。
6. スキャッター（P7）。 gd_world.scatter を使い、必ずウィンドウモードで実行します。GATE：すべてのインスタンスが地面に接していること、.tscn 内にタイルごとの buffer があること、棄却数がカウントされていること、終了時のキャプチャが確認されていること。
7. GLB からのプロップ（P8）。 オフラインで glb_stats と glb_flags を実行し、続いて ingest_glbs(P, drop, manifest) を実行します（LOD、シャドウメッシュ、ライトベイクを設定した事前作成済みの .import、post_import_prop.gd、テクスチャは VRAM 向けに 2048 に調整）。その後、audit_props と lod_probe を実行します。アセットの正面は +Z（Vector3.MODEL_FRONT）です。look_at(t, up, true) は +Z をターゲットに向けます。Blender のエクスポートでは三角形化し、トランスフォームを適用して、リグをレストポーズにします（ドキュメントを参照）。GATE：マニフェストの高さ、y 0 のベース、背面カリング、予算フラグが把握されていること、1.8 m の参照オブジェクトの隣に並べたキャプチャがあること、向きが確認されていること。
8. ストリーミング（P9）。 runtime/cell_streamer.gd を使い、unload_radius を load_radius より大きくします。world_stream.gd:walk を使い、ウィンドウモードでテストします。GATE：境界で 0 件のリクエストペース調整が発生すること、すべてのセルがアンロードされ、終了時にノード数がベースラインに戻ること、最悪フレームが予算内であること。
9. 監査とプロファイル（P10）。 audit_level(scenes) を実行し、続いて gd_run.profile_scene(..., driver="vulkan") を実行します。GATE：残存する CSG、ヘッドレス MultiMesh、名前のないレイヤーがないこと、GPU ms とドローコールが記録されていること。ウィンドウモードではフレーム時間がディスプレイのリフレッシュレートで上限に達するため、GPU と CPU の ms で評価します。

数値

値	測定値または出典	比較対象
コントローラーのデフォルト値	速度 6、加速度 40、空中 8、ジャンプ 5.5 m/s、落下上限 30	このキット［追加］、GDQuest の形状
階段モジュール	0.45 を登り、0.6 は登れません。上昇量 0.10／0.25／0.45 で、下降時に空中にいるフレーム数は 120 フレーム中 0／8／49	踏面 0.35、6 m/s
下方の床を検出するレイ	最大段差の 1.5 倍	Majikayo の 0.5 に対する 0.75
HeightMapShape3D の誤差	最大 0.058 m、平均 0.004 m	双線形補間、間隔 1 m および 2 m
散布	11.7 ms で 6,000 本のレイから 1,931 本の木を生成	傾斜 30 度、クリアランス 2 m
AI GLB テクスチャ	4K マップごとにロスレスの 19.6 MB から S3TC の 2.8 MB に圧縮	サイズ上限 2048、ミップマップ
1080p での LOD	ライトハウス：30 m で 986,642 tris、300 m で 61,616 tris	mesh_lod_threshold 1.0
ストリーミング	ヒステリシスなしでは 240 フレームで 69 回ロード、ありでは 0 回	境界のペーシング、64 m セル
水面の Z ファイティング、平面が 1 mm 下	Compatibility：近距離 0.05 でピクセルの 1.7%、近距離 0.25 で 0%；Forward+：どちらも 0%	Tokisan の近距離 0.25（YtiAI2F6Xkk 00:18:00）

品質ゲート

• エンジンの検証には設定を読むのではなく、プローブを使用します。レイヤーには名前が付いています。
• 歩行可能なすべての面にコリジョンがあります。すべての GridMap セル、家の床、地形サンプルでレイテストを実施します。
• コントローラースイートは、プロジェクトで実際に使用する段差とドアのサイズで合格します。
• 出荷するシーンに CSG はなく、スケールされたコリジョンシェイプもありません（HeightMapShape3D の間隔は除く）。両面表示の閉じたメッシュもありません。
• MultiMesh シーンはウィンドウ表示で実行した際に書き込まれ、監査でバッファーが見つかります。
• プロップはマニフェストのサイズで、基部は y 0 にあり、コリジョンはシンプルです。VRAM 内のテクスチャは 2048 以下で、LOD0 は予算内です（LOD によって LOD0 が低減されることはありません）。
• Terrain3D のデータは .res にあり、リージョン数を記録し、テクスチャはスタンス 9 のルールに従っています。
• キャプチャを開いて確認します：村、キット、島のクローズアップ、Terrain3D、プロップのラインアップ、階段。

よくある間違い

間違い	症状	修正
カプセルの移動量から段差の高さを求める	上限を超える高さの段差を登る	踏み面に向けてレイを飛ばす
床下へのレイがない	すべての段差で下にスナップする	まず段差の1.5倍の長さのレイを飛ばす
ヘッドレスでScatterを実行する	再読み込み後に木が消える。バッファーもない	ウィンドウモードで実行する
update_map_data_from_image(img, -1000, 1000)	10 mが19,000 mになる	ピクセルは0..1で読み取られるため、(0, 1)を使用する
高さにFastNoiseLite.get_imageを使う	階段状になる（8ビット）	floatループまたはRF画像を使う
カメラより先にTerrain3Dを配置する	「アクティブなカメラが見つかりません」	カメラを先に配置するか、set_camera()を使う
add_childの前にTerrain3D.collision_modeまたはregion_sizeを設定する	無視される	ツリー内でcollision.set_mode()、change_region_size()を使う
原点を中心とした地形より大きいリージョンサイズ	メモリが4倍になる	256または512にするか、リージョングリッドに合わせる
床と壁に1つのGridMapを使う	壁が床を置き換える	2つ目のGridMapを使う
_post_importでreparent()を使う	子が原点に移動する	reparent(n, false)を使う
接尾辞を削除した後に名前が衝突する	@StaticBody3D@19793	一意なベース名を使う
100万三角形のGLBでLODを信頼する	30 mで98万6千三角形	インポート前にポリゴン数を削減する
水面と地面が同一平面にある	Compatibilityでちらつく	0.25付近にするか、水面をずらす

引き継ぎ

• scenario-godot-expert：ツールキット、レビューループ、バージョンごとの注意点。
• scenario-godot-rendering-lighting：ライトマップ、オクルーダー、GI、フォグ（デプスフォグでストリーミングの 境界を隠せます［追加］）、シャドウ。
• scenario-godot-shaders：地形スプラットシェーダーまたはトライプラナーシェーダー、水。
• scenario-godot-animation：リグ付きキャラクターとインポートしたアニメーション。
• scenario-godot-gameplay：ナビゲーションのベイク、AI、インタラクション。
• scenario-godot-pipeline-automation：バッチインポート、CI、post_import_prop.gd以外のプラグイン。
• scenario-godot-performance-export：プラットフォームごとの予算、Webおよびモバイル向けのエクスポート、遠方セルを結合した プロキシ（HLOD）［追加］。
• blenderスキル：インポート時にBlenderのマーカーが置き換えられます（Allard 00:04:38）。リンクデータは依存ファイルを保存した場合にのみ更新されます（00:27:49）。AO用の「glTF Settings」ノードグループ（FinePointCGI PIpCl6TYnC0 00:03:23）。
• scenario-3d：GLBの生成。顧客向けテキストでは「Scenario MCP」と記載してください。

Godot 4.7 の注記

• 新しい 4.6 以降のプロジェクトでは Jolt がデフォルトです。手書きの project.godot では physics/3d/physics_engine="Jolt Physics" を設定する必要があります。
• Scene .import で確認されたキー：meshes/lightmap_texel_size は 0.2、gltf/naming_version=2、ノードごとの 物理設定は _subresources 内にあります。事前に記述した最小限の .import が適用されます。
• ヘッドレスでの --import では、抽出された glTF テクスチャはロスレスのままです。再調整パスで VRAM を設定します。
• SurfaceTool.set_smooth_group(-1) はフラットな法線を生成します。
• スクリプト API に LightmapGI.bake や OccluderInstance3D.bake はありません。
• Terrain3D 1.0.2 は 4.7.2 で読み込めます。最初の --import はクラッシュしました（シグナル 11）が、2 回目は正常に完了しました。

参考資料

• references/procedures.md：P1 から P10 までのコード、実際の結果、数値。
• references/expert-notes.md：各専門家の見解とタイムスタンプ、および 4.7.2 との相違点。
• references/critique.md：ベースラインと採点済みの回答の誤り、およびこのスキルの制限。
• references/gui-paths.md：ビューポートのみを使う作業のエディター内のパスと、それぞれに対応するコードでの代替方法。
• references/sources.md：動画、ドキュメント、アドオン、バージョン。