godot-3d-world-building

3D ワールド構築

GridMap、CSG のベイク、オクルージョンを使ったレベルデザインの専門的なガイダンスです。ライティングや雰囲気の演出は対象外です。

絶対にしないこと

• GridMap のナビゲーションを絶対にベイクし忘れないでください — GridMap はナビゲーションメッシュを自動生成しません。EditorPlugin または手動で NavigationRegion3D を使用してください。
• 最終的なゲームジオメトリに CSG を絶対に使用しないでください — CSG はプロトタイピング用です。パフォーマンス向上のために、静的メッシュに変換してください（エディターで「Bake CSG Mesh」を使用）。
• タイルを配置した後に GridMap のセルサイズを絶対に変更しないでください — cell_size を変更しても既存のタイルは更新されず、位置ずれが発生します。最初に一度だけ設定してください。
• 衝突を確認せずに MeshLibrary アイテムを絶対に出荷しないでください — 変換前に mesh_library.get_item_shapes(tile_index) を呼び出すか、ソースシーンの StaticBody3D と CollisionShape3D を確認してください。シェイプが空の場合、見た目だけのジオメトリが生成され、プレイヤーはすり抜けて落下します。
• コンバイナーのフレームが落ち着く前に CSG を絶対にベイクしないでください — メッシュの抽出は await get_tree().process_frame の後にのみ行ってください（safe_csg_baking.gd を参照）。再計算中にベイクすると、空または古い ArrayMesh データが生成されます。手順：ブーリアン編集を完了 → 1 フレーム待機 → ベイク → CSG を削除 → 衝突を追加。
• ゲームプレイ中に CSG ノードを絶対にアニメーションさせないでください — 別の CSG ノード内で CSG ノードを動かすと、CPU によるブーリアンジオメトリの再計算が発生し、パフォーマンスが大幅に低下します。
• GridMap に汎用ロジックノードを絶対に配置しないでください — GridMap はメッシュ、ナビゲーション、衝突に限り高度に最適化されています。スポーンやトリガーには、プロキシタイルとスクリプトを使用してください。
• CSG で非多様体メッシュを絶対に使用しないでください — カスタム CSGMesh3D アセットは多様体（閉じていて、自己交差がない）でなければなりません。非多様体メッシュは CSG アルゴリズムを破損させます。

---

利用可能なスクリプト

必須：対応するパターンを実装する前に、該当するスクリプトを読んでください。 ここではライティング、空、フォグのスクリプトや Environment の詳しいチュートリアルを読み込まないでください — godot-3d-lighting に案内してください。

collision_gen.gd

メッシュから衝突シェイプを自動生成します。衝突のないモデルをインポートする場合や、プロシージャルジオメトリに使用してください。

gridmap_runtime_builder.gd

ストリーミング／ランタイム GridMap に関する唯一のエントリーポイント — タイル配置の一括処理、チャンク形式の再構築、自動ナビゲーションベイクに対応します。場当たり的な WorldStreamer のスタブよりこちらを優先してください。

csg_bake_tool.gd

CSG ジオメトリを、適切なマテリアルと衝突を備えた静的メッシュにベイクする EditorScript です。レベルのプロトタイプを仕上げる際に使用してください。

safe_csg_baking.gd

CSG を安全にベイクするための専門的な手法です。ベイクしたメッシュを抽出する前にフレームの終了を待ち、データが空になるのを防ぎます。

lod_manager.gd

カメラからの距離に応じて詳細レベルを切り替えます。広大な屋外シーンでメッシュの切り替えと表示状態を管理します。

occlusion_setup.gd

手動のオクルージョンカリング用に OccluderInstance3D を設定します。部屋が多い屋内レベルで使用してください。

grid_map_logic_manager.gd

プロキシタイルのパターン：見えない MeshLibrary マーカーを _ready 時にスポーン／トリガー用シーンへ置き換え、その後プロキシセルをクリアします。

world_streamer.gd

ResourceLoader.load_threaded_request のキュー — バックグラウンド読み込みの完了後にチャンクをインスタンス化し、カクつきを防ぎます。

ゴールデンパス（GridMap／CSG／オクルージョン）

1. MeshLibrary — ソースシーン：MeshInstance3D + StaticBody3D/CollisionShape3D → Convert To MeshLibrary → get_item_shapes() を検証します。
2. GridMap — cell_size を一度だけ設定し、セルを配置して、NavigationRegion3D をベイクします。ランタイムで再構築する場合は、必須の gridmap_runtime_builder.gd を使用します。
3. CSG グレイボックス — CSGCombiner3D でプロトタイプを作成 → 必須の safe_csg_baking.gd / csg_bake_tool.gd を使用 → ライブ CSG を削除します。
4. オクルージョン／LOD — 屋内の部屋には occlusion_setup.gd を使用します。距離に応じた切り替えには lod_manager.gd を使用します。
5. Sky／fog／WorldEnvironment — 対象外です。関連分野の godot-3d-lighting を使用してください（別の場所でボリューメトリックフォグが有効になっている場合は、DirectionalLight3D のみを配置した状態にしてください）。

---

GridMap の基本

セットアップ（簡潔版）

extends GridMap

func _ready() -> void:
    mesh_library = load("res://tilesets/dungeon_library.tres")
    cell_size = Vector3(2, 2, 2)  # Set once; never after tiles exist

セル API：set_cell_item(pos, index[, orientation])、get_cell_item、INVALID_CELL_ITEM、local_to_map / map_to_local。バッチ／ランタイムでの配置とナビゲーションのベイクには、gridmap_runtime_builder.gd を読み込んでください。独自のチャンクストリーマーを貼り付けないでください。

コリジョンの検証

var shapes := mesh_library.get_item_shapes(tile_index)
if shapes.is_empty():
    push_error("Tile %d has no collision — fix MeshLibrary source scene" % tile_index)

---

CSG のベイク順序

1. CSGCombiner3D 内でブーリアン編集を完了します。
2. await get_tree().process_frame（理由：CSG のダーティフラグは 1 フレーム遅れて反映されます）。
3. 上記のスクリプトで MeshInstance3D とコリジョンにベイクし、エクスポートするシーンから CSG を削除します。
4. ランタイムで CSG をアニメーションさせないでください。

ブラシタイプ（Box／Cylinder／Sphere／Polygon）は、エディターでのグレイボックス作成専用です。出荷用ジオメトリには使用しないでください。

---

ストリーミングの判断

必要なもの	対応
ランタイムの GridMap タイル／チャンクの再構築とナビゲーションのベイク	必須の gridmap_runtime_builder.gd を使用します
広大なオープンワールドシーンのストリーミング	関連分野の godot-genre-open-world を参照します
場当たり的な WorldStreamer のインラインスタブ	削除してください。不完全なファイル読み込み TODO を再導入しないでください

---

エキスパート向けテクニック

MultiMesh の空間分割

密集した小物を複数の地域別 MultiMeshInstance3D ノードに分割すると、フラスタムカリング／オクルージョンカリングでクラスター全体をカリングできます（単一の MultiMesh AABB ではすべてが描画されます）。

GridMap のロジックプロキシ

スポーン／トリガーには非表示のプロキシタイル ID を使用します。_ready で get_used_cells_by_item を呼び出し、ロジックシーンをインスタンス化して、プロキシセルをクリアします。ロジックを GridMap 自体に持たせないでください。

インテリアマッピング

都市規模のフェイクインテリアには、ウィンドウ平面に空間シェーダーを使用します。関連分野の godot-shaders-basics を参照してください。シェーダーの完全なレシピをここに貼り付けないでください。

エッジケース

• コリジョンがない：get_item_shapes が空の場合は、MeshLibrary のソースを修正します。
• CSG の Z ファイティング：ベイク前に、減算ブラシにごく小さなオフセットを加えます。

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

トピック	リファレンス／スクリプト
GridMap／CSG のベイク手順	gridmap-and-csg.md
チャンクストリーミング／プロシージャル生成ルーム	streaming-and-procgen.md
プロキシスポーンタイル	grid_map_logic_manager.gd
スレッド化されたチャンク読み込み	world_streamer.gd

リファレンス

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

公式ドキュメント

• GridMap の使用 — MeshLibrary のワークフロー、セルの配置、GridMap が適したモジュール式レベルツールとなる場面について説明します。
• MeshLibrary — GridMap が実行時にインスタンス化するアイテムのメッシュ、名前、コリジョン形状について説明します。
• CSG ツール — CSGCombiner3D／プリミティブを使ったブーリアン演算によるプロトタイピングと、メッシュへのベイクの引き継ぎについて説明します。
• 環境とポストプロセス — WorldEnvironment、Sky、ProceduralSkyMaterial／PanoramaSkyMaterial、フォグモードについて説明します。
• ボリュメトリックフォグとフォグボリューム — 散乱の設定、密度／アルベド、ボリュメトリックフォグを表示するにはライトが必要な理由について説明します。
• オクルージョンカリング — OccluderInstance3D の配置と、屋内の部屋における CPU コストのトレードオフについて説明します。
• メッシュの詳細度（LOD） — インポーターによる自動 LOD と、大規模な屋外レベルにおける手動のメッシュ切り替えについて説明します。
• 可視性範囲 — LOD マネージャーで使用する GeometryInstance3D の距離フェード／ヒステリシスについて説明します。
• コリジョン形状（3D） — MeshLibrary のアイテムやベイク済み CSG に使用する、凸形状／三角形メッシュ／プリミティブの選択について説明します。
• ナビゲーションの概要（3D） — NavigationRegion3D のベイクについて説明します。GridMap は自動生成されません。
• バックグラウンドでの読み込み — ResourceLoader によるスレッド処理を使ったチャンクのストリーミングで、一時的な処理落ちを防ぐ方法について説明します。
• MultiMesh の使用 — 大量のプロップのインスタンス化と、空間的に MultiMesh を分割してカリングを復元する理由について説明します。

関連スキル

前提条件

• godot-project-foundations — MeshLibrary への変換や WorldEnvironment の設定を行う前に、シーンツリー、リソース、インポートの基本を学びます。
• godot-physics-3d — MeshLibrary のソースシーンに設定する必要がある StaticBody3D／CollisionShape3D のパターンについて説明します。設定しないと、プレイヤーがタイルをすり抜けて落下します。
• godot-gdscript-mastery — ベイクや実行時ビルダーで使用する、型付きの GridMap／CSG スクリプティング、シグナル、await／process_frame のパターンについて説明します。

補完

• godot-3d-lighting — ボリューメトリックフォグが散乱させるDirectionalLight3DとGIです。環境設定と実際のライト設定を組み合わせます。
• godot-3d-materials — グレーボックス化の後、タイルとベイク済みのCSGメッシュにStandardMaterial3D/ORMを適用します。
• godot-navigation-pathfinding — セル編集後、GridMapジオメトリからNavigationMeshをベイクして更新します。
• godot-shaders-basics — 都市規模で建物の内部を疑似的に表現するためのインテリアマッピングなど、空間表現のテクニックです。
• godot-camera-systems — カメラの距離に応じて可視範囲、LODの切り替え、チャンクの読み込み半径を制御します。
• godot-scene-management — カクつきのないワールドのストリーミングを実現する、シーンのパッキングとスレッド化された読み込みキューです。
• godot-performance-optimization — 大規模レベル向けのドローコール予算、オクルージョン戦略、MultiMeshの分割です。

下流／利用者

• godot-procedural-generation — 配置バックエンドとしてGridMapにセルを書き込む、ダンジョン／地形ジェネレーターです。
• godot-genre-open-world — これらのワールド構築プリミティブを基盤とする、チャンクストリーミング、フローティングオリジン、HLODです。
• godot-genre-sandbox — GridMap/CSGのベイク処理を再利用する、プレイヤー主導の建築と編集可能なボクセル／グリッドワールドです。

マスター

• godot-master — スキル横断の探索に使う、ライブラリルーター兼ミラー化されたモジュールエントリです。