| name | ra3-csharp-map-editing |
| description | 使用 C# 批量编辑 Red Alert 3 地图（Ra3MapSharp / Dreamness.RA3.Map.Facade），并通过 Ra3MapUtils 地编伴侣直接执行 C#（HTTP 与 MCP）。 当用户需要地图自动化改图、地形纹理处理、单位/路径点/玩家/队伍调整、脚本 JSON 导入导出、或查询 C# 地图库 API 时使用。 Use when users ask for RA3 map editing in C#, map automation scripts, map data import/export, or running C# via companion MCP/HTTP. |
ra3-csharp-map-editing
用于在 RA3 地图工作流中稳定地执行 C# 改图任务，覆盖三条执行链路：
- 本地 C# 工程直接调用
Ra3MapFacade
- 地编伴侣 HTTP 执行 C#（
/api/csharpscript/*）
- 地编伴侣 MCP 执行/反射查询 C# 能力（
/mcp）
触发场景
- 需要用 C# 批量修改 RA3 地图内容
- 需要在已有地图上修改地形/纹理/单位/路径点/玩家/队伍
- 需要导入导出
PlayersData.json、TeamsData.json、ScriptsData.json
- 需要通过地编伴侣直接运行 C# 脚本
- 需要对接 MCP 大模型能力调用 RA3 地图库
执行路径选择
按任务环境优先选择：
- 本地 C# 工程：优先用于真实项目开发与调试，可完整控制依赖、日志、断点。
- HTTP 执行：优先用于“快速运行一段 C#”或“临时任务”，接口为
http://127.0.0.1:30033/api/csharpscript/run/code|run/file。
- MCP 执行：优先用于大模型自动化编排，通过地编伴侣
http://127.0.0.1:30033/mcp 调用 RunRa3CSharpScript 等工具。
安全与一致性约束
每次执行改图前都执行以下约束：
- 先备份地图：
优先通过地编伴侣扩展
ra3map.Backup()，或手动复制 .map 文件。
- 坐标系不混用：
地形/纹理/通行属性使用 Grid 坐标（整数格子）。
单位/路径点使用 World 坐标（浮点，通常为格子坐标的 10 倍尺度）。
NewMap 首次必须 SaveAs：
新建地图调用 Save() 会因缺少 MapFilePath 抛错。- 改完高度后执行
UpdatePassabilityMap()：
保证通行数据与高度一致。
- 需要纹理融合时执行自动融合：
区域编辑后可调用
AutoDetectBlendsInRegion 或 AutoDetectBlendsEntireMap。
- 导入 JSON（玩家/队伍/脚本）后重新保存并验证：
导入后建议重新打开地图做一次读取校验。
标准工作流
- 选择执行路径（本地工程 / HTTP / MCP）。
- 打开地图或新建地图。
- 读取地图尺寸与目标对象（地形、单位、玩家、队伍等）。
- 应用批量修改。
- 执行一致性操作：
高度后刷新通行，必要时重建融合。
- 保存：
现有地图可
Save()，新图必须 SaveAs(...)。
- 回归检查：
打开结果地图，抽查关键对象和数据是否符合预期。
错误分流
- 伴侣未启动/不可达：
先请求
GET /api/status/companion；失败则提示先启动 Ra3MapUtils。
- HTTP 执行失败：
按
ApiResponseCode 处理：
1003 参数/文件路径问题，1002 C# 执行失败，1001 未知错误。
- C# 编译或运行异常：
优先保留原始错误栈，再给出最小修复建议，不直接掩盖异常。
- 地图改坏或数据异常：
立即回滚备份文件，再缩小变更范围重试。
参考文档导航
只在需要时加载对应 reference，不要一次性加载全部文档。
输出要求
执行该 skill 时，输出必须包含：
- 使用了哪条执行路径以及原因。
- 对地图做了哪些变更。
- 做过哪些安全动作（备份、通行刷新、融合重建）。
- 保存位置与验证结果。
