diff --git a/06_工具脚本/MCP工具/CrystalBattle_Codex_Unity_MCP使用规则.md b/06_工具脚本/MCP工具/CrystalBattle_Codex_Unity_MCP使用规则.md index 0969907..1d074d4 100644 --- a/06_工具脚本/MCP工具/CrystalBattle_Codex_Unity_MCP使用规则.md +++ b/06_工具脚本/MCP工具/CrystalBattle_Codex_Unity_MCP使用规则.md @@ -13,57 +13,23 @@ MCP(Model Context Protocol)用于打通 Codex 与 Unity Editor。Codex 不 ## 2. 工程结构 -Unity Editor 侧: +本文档只说明 Codex 如何对接 Unity MCP,不说明 Unity Editor 内部脚本目录结构,也不在本节维护数据目录。 + +Codex 需要知道的对接点: ```text -CrystalBattle_Client/Assets/Editor/Command/ -├── CodexUnityEditorBridge.cs -├── CodexUnityEditorBridgeWindow.cs -├── UIPrefabGenerator.cs -└── UIPrefabToJson.cs -``` - -MCP 测试数据目录: - -```text -CrystalBattle_Client/Assets/Editor/MCP_{功能名}/ -└── / -``` - -Codex MCP Server 侧: - -```text -UnityAI/Tools/CodexUnityMcp/ -├── src/server.mjs -├── package.json -├── pnpm-lock.yaml -└── README.md -``` - -Codex 配置: - -```text -.codex/config.toml -``` - -Unity Bridge 默认地址: - -```text -http://127.0.0.1:17777 +Unity MCP Server: UnityAI/Tools/CodexUnityMcp/ +Codex config: .codex/config.toml +Unity Bridge URL: http://127.0.0.1:17777 ``` ## 3. 启动与连接 -1. 打开 `CrystalBattle_Client` Unity 工程,并等待脚本编译完成。 -2. 打开 Unity 面板: - -```text -Tools/Codex Unity MCP/Bridge Panel -``` - -3. 面板中确认状态为 `已连接`。如果未连接,点击 `开始连接`。 -4. Codex 侧重启或新开线程后,会读取 `.codex/config.toml` 中的 `crystalbattle-unity` MCP server 配置。 -5. 每轮 Unity 自动化前,优先调用 `unity_health` 检查连通性。 +1. 确认 `.codex/config.toml` 中存在 `crystalbattle-unity` MCP server 配置。 +2. 确认 MCP Server 入口指向 `UnityAI/Tools/CodexUnityMcp/src/server.mjs`。 +3. Codex 侧重启或新开线程后,会重新读取 MCP server 配置。 +4. 每轮 Unity 自动化前,优先调用 `unity_health` 检查连通性。 +5. 如果 `unity_health` 不通,只记录错误并停止后续 Unity 操作;Unity 侧如何打开或重启 Bridge 不在本文档说明范围内。 禁止事项: @@ -84,7 +50,7 @@ Tools/Codex Unity MCP/Bridge Panel ## 5. MCP 数据目录规则 -所有 MCP 数据必须按功能单独放在 Unity Editor 目录下,并直接按目标预制体名分文件夹;不再额外创建 `TestData` 目录。统一格式: +所有 MCP 数据必须按功能单独放在 Unity Editor 目录下,并直接按目标预制体名分文件夹;不再增加中间层目录。统一格式: ```text Assets/Editor/MCP_{功能名}// @@ -96,28 +62,30 @@ Assets/Editor/MCP_{功能名}// - `` 必须沿用目标预制体名称,和最终生成的 `.prefab` 保持一致。 - UI 相关数据统一放在 `Assets/Editor/MCP_UI//`。 - 其它功能按能力命名,例如 `Assets/Editor/MCP_Config//`、`Assets/Editor/MCP_Map//`。 -- `Assets/Editor/Command/` 只放 Editor Bridge 和工具脚本,不再放数据文件夹。 - 新增、导出、临时验证用 JSON 都必须遵守该目录规则。 -历史说明: - -- 早期测试样例曾放在 `Assets/Editor/Command/TestData/`。 -- 后续新增或整理数据时,应迁移到 `Assets/Editor/MCP_UI//` 或对应功能目录。 +整理旧数据时,应迁移到 `Assets/Editor/MCP_UI//` 或对应功能目录。 ## 6. UI 生成规则 标准流程: -1. 在 `Assets/Editor/MCP_UI//` 准备 UI JSON,文件夹名必须沿用预制体名。 -2. 调用 `unity_generate_ui_prefab`。 -3. 目标 Prefab 路径优先使用: +1. 先读取 `F:/JMNet/AIMCP/UnityAI/README.md` 中的 `UI相关` 索引。 +2. 根据 README 的 UI 相关入口,优先阅读: + - `F:/JMNet/AIMCP/UnityAI/03_核心功能/UI/UI开发指南.md` + - `F:/JMNet/AIMCP/UnityAI/03_核心功能/UI/UI界面拼接设计指南.md` +3. 需要使用 JSON 与 Prefab 双向转换时,再阅读 README 中的 `UI工具` 入口: + - `F:/JMNet/AIMCP/UnityAI/06_工具脚本/UI工具/` +4. 按 UI 指南确认窗口命名、层级、资源路径和布局规则后,准备 UI JSON。 +5. 调用 `unity_generate_ui_prefab`。 +6. 目标 Prefab 路径优先使用: ```text Assets/Game/GameHFResource/CN/UIWindows//.prefab ``` -4. 调用 `unity_get_console_logs` 查看是否有 Error 或关键 Warning。 -5. 如需要验证双向转换,再调用 `unity_export_prefab_to_json`。 +7. 调用 `unity_get_console_logs` 查看是否有 Error 或关键 Warning。 +8. 如需要验证双向转换,再调用 `unity_export_prefab_to_json`。 JSON 约束: @@ -147,15 +115,14 @@ MCP 工具可以触发 Unity Editor 行为,因此必须保持最小权限: 连接失败: -1. 在 Unity 中打开 `Tools/Codex Unity MCP/Bridge Panel`。 -2. 点击 `开始连接` 或 `重启连接`。 -3. 用浏览器或 PowerShell 检查: +1. 调用 `unity_health` 获取错误信息。 +2. 用浏览器或 PowerShell 检查: ```powershell Invoke-WebRequest -UseBasicParsing "http://127.0.0.1:17777/health" ``` -4. 如果端口占用,先在 Unity 面板断开连接,再重新开始连接。 +3. 如果连接仍失败,停止后续 Unity 操作并记录错误;Unity 侧启动、重启、面板操作不在本文档说明范围内。 MCP 工具不可见: @@ -183,12 +150,6 @@ UI 生成失败: - `unity_export_prefab_to_json` 能把测试 Prefab 导出 JSON。 - Unity Console 无新增 Error。 -测试数据路径必须遵守: - -```text -Assets/Editor/MCP_{功能名}// -``` - UI 测试样例推荐路径: ```text @@ -202,7 +163,7 @@ Assets/Editor/MCP_UI/CodexMcpTestWindow/CodexMcpTestWindow.exported.json 新增 MCP tool 时必须同步更新: - `UnityAI/Tools/CodexUnityMcp/src/server.mjs` -- `CrystalBattle_Client/Assets/Editor/Command/CodexUnityEditorBridge.cs` +- Unity Bridge 侧对应命令代码 - 本文档的工具列表与测试基准 新增 Unity 命令时必须满足: @@ -222,6 +183,6 @@ Assets/Editor/MCP_UI/CodexMcpTestWindow/CodexMcpTestWindow.exported.json 文档版本: -- v1.3 +- v1.4 - 生效日期:2026-07-03 - 适用项目:CrystalBattle_Client