godot-genre-rts

绝对不要做（专家级反模式）

单位逻辑与寻路

• 绝对不要让编队单位移动时出现寻路“抖动”；务必错开寻路查询，并且仅在单位移动时启用 RVO 避让，以节省 CPU 周期。
• 绝对不要每帧都更新所有单位的 RVO 避让；务必使用避让线程（项目设置），并将静止单位替换为 NavigationObstacle。
• 绝对不要让单位陷入无限寻路循环；务必在目标点无法到达时实现超时机制和 IDLE 状态。
• 绝对不要对数百个独立单位使用 _process()；务必使用中央 UnitManager，或仅在必要时使用 _physics_process。
• 绝对不要手动计算战争迷雾中的单位可见性；务必使用基于 Shader 的遮罩（SubViewport + ColorRect）以提高 GPU 效率。
• 绝对不要对大规模编队同步处理单位 AI 或寻路；务必将任务交给 WorkerThreadPool，并错开寻路更新。
• 绝对不要使用高多边形视觉网格作为 NavMesh 源几何体；务必使用简化的碰撞形状进行烘焙。

交互与命令

• 绝对不要忘记命令队列（Shift-Click）；务必存储一个 Array[Command]，并实现“强制移动/攻击”绕过机制。
• 绝对不要制造过多的微操；务必自动处理低层级任务，例如自动仇恨范围和资源采集后的自动返回。
• 绝对不要使用精确浮点相等（==）比较网格坐标或计时器；务必使用 is_equal_approx() 来触发确定性事件。
• 绝对不要依赖可视 SceneTree 获取选择数据；务必维护一个由 RefCounted 或 Resource 对象组成的类型化选择集，以便确定性序列化和网络代码处理。
• 绝对不要忘记命令队列；务必使用命令模式，通过可序列化的 Dictionary 或 JSON 状态实现存档和多人游戏回放。
• 绝对不要忘记对全局共享的 Resources 使用 duplicate_deep()；否则，修改一个单位的数据（例如属性）会影响所有单位。

性能与模拟

• 绝对不要使用独立的 MeshInstance3D 节点渲染数千个单位；务必使用 MultiMeshInstance，并通过 INSTANCE_CUSTOM 数据驱动 GPU 端的独立状态动画（行走/攻击/颜色）。
• 绝对不要在主线程上计算大量单位的变换；务必使用 WorkerThreadPool 将缓冲区传递给 RenderingServer.multimesh_set_buffer()。
• 绝对不要在同一帧更新每个单位的导航路径；务必使用随机计时器来错开更新。
• 绝对不要在高频 AI 状态标识符中使用标准 String；务必使用 StringName（&"harvesting"），以便通过指针速度进行比较。
• 绝对不要在没有浮点精度管理的情况下，让模拟坐标超过 8192 个单位；务必使用世界原点偏移。
• 绝对不要将 CSGShape3D 用作建筑放置预览；务必使用经过优化的静态 ArrayMesh 几何体。

---

🛠 专家组件（scripts/）

MANDATORY：阅读与你正在实现的工作流对应的脚本 — 不要在 Agent 主体中重新内联选择/战争迷雾方案。

选择 / 命令

• 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 — MANDATORY 单位控制器（状态 + NavigationAgent）。
• crowd_navigation_unit.gd — RVO / 群体 Agent 接线。
• rts_path_query_pool.gd — 池化 Navigation 路径查询。
• navigation_mask_helper.gd — 导航层 / 避障位掩码。
• rts_army_manager.gd — WorkerThreadPool 军队 AI 批处理。
• rts_unit_stat_duplicator.gd — 通过 duplicate_deep() 隔离单位资源。

经济 / 建造 / 战争迷雾 / 幽灵

• global_economy_manager.gd — 收集 / 消耗资源的全局 Autoload 模式。
• building_grid_astar.gd — 网格放置寻路。
• fog_of_war_tile_mask.gd — MANDATORY 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 节点可行	MANDATORY 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 / 小队），而非每名士兵一个 Agent	MultiMeshInstance + INSTANCE_CUSTOM；在主线程外推送缓冲区	rts_army_manager.gd + Batch 09 中的 MultiMesh 路径；Do NOT Load 每单位 _process Agent

规则：当单位需要单独避障和微操手感时，保留 NavigationAgent+RVO。当绘制调用 / 节点开销成为主要瓶颈时，切换到 MultiMesh + 服务端变换——按小队而非数千个 Agent 寻路。

架构概览

1. 选择管理器

MANDATORY：selection_manager_marquee_2d.gd（2D）或 selection_manager_raycast_3d.gd（3D）。维护有类型的选择集（而非仅 SceneTree），以支持网络代码 / 存档。覆盖层：rts_selection_overlay.gd。

2. 单位控制器（状态机）

强制要求：rts_unit.gd 用于 Idle/Move/Attack/Hold 状态及 NavigationAgent。复杂状态图 → godot-state-machine-advanced。共享的状态 Resource 始终使用 duplicate_deep() (rts_unit_stat_duplicator.gd)。

3. 集团移动与编队

避免单位都挤向一次点击的目标：计算质心，应用相对偏移，为每个单位分配目的地。对于数百个单位，使用一条 NavigationServer 路径计算质心的路径（Batch 09），并配合 rts_group_commander.gd / rts_path_query_pool.gd。

4. 战争迷雾

强制要求：对于 tile/grid 战争迷雾，使用 fog_of_war_tile_mask.gd。SubViewport 蒙版 + 着色器叠加层适用于柔和视野——通过文档（Using Viewports）+ godot-shaders-basics 实现；当 tile-mask 脚本已覆盖网格方案时，不要将冗长的战争迷雾着色器粘贴到此技能正文中。

关键机制实现

命令队列

Shift-click 进行连锁操作：存储可序列化命令的 Array；完成后弹出命令；绘制排队路径线。与选择脚本的下达命令钩子配合使用。

资源采集

ResourceNode → 工作计时器 → DropoffPoint → 更新银行。通过 global_economy_manager.gd / godot-economy-system 连接银行。

常见陷阱

1. 寻路抖动 — 启用 RVO；调用 set_velocity 并在 velocity_computed 时移动；错开集团寻路查询。
2. 微操过多 — 自动仇恨 / 自动返程采集；使用命令队列执行强制移动/攻击。
3. 节点爆炸 — 单位超过几百个后，遵循决策树（MultiMesh + 军队管理器），而非为每个单位使用 _process。

Godot 专属提示

• 避让：NavigationAgent* 的 RVO 需要使用 set_velocity() + velocity_computed 执行实际移动。
• 服务端架构：100+ 个单位时，使用中央 UnitManager / rts_army_manager.gd。
• 分组：使用 Units、Buildings、Resources 作为选择筛选条件。

---

🚀 精英级技术实现（Batch 09）

1. 质心编队移动

对于大型选择，从质心到目标只使用一条 NavigationServer 路径，然后为每个单位添加偏移（参见决策树）。将算法保留在项目代码或编队辅助程序中；与 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 时才打开官方文档链接； 将工作分派到相关领域时再加载相关技能——不要预先加载整个技能网络。

官方文档

• 导航（教程索引） — 在接入军队移动前，了解 Agent、服务、网格、层和障碍物的入口索引。
• 使用 NavigationAgents — 通过 set_velocity / velocity_computed RVO 循环，避免人群抖动和 IDLE 超时卡住。
• 使用 NavigationServers — 直接查询地图路径，以质心编队移动，避免为每个单位都创建 Agent。
• 使用导航路径查询对象 — 使用池化的 NavigationPathQueryParameters* 模式下达群体移动指令，避免堆分配开销。
• 优化导航性能 — 数百个单位每个 tick 都计算路径时，可采用错峰查询、避让预算和障碍物切换。
• 使用 MultiMesh — 使用 GPU 实例缓冲区渲染数千个单位，而不是为每名士兵各建一个 MeshInstance。
• 使用多个线程 — 了解 WorkerThreadPool 的使用约定，以便在主线程之外批量处理军队 AI。
• 射线投射 — 通过直接空间状态查询实现 3D 选取和地面点击目标。
• 使用视口 — 使用 SubViewport 视野遮罩，为战争迷雾着色器提供数据，避免 CPU 批量处理图块。
• 鼠标和输入坐标 — 将屏幕坐标映射到世界坐标，以支持框选、反投影选取和按住 Shift 排队下达指令。
• AStarGrid2D — 快速网格寻路，用于建筑占地和基地放置检查。
• 资源 — 了解为何单位属性必须使用 duplicate(true)，避免生命值或护甲修改共享模板。

相关技能

前置要求

• godot-project-foundations — 在选择和寻路保持确定性之前，配置物理 tick、导航/避让项目设置和输入映射操作。
• 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／spatial 遮罩着色器。
• 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 问题时打开。