UnityAI/modules/frameworks/编辑器工具/UI拼接工具.md

# 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 调用和安全边界 |