godot-genre-rts

絶対に避けるべきこと（上級者向けのアンチパターン）

ユニットのロジックと経路探索

• グループユニットの移動時に、経路探索の「ジッター」を絶対に発生させないでください。CPU サイクルを節約するため、必ず 経路クエリをずらして実行し、ユニットの移動中にのみ RVO 回避を有効にしてください。
• すべてのユニットについて、毎フレーム RVO 回避を絶対に更新しないでください。必ず 回避スレッド処理（プロジェクト設定）を使用し、静止ユニットは NavigationObstacle に置き換えてください。
• ユニットを無限の経路探索ループにはまらせないでください。目的地に到達できない場合に備えて、必ず タイムアウトと IDLE 状態を実装してください。
• 数百体のユニットそれぞれで _process() を絶対に使用しないでください。必ず中央の UnitManager を使うか、必要な場合にのみ _physics_process を使用してください。
• 霧の表現のユニット可視性を手動で計算しないでください。GPU 効率のため、必ず シェーダーベースのマスク（SubViewport + ColorRect）を使用してください。
• 大規模なグループのユニット AI や経路探索を同期的に処理しないでください。必ず WorkerThreadPool に処理を委譲し、経路の更新をずらして実行してください。
• NavMesh のソースジオメトリとして、高ポリゴンのビジュアルメッシュを絶対に使用しないでください。ベイクには必ず単純化した コリジョンシェイプを使用してください。

インタラクションとコマンド

• コマンドキュー（Shift-Click）を絶対に忘れないでください。必ず Array[Command] を保存し、「強制移動／攻撃」による割り込みを実装してください。
• 過剰なマイクロマネジメントを絶対に発生させないでください。自動攻撃範囲や、資源収集時の自動帰還など、低レベルのタスクは必ず自動化してください。
• グリッドやタイマーに、浮動小数点数の完全一致（==）を絶対に使用しないでください。決定論的なトリガーには必ず is_equal_approx() を使用してください。
• 選択データとして、視覚的な SceneTree に絶対に依存しないでください。決定論的なシリアライズとネットコードのため、RefCounted または Resource オブジェクトの 型付き選択セットを必ず維持してください。
• コマンドキューを絶対に忘れないでください。セーブデータとマルチプレイヤーの再生に対応するため、シリアライズ可能な Dictionary または JSON の状態を使った Command Pattern を必ず実装してください。
• グローバルで共有されている Resource の duplicate_deep() を絶対に忘れないでください。そうしないと、1 体のユニットのデータ（例：ステータス）を変更したときに、すべてのユニットに影響します。

パフォーマンスとシミュレーション

• 個別の MeshInstance3D ノードを使って、数千体のユニットを絶対に描画しないでください。INSTANCE_CUSTOM データを使用する MultiMeshInstance を必ず使い、GPU 側の状態アニメーション（歩行／攻撃／色）を個別に制御してください。
• 大量のユニットのトランスフォームをメインスレッドで絶対に計算しないでください。必ず WorkerThreadPool を使ってバッファーを RenderingServer.multimesh_set_buffer() に渡してください。
• すべてのユニットのナビゲーション経路を同じフレームで絶対に更新しないでください。必ずランダムなタイマーを使って 更新をずらしてください。
• 高頻度で使う AI 状態識別子に標準の String を絶対に使わないでください。ポインター速度で比較できるよう、必ず StringName（&"harvesting"）を使ってください。
• 浮動小数点精度の管理なしに、シミュレーション座標を 8192 ユニットを超えて絶対に増加させないでください。必ずワールド原点をシフトしてください。
• 建物配置ゴーストに CSGShape3D を絶対に使用しないでください。必ず最適化された静的な ArrayMesh ジオメトリを使用してください。

---

🛠 上級者向けコンポーネント（scripts/）

必須：実装するワークフローのスクリプトを読んでください。選択や霧の表現の手順をエージェント本体に再度インラインで記述しないでください。

選択／コマンド

• selection_manager_marquee_2d.gd — 2D のドラッグボックス、フィルター、Shift による追加には必須です。
• selection_manager_raycast_3d.gd — 3D の PhysicsServer によるピックには必須です。
• rts_selection_overlay.gd — 選択ビジュアル／ボックスオーバーレイです。
• rts_group_commander.gd — SceneTree のグループへの一括命令ブロードキャストです。
• rts_targeting_logic.gd — 距離の二乗による敵のフィルタリングです。

ユニット／ナビゲーション／軍隊

• rts_unit.gd — 必須のユニットコントローラー（ステート＋NavigationAgent）。
• crowd_navigation_unit.gd — RVO／群集エージェントの接続。
• rts_path_query_pool.gd — プールされたNavigationパスのクエリ。
• navigation_mask_helper.gd — ナビゲーションレイヤー／回避ビットマスク。
• rts_army_manager.gd — WorkerThreadPoolを使った軍隊AIのバッチ処理。
• rts_unit_stat_duplicator.gd — ユニットのResourceを分離するためのduplicate_deep()。

経済／建設／フォグ／ゴースト

• global_economy_manager.gd — 資源の収集・消費を管理するAutoloadパターン。
• building_grid_astar.gd — グリッド上の配置経路探索。
• fog_of_war_tile_mask.gd — 必須のTileMapLayerフォグ消去（2D／グリッド）。
• rendering_ghost_spawner.gd — RenderingServerのRIDを使った配置ゴースト。
• rts_formation_manager.gd — 重心に基づくグループ経路＋ユニットごとの編隊オフセット。
• rts_massive_unit_renderer.gd — ユニットのトランスフォームと同期するMultiMeshInstance3D軍隊レンダラー。

---

コアループ

1. 収集：ユニットが資源（金、木など）を集めます。
2. 建設：拠点の建物を建設し、技術やユニットをアンロックします。
3. 訓練：多様なユニットで軍隊を編成します。
4. 指揮：リアルタイムの戦闘でユニットを細かく指揮します。
5. 拡張：マップの支配権と資源を確保します。

スキルチェーン

フェーズ	スキル	目的
1. 操作	godot-input-handling, godot-camera-systems	選択ボックス、カメラのパン／ズーム／エッジスクロール
2. ユニット	godot-navigation-pathfinding, godot-state-machine-advanced	経路探索、RVO回避、待機／移動／攻撃
3. システム	godot-shaders-basics, godot-tilemap-mastery, godot-economy-system	フォグマスク／TileMapフォグ、収集・消費台帳
4. AI	godot-ai-navigation, godot-autoload-architecture	敵指揮官の経路設定＋軍隊／経済のAutoload
5. 仕上げ	godot-ui-containers, godot-particles	戦略UIの装飾、戦闘フィードバック
6. バランス調整	godot-monte-carlo-balancer	抽出したAIの指示と建設順序ポリシーの比較

判断ツリー：NavigationAgent＋RVOとMultiMesh＋サーバーシミュレーションの比較

アクティブなユニット数（桁数）	シミュレーション／経路探索	レンダリング	負荷
< ~80	ユニットごとのNavigationAgent2D/3D＋RVO；set_velocity → velocity_computed	MeshInstance／Spriteノードで問題ありません	必須のrts_unit.gd、crowd_navigation_unit.gd
~80–400	経路クエリを分散；移動中のみRVOを使用；静止物体 → NavigationObstacle；中央指揮官	引き続きノードで描画；経路クエリをプール	＋rts_path_query_pool.gd、rts_army_manager.gd、Batch 09のCOM編隊
> ~400／数千	サーバーシミュレーション：WorkerThreadPool上で論理トランスフォームを処理；NavigationServerのマップクエリは少数（COM／分隊）にし、兵士ごとにエージェントを作らない	MultiMeshInstance＋INSTANCE_CUSTOM；メインスレッド外でバッファーを送信	rts_army_manager.gd＋Batch 09のMultiMeshパス；ユニットごとの_processエージェントは読み込まないでください

ルール：ユニットごとの衝突回避と細かな指揮感が必要な間は、NavigationAgent＋RVOを使用します。ドローコール／ノードのコストが支配的になったら、MultiMesh＋サーバー側トランスフォームに切り替えます。数千のエージェントではなく、分隊単位で経路を設定します。

アーキテクチャ概要

1. 選択マネージャー

必須：selection_manager_marquee_2d.gd（2D）またはselection_manager_raycast_3d.gd（3D）。ネットコード／セーブに対応できるよう、SceneTreeだけに依存せず、型付きの選択セットを管理します。オーバーレイ：rts_selection_overlay.gd。

2. ユニットコントローラー（ステートマシン）

必須：アイドル／移動／攻撃／待機と NavigationAgent には rts_unit.gd を使用してください。複雑なステートグラフには godot-state-machine-advanced を使用してください。共有する stat Resource は必ず duplicate_deep() してください（rts_unit_stat_duplicator.gd）。

3. グループ移動とフォーメーション

クリックした地点にユニットが固まらないようにするには、重心を計算し、相対オフセットを適用して、ユニットごとに目的地を指定します。数百体のユニットでは、COM の経路に NavigationServer の経路を1つ使用し（Batch 09）、rts_group_commander.gd／rts_path_query_pool.gd と組み合わせてください。

4. 戦場の霧

タイル／グリッドの戦場の霧には、必須の fog_of_war_tile_mask.gd を使用してください。ソフトな視界には SubViewport マスクとシェーダーオーバーレイが有効です。ドキュメント（Using Viewports）と godot-shaders-basics を使って実装してください。タイルマスクスクリプトでグリッド方式に対応できる場合、このスキル本文に長い戦場の霧シェーダーを貼り付けないでください。

主要なメカニクスの実装

コマンドキュー

Shift キーを押しながらのクリックでコマンドを連続登録します。シリアライズ可能なコマンドの Array を保存し、完了時に取り出し、キューに登録した経路を線で描画します。選択スクリプトのコマンド発行フックと組み合わせてください。

リソース採集

ResourceNode → 作業タイマー → DropoffPoint → 銀行の更新、という流れです。global_economy_manager.gd／godot-economy-system を通じて銀行を接続してください。

よくある落とし穴

1. 経路探索の揺れ — RVO を有効にし、set_velocity を呼び出してから velocity_computed 時に移動させます。グループの経路クエリは時間差で実行してください。
2. 細かすぎる操作 — 自動で敵を攻撃／採集から帰還するようにし、強制移動／攻撃にはコマンドキューを使用します。
3. ノードの増えすぎ — 数百体を超えたら、ユニットごとの _process ではなく、判断ツリー（MultiMesh と軍隊マネージャー）に従ってください。

Godot 固有のヒント

• 回避：NavigationAgent* の RVO で実際に移動するには、set_velocity() と velocity_computed が必要です。
• サーバーアーキテクチャ：100体以上のユニットには、中央の UnitManager／rts_army_manager.gd を使用します。
• グループ：選択フィルターには Units、Buildings、Resources を使用します。

---

🚀 高度な技術実装（Batch 09）

1. 重心を使ったフォーメーション移動

大規模な選択では、COM から目的地までの NavigationServer の経路を1つ使い、その後、各ユニットにオフセットを適用します（判断ツリーを参照）。アルゴリズムはプロジェクトコードまたはフォーメーションヘルパーに記述し、経路オブジェクトをプールできるよう rts_path_query_pool.gd と組み合わせてください。

# Sketch only — prefer pooled queries from rts_path_query_pool.gd
static func move_group_to_target(units: Array, target: Vector3, map_rid: RID) -> void:
    if units.is_empty():
        return
    var com := Vector3.ZERO
    for u in units:
        com += u.global_position
    com /= units.size()
    var path: PackedVector3Array = NavigationServer3D.map_get_path(map_rid, com, target, true)
    if path.is_empty():
        return
    var dest: Vector3 = path[path.size() - 1]
    for u in units:
        u.set_movement_target(dest + (u.global_position - com))

2. MultiMesh の軍隊（判断ツリーで指定された場合）

instance_count を事前に割り当て、visible_instance_count を制御し、トランスフォームを設定します（必要に応じて WorkerThreadPool → RenderingServer.multimesh_set_buffer を使用）。兵士ごとに MeshInstance3D を作成しないでください。公式ドキュメントの「Using MultiMesh」を参照してください。

3. 戦場の霧 — まずスクリプトを使用

fog_of_war_tile_mask.gd を優先してください。SubViewport の視界マスクについては、ドキュメントと godot-shaders-basics を参照してください（長いシェーダー本体をここに重複して記載しないでください）。

判断ツリーやスクリプトカタログを超える詳しい説明が必須の場合：rts-mass-army-deep.md を参照してください。最初の配線時には読み込まないでください。まず同梱の scripts/ を使用してください。

参考資料

段階的な情報開示：特定の API を調査するときにのみ、公式ドキュメントへのリンクを開いてください。 関連する領域に作業を振り分けるときにのみ、関連スキルを読み込んでください。スキル全体を事前に読み込まないでください。

公式ドキュメント

• ナビゲーション（チュートリアル一覧） — 軍隊の移動をつなぎ込む前に、エージェント、サーバー、メッシュ、レイヤー、障害物を確認できる入口となるガイドです。
• NavigationAgent の使用 — set_velocity / velocity_computed の RVO ループで、群衆のジッターや IDLE 状態のタイムアウトによる停止を防ぎます。
• NavigationServer の使用 — ユニットごとのエージェントを大量に使わずに、重心を基準にした隊形移動のためのマップ経路を直接クエリできます。
• ナビゲーション経路クエリオブジェクトの使用 — ヒープの頻繁な確保・解放を避けながら、大量の移動命令を処理するための NavigationPathQueryParameters* のプールパターンを紹介します。
• ナビゲーションのパフォーマンス最適化 — 数百のユニットが各ティックで経路探索する場合の、クエリの時間差実行、回避処理の予算、障害物の切り替えについて説明します。
• MultiMesh の使用 — 兵士ごとに MeshInstance を用意する代わりに、数千のユニットを GPU インスタンスバッファーで描画します。
• 複数スレッドの使用 — メインスレッド外で軍隊の AI バッチを処理するための WorkerThreadPool の仕様について説明します。
• レイキャスト — 3D の選択や地面のクリックによるターゲット指定に、直接の空間状態クエリを使用します。
• Viewport の使用 — CPU による大量のタイル処理なしで、戦場の霧シェーダーに渡す SubViewport の視界マスクを作成します。
• マウス座標と入力座標 — マーキーボックス、逆投影による選択、Shift キーでキューに追加する命令のための、スクリーン座標からワールド座標への変換を説明します。
• AStarGrid2D — 建物の占有範囲や拠点の配置判定に使える、高速なグリッド経路探索です。
• リソース — 体力や防御力が共有テンプレートに反映されないよう、ユニットのステータスを duplicate(true) する必要がある理由を説明します。

関連スキル

前提条件

• godot-project-foundations — 選択や経路探索の決定性を保つため、物理ティック、ナビゲーション／回避のプロジェクト設定、入力マップのアクションを扱います。
• godot-input-handling — マーキー選択や命令のキュー追加に使う、マウスボタン、Shift 修飾キー、物理ステップでのサンプリングを扱います。
• godot-navigation-pathfinding — このジャンルの軍隊移動の基盤となる NavigationAgent の RVO、マップ、レイヤー、クエリオブジェクトのプールを扱います。

補完

• godot-camera-systems — RTS のパン／ズーム／エッジスクロールによるフレーミングで、戦略的な視点でも選択や命令を見やすく保ちます。
• godot-raycasting-queries — ユニット数が多い場合の 3D ピックに使える、PhysicsServer のレイ／シェイプ処理のレシピです。
• godot-state-machine-advanced — スパゲッティ状のフラグを使わず、ユニットごとに待機／移動／攻撃／保持の命令状態とキュー遷移を実装します。
• godot-shaders-basics — SubViewport のフォグテクスチャをサンプリングする CanvasItem／空間マスクシェーダーです。
• godot-autoload-architecture — 明確な起動順序を備えた Autoload として、全体の経済管理と軍隊管理を実装します。
• godot-economy-system — RTS の銀行 Autoload で再利用できる、資源の収集／支出台帳とコスト辞書です。
• godot-signal-architecture — 指揮官がすべてのユニットノードを直接反復しなくて済む、グループへのブロードキャストと命令バスです。

下流／利用側

• godot-monte-carlo-balancer — ビルドオーダーの方針、ユニットのコスト曲線、AI 対戦相手の強さを扱います。資源収集率を勘に頼って調整する代わりに、勝率をシミュレーションします。
• godot-performance-optimization — MultiMesh バッファー、回避処理、WorkerThreadPool が引き続きプロファイラーの負荷の大半を占める場合は、こちらに進んでください。
• godot-combat-system — 移動／攻撃命令でダメージ判定が必要になった際の、ヒット／被弾とターゲティングの仕様です。

マスター

• godot-master — ライブラリのルーター兼、ミラーされたモジュールのエントリです。複数領域にまたがる RTS の懸案事項を担当するドメインスキルを探す際に開いてください。