内容
# 大规模战斗编辑器MCP
[中文文档](zh.md)
我认为RTS游戏是理解AI社会的最佳方式之一。人类不应该被困在每一个低级别的行动中。人类应该定义策略、约束、权衡和目标；AI和工具应该将这些目标转化为可执行的战术工作。未来，稀缺的人力资源将不再是那些仅仅重复实现细节的人，而是那些能够设定方向、组织系统、评估结果和承担责任的人。
这也是为什么RTS对我很重要。一个有雄心的RTS游戏不应该从大规模战争的愿景开始，然后因为技术无法支撑设计而减少单位数量。规模不是装饰。规模会改变游戏玩法、战术空间、呈现层和构建游戏所需的工具。
[大规模战斗框架](https://github.com/MassBattle/MassBattleFrame)符合我的口味，因为它旨在极致性能。只有当基础足够快时，我们才能承担那些看起来浪费但能创造体验的东西：更密集的单位、更丰富的视觉效果、更大的战场和更多的战术反馈。如果你的RTS目标是数千或数万单位，[大规模战斗框架在Fab](https://www.fab.com/listings/191850b4-44d3-4455-aa76-874bc0196a10?lang=zh-cn)不是奢侈品。它是必要的基础设施。
当一个插件足够好时，爱好者自然会开始围绕它构建。大规模战斗编辑器MCP就是一个证明。它不是大规模战斗框架的运行时功能。它是一个编辑器工具，手部AI可以使用。它将单位、效果、材质、渲染器、Niagara和DataAsset的创作暴露为可调用的、可读的、可批处理的编辑器操作，因此AI可以在人类保持设计判断的同时处理战术资产转换。
如果你的游戏已经有数千单位，这个生态系统是有价值的。上面的故事可能很枯燥，但它是真实的：强大的核心技术吸引周围的社区工具。除了这个MCP插件外，还有其他围绕大规模战斗和RTS工作流的社区插件：
- [战争迷雾](https://github.com/winyunq/FogOfWar)：战争迷雾插件，包括小地图插件和场景雾插件。
- [RTS输入系统](https://github.com/winyunq/RTSInputSystem)：RTS控制系统，包括RTS相机、小地图可见相机视图，可以与战争迷雾小地图配合使用，以及单位选择面板。
- [地标](https://github.com/winyunq/LandmarkSystem)：场景编辑系统，包括特定坐标的编辑器文本、特定区域的建筑生成和特定位置的大规模战斗框架单位生成。
## 插件定位：大规模战斗工作流的编辑器工具
大规模战斗编辑器MCP将大规模战斗工作流中的战术资产和配置转换变成可调用的、可读的、可批处理的编辑器操作。它支持单位创建、配置转换、批量效果转换和动画、材质、网格和FX的呈现链转换。
开发人员不应该花费大部分时间手动适配一个单位或效果。这个插件让他们更快地验证规则是否与战略设计目标相符。
## 核心能力
默认节奏是先读取，然后创建或联合写入，显式删除仅在需要时进行，变更后再次读取。目标是重复性和可追溯性。
您可以使用它来区分单位呈现和平衡数据，或将非批处理的资产适配到可扩展的批处理系统中。
## 入口点
在线文档：`https://github.com/MassBattle/MassBattleEditorMCP`
本地文档入口：`Document/index.html`（`Document`工作树 / `Document`分支）
## AI技能
此仓库在`skills/`下包含Codex技能：
`skills/massbattle-unit-authoring`：指导AI完成MassBattle单位配置的MCP创建、读取、联合写入、删除和验证。
`skills/massbattle-effect-mcp`：指导AI完成Niagara / Effect MCP查询、读取、导出、复制和批量效果配置，同时协调单位MCP。
安装到本地Codex：
```powershell
Copy-Item -Recurse -Force .\skills\massbattle-unit-authoring $env:USERPROFILE\.codex\skills\
Copy-Item -Recurse -Force .\skills\massbattle-effect-mcp $env:USERPROFILE\.codex\skills\
```
如果设置了`CODEX_HOME`，请复制到 `$env:CODEX_HOME\skills\`。
MCP是编辑器工具接口。技能仅描述如何组合这些工具；它不应将工作流变成一个大按钮。
### Codex MCP服务器安装
大规模战斗编辑器MCP有两个面向Codex的层：
1. UE编辑器插件内部的本地TCP桥，默认监听 `127.0.0.1:55558`。
2. `Resources/Python/MassBattleMcpServer.py`，一个STDIO MCP服务器，将Codex工具调用转发到UE桥。
安装到Codex：
```powershell
.\Scripts\Install-CodexMassBattleMCP.ps1
```
快速检查安装和UE桥：
```powershell
.\Scripts\QuickStart-CodexMassBattleMCP.ps1
```
安装成功后，请重启Codex或启动新会话。UE编辑器还必须加载此插件，然后桥才能开始监听。
安装成功后，您应该看到 `massbattle-editor-mcp`，并且能够调用诸如 `unit_get`、`unit_create`、`unit_write`、`unit_delete`、`effect_asset_read_summary`、`niagara_set_module_pin`、`batch_fx_read_renderer_defaults` 和 `batch_fx_set_renderer_defaults` 等基本工具。
注意：`FFxConfig.AgentBehaviorState` 使用 `EAgentBehaviorState`。可写值包括 `None`、`Appearing`、`Sleeping`、`Patrolling`、`Attacking`、`Hit` 和 `Dying`。命中效果应使用 `Hit`；请勿将运行时标志名称 `BeingHit`写入此字段。
## MCP能力列表
| 类别 | MCP工具 | 状态 | 目的 |
| --- | --- | :---: | --- |
| 连接/诊断 | `massbattle_ping` | 可用 | 确认Codex MCP服务器可以连接到UE编辑器桥。 |
| 连接/诊断 | `unit_get_api_status` | 可用 | 读取单位MCP能力。 |
| 连接/诊断 | `effect_asset_get_api_status` | 可用 | 读取效果资产/批量FX MCP能力。 |
| 连接/诊断 | `niagara_get_api_status` | 可用 | 读取Niagara MCP能力。 |
| 单位MCP | `unit_list` | 可用 | 列出`MassBattleAgentConfigDataAsset`单位配置资产。 |
| 单位MCP | `unit_get` | 可用 | 读取具有简单/完整视图和默认过滤的单位配置。 |
| 单位MCP | `unit_get_schema` | 可用 | 读取可编辑的单位字段、类型、角色和工具提示。 |
| 单位MCP | `unit_export` | 可用 | 导出紧凑的单位平衡表用于分析或批量审查。 |
| 单位MCP | `unit_find_assets` | 可用 | 查找用于单位创作的候选骨骼网格、渲染器、Niagara和相关资产。 |
| 单位MCP | `unit_create` | 可用 | 创建新单位；如果没有提供模板，则使用默认模板；支持可选的初始单位数据。 |
| 单位MCP | `unit_write` | 可用 | 将部分源对齐的JSON联合写入现有单位；省略的字段保持不变。 |
| 单位MCP | `unit_delete` | 可用 | 显式删除或软删除单位；默认情况下为干预运行。 |
| 样式MCP | `style_summarize_units` | 可用 | 按样式、家族和路径类别汇总单位资产。 |
| 样式MCP | `style_plan_organize_units` | 可用 | 在不移动资产的情况下规划基于样式的单位文件夹组织。 |
| 单位编辑器MCP | `editor_get_status` | 可用 | 读取单位编辑器工作流能力。 |
| 单位编辑器MCP | `editor_list_profiles` | 可用 | 列出样式配置文件和创作配方。 |
| 单位编辑器MCP | `editor_get_profile` | 可用 | 读取一个配置文件或配方。 |
| 单位编辑器MCP | `editor_plan_organize_unit_assets` | 可用 | 计划将一个单位和链接的生成资产移动到样式布局中。 |
| 单位编辑器MCP | `editor_apply_organize_unit_assets` | 可用 | 应用审查后的单位资产组织计划；默认情况下为干预运行。 |
| 效果资产MCP | `effect_asset_query` | 可用 | 按`query/root/classes/limit`查询视觉资产，如Niagara、Cascade、蓝图、材质、纹理和声音。 |
| 效果资产MCP | `effect_asset_read_summary` | 可用 | 读取未知效果资产类型的摘要；Cascade返回发射器、LOD、模块和依赖项详细信息。 |
| 效果资产MCP | `effect_asset_export_text` | 可用 | 导出用于AI阅读和审查的确定性文本。 |
| 效果资产MCP | `effect_asset_soft_delete` | 可用 | 读取引用，然后将未引用的资产移动到 `_Trash`；默认情况下为干预运行。 |
| 效果资产MCP | `effect_duplicate_asset` | 可用 | 在不删除或覆盖源的情况下添加复制资产。 |
| Niagara MCP | `niagara_query` | 可用 | 按路径或名称查询Niagara系统。 |
| Niagara MCP | `niagara_read_summary` | 可用 | 读取Niagara系统、发射器、渲染器、用户参数和模块摘要。 |
| Niagara MCP | `niagara_read_module` | 可用 | 读取一个Niagara模块节点及其引脚。 |
| Niagara MCP | `niagara_export_text` | 可用 | 导出确定性Niagara文本。 |
| Niagara MCP | `niagara_merge_write` | 可用 | 联合写入Niagara属性；不处理删除。 |
| Niagara MCP | `niagara_set_module_pin` | 可用 | 写入一个Niagara FunctionCall模块输入引脚默认值；默认情况下拒绝链接的引脚。 |
| Niagara MCP | `niagara_set_emitter_enabled` | 可用 | 显式启用或禁用一个Niagara发射器句柄。 |
| Niagara MCP | `niagara_delete` | 可用 | 显式删除渲染器、用户参数、禁用发射器等。 |
| 批量FX MCP | `batch_fx_read_renderer_defaults` | 可用 | 读取`AMassBattleFxRenderer`蓝图默认值，这些默认值由新放置的演员继承。 |
| 批量FX MCP | `batch_fx_set_renderer_defaults` | 可用 | 设置`AMassBattleFxRenderer`蓝图默认值，包括`NiagaraSystemAsset`、`NDC_BurstFx`、`SubType`、批量大小和池冷却。 |
批量FX循环是：读取或复制参考效果资产，准备批处理的Niagara/NDC/渲染器蓝图，让MCP写入并验证渲染器蓝图默认值，让用户在测试关卡中放置渲染器演员，然后使用单位MCP将`FFxConfig`写入`Hit.SpawnFx`、`Death.SpawnFx`和`Attack.SpawnFx`等数组。MCP不会自动修改当前关卡布局。只要用户不覆盖实例参数，新放置的演员应该继承资产默认值。
## 默认样式和基于模板的工作流
默认样式配置文件是 `Resources/UnitManagementStyles/default.massbattle_unit_style.json`。
它不是运行时功能。它是AI和MCP工具的创作上下文：扫描根目录、单位组织规则、单位创作默认值和批量FX模板。
当 `unit_create` 未收到 `template_unit` 时，它会读取 `authoring_defaults.default_unit_template` 作为默认单位模板。在使用默认模板创建之前，请配置该路径。
批量FX不应从空白资产开始。推荐流程：
1. 使用 `editor_get_profile` 读取 `style/default`。
2. 从 `batch_fx_templates` 中选择最接近的模板，例如 `mesh_burst_hit`、`sprite_explosion_burst` 或 `projectile_muzzle_burst`。
3. 使用 `effect_duplicate_asset` 复制Niagara和渲染器蓝图模板。
4. 使用 `niagara_set_emitter_enabled` / `niagara_delete` 禁用不必要的发射器。
5. 使用 `niagara_merge_write` 写入渲染器、发射器数据、边界和其他UObject属性。
6. 使用 `niagara_set_module_pin` 微调模块输入引脚，例如Lifetime、Scale、Spawn Count或随机范围。
7. 使用 `batch_fx_set_renderer_defaults` 写入渲染器CDO Niagara、NDC、SubType和批量大小。
8. 使用 `unit_write` 将单位 `FFxConfig` 条目指向相应的 `SubType`。
此模式类似于代码差异：模板承载大部分结构，而MCP执行小的可审查的编辑。
