内容
# ge-mcp — GIANTS 编辑器 ⇄ Claude 桥接
让 Claude 控制一个 **实时 GIANTS 编辑器 10.x (FS25)** 会话。要求一个河流，得到一个雕刻的河床，沿着你的样条线。要求一个麦田，得到一个游戏-ready的田地——多边形，地面，作物，农田——从一个封闭的样条线中生长出来。问“我的地图有什么问题？”并得到文件引用、碰撞、交通样条线和农田分配的审计报告。问“给我看看”，然后 Claude 会 *查看你的编辑器* 并回答。
**59 个工具**，分布在 12 个可切换的组中，加上一个 **代码段库**，它可以将任何曾经有效的 Lua 代码变成可重复执行的单行代码。
```
你： 沿着 creek_spline 挖一条 2m 深的沟渠，并用 mudDark01 绘制河床
克劳德：spline_adjust_terrain(creek_spline, mode=lower, depth=2, width=6) [预览 → 提交]
spline_adjust_terrain(mode=smooth) [软化河岸]
spline_paint_terrain(creek_spline, layer=mudDark01, width=5) [河床纹理]
viewport_screenshot() [显示结果]
```
## 图库 — 真实的输出，实时编辑器
| | |
| --- | --- |
|  | **五步创建田地**：封闭样条线 → `field_ops create_from_spline` → `set_ground` → `set_fruit wheat 8` — 官方田地结构，耕地，收获-ready 作物。 |
|  | **区域工具**：`terrain_flatten_area` + `paint_foliage_area` 精确填充到样条线边界（引擎端多边形栅格化）。 |
|  | **`camera_topdown`**：按需生成正交小地图块，相机恢复原状。 |
|  | **`asset_ops`**：搜索 5,000+ 基础游戏 i3ds，`place` 场景中的地形对齐。 |
## 为什么可以安全地指向你的地图
在（并且因为）真正的编辑器崩溃和地图损坏后构建：
1. **每个写入工具默认预览** — `commit=false` 报告操作次数和更改内容；只有 `commit=true` 才会触及场景。
2. **操作上限** 拒绝超大任务，以免冻结/崩溃 GE。
3. **确定性种子** — 预览即是提交（相同的种子，相同的结果）。
4. **放置到一个新组** — 删除它以撤销整个运行。
5. **地形高度操作分为两阶段**（所有读取在写入之前）因此传递永远不会复合；相对较低/提高具有相同参数的相反操作会相互抵消。
6. **删除崩溃防护** — 选定节点清除首先（删除选定节点会崩溃 GE），根节点/地形/相机拒绝，ID 有效性检查。
7. **`run_lua` 验证** 针对编辑器的实时全局变量在运行前；未知名称被拒绝，并给出建议而不是在脚本中报错。
地形/植被绘制 **没有编辑器撤销** — 不确定时先 `save_scene`。
## 组件
| 组件 | 位置 | 任务 |
| --- | --- | --- |
| MCP 服务器 | `ge_mcp/` (Python) | 工具，验证，安全门 |
| 轮询器 | `lua/ge_mcp_poller.lua` | 在编辑器中运行；执行 Lua，捕获事件 |
| 帮助库 | `lua/ge_mcp_helpers.lua` | 在首次使用时自动注入编辑器 |
| 代码段 | `snippets/*.json` | 你保存的，可重复执行的脚本（可共享的软件包） |
服务器和编辑器通过编辑器的 AppData 文件夹中的 XML 邮箱文件进行通信（base64 有效载荷；无竞争的单次飞行）。编辑器版本自动检测。
## 快速入门
**克劳德桌面，一键安装**：`pip install mcp`，然后将 `ge-mcp-<version>.mcpb` 拖入克劳德桌面，询问克劳德 *“运行安装程序并安装轮询器”*，启动编辑器并运行 **脚本 → GE-MCP 桥接器**。完成。手动路线：
1. `pip install mcp`（或在此文件夹中使用 `ge-mcp` 命令的 `pip install -e .`）
2. 注册服务器 — 克劳德桌面 `claude_desktop_config.json`：
```json
"giants-editor": {
"command": "python",
"args": ["D:\\path\\to\\GiantsEditor-mcp\\giants_mcp_server.py"]
}
```
（克劳德代码：`claude mcp add giants-editor -- python D:\path\to\giants_mcp_server.py`）
3. 每个编辑器会话：从编辑器的 **脚本** 菜单运行 `lua/ge_mcp_poller.lua`（将其放入 `%LOCALAPPDATA%\GIANTS Editor 64bit <version>\scripts\` 一次）。
日志显示 `[GE-MCP] 桥接器已激活` — 你已在线。
4. 询问克劳德 `ping_editor`，然后尝试 `list_splines` 或 `viewport_screenshot`。
完整的设置细节和故障排除：[INSTALL.md](INSTALL.md)。
完整的工具参考：[docs/TOOLS.md](docs/TOOLS.md)。
工作原理：[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。
## 我可以问什么？
普通英语 — 克劳德选择工具。实际例子今天就有效：
**查看和检查**
- “给我编辑器的截图” / “给我看看 12 号田地从上面”
- “围绕旧谷仓旋转，显示所有四面”
- “当前选择了什么？” / “3 号田地有多大，坡度是多少？”
- “给我显示视口的坡度热图” （调试渲染模式）
**地形和水**
- “沿着 creekSpline 挖一条 2m 深的沟渠，软化河岸，并用 mudDark01 绘制河床”
- “在我的 pad_outline 样条线内平整一个建筑垫，并混合边缘”
- “在我的采石场样条线内为所有坡度大于 25° 的斜坡绘制岩石纹理”
**种植和放置**
- “沿着 treeline_south 每 8m 放置一棵橡树，随机旋转和缩放 0.9–1.2”
- “沿着 paddock_spline 建造围栏 — 每 2.5m 放置一根柱子”
- “在基础游戏中找一棵白桦树，并将其放置在 500, 620 处”
- “让我的岩石堆看起来更自然” （随机化 + 倾斜到坡度）
**田地和游戏玩法**
- “将我的封闭样条线变成 22 号田地，耕作并种植小麦到收获”
- “哪些田地在错误的农地上？” / “在边界内绘制农地 14”
**地图质量（发布前运行）**
- “备份我的地图” — 总是在绘制之前
- “审计我的地图：损坏的文件引用，碰撞，交通样条线”
- “列出所有剪辑距离超过 100000 的节点” （通过保存的代码段）
**高级用户**
- “在编辑器 API 中搜索关于样条线的任何信息” / “阅读我的围栏面板脚本的工作原理”
- “运行一些 Lua 代码：...” — 在执行前针对编辑器的实时函数进行验证
- “将该代码保存为代码段” — 任何有效的内容都变成可重复执行的单行代码
每次写入都会显示 **预览** （内容，位置，操作次数）并且只有在您确认后才会应用。放置内容会进入一个组 — 删除它以撤销。
## 工具组
- `core` — 桥接器健康，`setup` 诊断，验证的 `run_lua`，API 搜索，内置 + 用户脚本读取，编辑器事件
- `splines` — 发现，沿样条线放置，完整的 **编辑点编辑** （覆盖/重采样/反转/拆分/连接/偏移复制），连接的围栏线
- `terrain` — 纹理/植被带和多边形填充，高度调整（道路床，U/V 河床，相对雕刻/抬升/平滑），平整垫，基于坡度的自动纹理，统计数据
- `nodes` — 检查，变换，重命名，安全删除，世界保护的重新父节点，随机化，地形/法线对齐，i3d 导入
- `fields` — 从样条线创建田地，地面/水果绘制，农地所有权 + 审计，通用信息层
- `hygiene` — 场景/文件引用/纹理/碰撞/光线审计，批量重命名/清理/数组/替换，XPath 进入 i3d
- `materials` / `traffic` — 着色器参数工作；交通样条线验证（约定感知）
- `assets` — `$data` 目录：搜索，检查，放置；modDesc + 可放置验证，水果/填充类型；`xml_schema` — 游戏自己的 88 个 XSD 作为可浏览的参考（任何 FS25 XML 类型的有效元素/属性/枚举）
- `vision` — 聊天截图，相机瞄准/环绕/俯瞰图块，39 种调试渲染模式，编辑器日志
- `scene` — 验证保存（Ctrl+S + ON_SAVE 确认），时间戳地图备份
- `snippets` — 在零模式成本下保存/运行/列出已验证的 Lua 代码
使用 `GE_MCP_GROUPS` 注册来修剪（例如 `core,splines,nodes`）以保持模式在模式密集的客户端中较小。完整参考：[docs/TOOLS.md](docs/TOOLS.md)。
## 代码段：自我增长的工具包
当克劳德编写一个有效的 `run_lua` 并值得保留时，它会保存：
```
save_snippet("find-high-clip", lua, description="列出节点剪辑距离 > ARGS.limit",
params="limit=800")
run_snippet("find-high-clip", "limit=500")
```
无限保存的脚本，零附加模式成本，`snippets/` 是纯 JSON — 与其他模组者交换软件包。
## 搭配良好
**[fs25-skills](https://github.com/Paint-a-Farm/fs25-skills)** 由 Paint-a-Farm — FS25 模组知识的 AI 代理（modDesc 标准，Lua 模式，i3d/DDS 格式，包装，调试）。该软件包教导您的代理游戏的约定；ge-mcp 让它在实时编辑器中运行。克劳德代码用户：两个斜杠命令安装它（参见 [INSTALL.md](INSTALL.md#recommended-companion--the-fs25-knowledge-pack))。
## 兼容性
GIANTS 编辑器 10.x / FS25 在 Windows 上。测试版本为 10.0.13。编辑器更新不会破坏桥接器（路径自动检测）；新的编辑器 API 通过 `refresh_api` 出现。
## 出现问题？
询问克劳德运行 `setup`（它会命名损坏的链接）和 `read_log 40 errors`，然后在 [https://github.com/0h-MARVVV/giants-editor-mcp/issues](https://github.com/0h-MARVVV/giants-editor-mcp/issues) 上打开一个问题，附上两个输出，您的 GE 版本以及您请求的内容。大多数“无法正常工作”的报告是 [故障排除表](INSTALL.md#troubleshooting) 的前三行之一。
不隶属于 GIANTS Software。MIT 许可 — 见 [LICENSE](LICENSE)。
灵感来自社区的编辑器面板脚本（样条线绘制/高度/植被面板由 W_R/Nicolas Wrobel, Farmerboys, FSG, XPModder 等人制作）— 该项目封装了相同的引擎调用，提供了一个会话式，安全门控的接口。
