105 lines
3.7 KiB
Markdown
105 lines
3.7 KiB
Markdown
# UI 拼接工具
|
||
|
||
## 目的
|
||
|
||
UI 拼接工具通过 JSON 与 Unity Prefab 双向转换，帮助 Codex 和开发人员创建基础 UI 层级、检查现有 Prefab，并继续在 Unity 中完成业务绑定和视觉校对。
|
||
|
||
## 当前实现
|
||
|
||
| 组件 | 位置 | 职责 |
|
||
|---|---|---|
|
||
| `UIPrefabGenerator` | `Assets/Editor/Command/UIPrefabGenerator.cs` | 读取 UI JSON 并生成 Prefab |
|
||
| `UIPrefabToJson` | `Assets/Editor/Command/UIPrefabToJson.cs` | 导出 Prefab 的层级和组件数据 |
|
||
| Unity Bridge | `Assets/Editor/Command/CodexUnityEditorBridge.cs` | 在 Unity 主线程执行生成和导出命令 |
|
||
| MCP Server | `UnityAI/Tools/CodexUnityMcp/` | 把 Unity Bridge 命令暴露给 Codex |
|
||
|
||
当前外部入口是 MCP Bridge，不使用文件监听或文本触发命令。
|
||
|
||
## 数据结构
|
||
|
||
根节点使用 `UILayoutData`：
|
||
|
||
```json
|
||
{
|
||
"name": "ExampleWindow",
|
||
"type": "Canvas",
|
||
"layer": 5,
|
||
"rectTransform": {
|
||
"anchorMin": [0.5, 0.5],
|
||
"anchorMax": [0.5, 0.5],
|
||
"position": [0, 0, 0],
|
||
"sizeDelta": [1080, 1920],
|
||
"pivot": [0.5, 0.5],
|
||
"localScale": [1, 1, 1],
|
||
"localRotation": [0, 0, 0]
|
||
},
|
||
"children": []
|
||
}
|
||
```
|
||
|
||
子节点使用 `UIElementData`，可配置 `rectTransform`、`image`、`button`、`text`、`layoutGroup`、`scrollRect`、`toggle`、`slider`、`inputField`、`customComponents` 和递归 `children`。
|
||
|
||
## 支持组件
|
||
|
||
- `Image` / `SFUI_Image`
|
||
- `Button` / `SFUI_Button`
|
||
- `TextMeshProUGUI` / `SFUI_TextMeshProUGUI`
|
||
- `RectTransform`、`Canvas`、`CanvasScaler`、`GraphicRaycaster`
|
||
- `ScrollRect` / `SFUI_ScrollRect`
|
||
- `SFUI_Viewport`、`SFUI_Content`、`SFUI_ListViewItem`
|
||
- `GridLayoutGroup`、`VerticalLayoutGroup`、`HorizontalLayoutGroup`
|
||
- `Toggle` / `SFUI_Toggle`
|
||
- `Slider` / `SFUI_Slider`
|
||
- `InputField` / `SFUI_InputField`
|
||
|
||
资源字段使用 Unity Asset 路径，例如 `Assets/Game/...`，路径分隔符统一使用 `/`。
|
||
|
||
## MCP 调用
|
||
|
||
生成 Prefab：
|
||
|
||
```text
|
||
unity_generate_ui_prefab(jsonPath, prefabPath)
|
||
```
|
||
|
||
导出 Prefab：
|
||
|
||
```text
|
||
unity_export_prefab_to_json(prefabPath, jsonPath)
|
||
```
|
||
|
||
路径由当前任务明确传入，不规定固定测试目录或中间数据目录。目标正式窗口通常位于：
|
||
|
||
```text
|
||
Assets/Game/GameHFResource/<语言>/UIWindows/<WindowName>/<WindowName>.prefab
|
||
```
|
||
|
||
## 标准流程
|
||
|
||
1. 先读 [UI 界面拼接](../UI窗口系统/界面拼接.md) 和 [UI 开发指南](../UI窗口系统/开发指南.md)。
|
||
2. 调用 `unity_health` 确认 Unity 项目和版本。
|
||
3. 检查目标 Prefab、窗口脚本和可用资源。
|
||
4. 生成基础 Prefab，或先导出现有 Prefab 再调整 JSON。
|
||
5. 调用 `unity_refresh_assets`。
|
||
6. 调用 `unity_get_console_logs` 检查 Error 和关键 Warning。
|
||
7. 在 Unity 中检查层级、RectTransform、组件、资源引用和实际显示。
|
||
|
||
工具生成成功只表示 Prefab 文件已创建，不表示 UI 已完成。业务脚本、列表初始化、字体、图集、点击区域和视觉结果仍需验证。
|
||
|
||
## 安全规则
|
||
|
||
- 覆盖已有 Prefab 前确认目标路径和现有内容。
|
||
- 不通过 UI 生成工具批量删除、移动资源或执行构建发布。
|
||
- Unity API 必须由 Bridge 排队到 Editor 主线程执行。
|
||
- 生成后检查 Git 差异，避免无意义重序列化其他资源。
|
||
- JSON 递归结构出现 serialization depth warning 时检查实际生成结果；新增 Error 必须处理。
|
||
|
||
## 文档关联
|
||
|
||
| 文档 | 关联原因 |
|
||
|---|---|
|
||
| [编辑器工具入口](README.md) | 编辑器工具模块入口 |
|
||
| [UI 窗口系统](../UI窗口系统/README.md) | 窗口框架和资源路径 |
|
||
| [UI 界面拼接](../UI窗口系统/界面拼接.md) | 视觉与 Prefab 流程 |
|
||
| [MCP 使用规则](MCP工具/CrystalBattle_Codex_Unity_MCP使用规则.md) | Codex 调用和安全边界 |
|