[ugui_to_fairygui]Unity 编辑器扩展，一键批量转换 UGUI Prefab工程为 FairyGUI 工程

Creator 2.x 扩展插件
#1

UGUI_to_FairyGUI 是一款 Unity 编辑器扩展，可将使用 UGUI 搭建的 Prefab 一键批量转换为 FairyGUI 工程结构，省去手动对照还原界面的重复劳动。
https://www.bilibili.com/video/BV1xjKi6fEC6

功能介绍

UGUI_to_FairyGUI 是一个 Unity 编辑器扩展，把使用 UGUI（Unity UI / uGUI）搭建的 Prefab 批量转换为 FairyGUI 的工程结构（package.xml + component + image 等资源）。

转换在编辑器内离线完成，不需要运行游戏。导出的工程可以直接用 FairyGUI 编辑器打开继续编辑。导出后，建议以 FairyGUI 工程作为后续 UI 迭代的主工程，不再回头维护原始 UGUI Prefab。

目标用户：已经在 Unity 里用 UGUI 做好了界面，希望迁移到 FairyGUI、或想同时产出 FairyGUI 版本的项目。

说明：本工具只提供「UGUI Prefab → FairyGUI 工程」的转换能力，不包含任何演示用的界面素材。文档与商店页中用于演示的界面截图、宣传图，所使用的 UI 工程来自其他第三方 GUI 资源商店，并不包含在本项目中。

解决的问题

Unity UI 项目中的界面通常是复杂的树形 Prefab。列表（商店、背包、图鉴等）一般作为 Prefab 内部的一个子树，由 LayoutGroup 组织，子项也包含在这棵 Prefab 树里。要把这样的列表搬进 FairyGUI，传统做法是手动把每个子项拆成独立 Prefab、再搭成 <list>，工作量大且容易遗漏。本工具把这部分重复劳动自动化。

重要：UGUI 和 FairyGUI 是两套架构迥异的 UI 系统。本工具解决的是静态结构 + 资源 + 基础交互的自动化迁移，无法覆盖动画、特效、遮罩、粒子、自定义脚本等系统级差异——这些部分仍需在 FairyGUI 编辑器中手工处理。工具产出的 XML 可直接在 FairyGUI 编辑器中打开修改，把它当作「省去重建骨架」的起步，而不是最终成品。

核心能力

  1. 一键导出：选择 Prefab 目录 → 选择输出目录 → 生成完整的 FairyGUI 工程（组件 XML、package.xml、.fairy 文件）。

  2. 全量组件映射：Image（Simple/Sliced/Filled）、Text/TMP、Button、Toggle、Slider、ScrollBar、ScrollRect、InputField、Dropdown、LayoutGroup（TMP 运行时自动检测，无需预装）。

  3. 按钮过渡效果保留：None/Animation → downEffect="scale"、ColorTint → controller + gearColor 六态颜色、SpriteSwap → controller + gearIcon 多态图标，完整映射为 FairyGUI 的 controller/gear 体系。

  4. 按钮命名约定：targetGraphic 对应的独立 Image 改名为 bg，状态图标节点保持 icon；icon 优先、bg 非必须、icon 与 bg 不会是同一对象。

  5. Toggle 选中图标：selectedIcon 取自 Toggle 的 graphic（checkmark），数据驱动。

  6. 引用组件覆写：dedup 重复项通过 <component> 引用 rep 组件时，title/icon/titleColor/titleFontSize 自动作为 <Button> 子节点传递到引用元素上。

  7. 九宫格保留：UGUI Image.Sliced → FGUI scale="9grid"，边距自动计算。

  8. 跨包图片共享优化：开启公共包后，被多个包引用的 Sprite 自动归入 Common/ 共享包，避免冗余。

  9. 嵌套 Prefab：与 Button / Slider 等一样视为组件边界，递归提取为独立组件，父组件原位置只留 <component src> 引用；同一嵌套 Prefab 在多处出现只生成一份定义，跨实例共享去重。

  10. 组件去重：分析所有 Prefab 的结构哈希，相同结构只导出一次，差异项通过 override 单独生成变体。

  11. List 子项自动提取：自动识别 Grid / Horizontal / Vertical LayoutGroup 列表，将层级下平铺的子节点提取为独立组件，生成 <list> 的 defaultItem 和 <item>，无需手动拆分 Prefab。嵌套 list 作为子项时不再误赋 Button 扩展。

  12. 组件类型配置：支持通过正则规则指定组件类型（Button/Label/Slider/ScrollBar/ComboBox），也可在去重编辑器或 Prefab 上手动调整。

  13. Prefab 重名修复：自动修复同级同名 GameObject（FairyGUI 要求名称唯一），避免导出阻塞。

  14. 确定性 ID 生成：所有组件 ID 基于名称的确定性哈希，多次导出同一预制的 ID 一致。

  15. Skip 规则：通过正则规则跳过不需要导出的 Prefab（如 Fx_ 开头的特效）。

  16. 文本描边/阴影：TMP 文本按材质/着色器关键词识别描边，导出为 FairyGUI 描边/阴影；提供默认描边宽度、描边色、阴影色等设置。

组件映射

基础显示

  • Image → 图片（image）/ 图形（Graph）：Simple/Sliced/Filled 分别映射；Sliced 转为 9grid。

  • RawImage → 图片（Texture）：按纹理引用导出。

  • Text (Legacy) → 文本（TextField）：含字体、颜色、富文本。

  • TextMeshPro → 文本（TextField）：运行时检测 TMP，转换为 FairyGUI 文本，字体回退到设置中的字体；描边/阴影按关键词识别。

交互组件

  • Button → 按钮（Button）：保留过渡效果（ColorTint / SpriteSwap），状态图标命名 icon / bg。

  • Toggle → 按钮（Button, mode=Check）：选中态图标（selectedIcon）取自 Toggle 的 graphic。

  • Slider → 滑块（Slider）：把手（grip）按规则定位，进度条（bar）建立关联。

  • ScrollBar → 滚动条（ScrollBar）：对应 FairyGUI 滚动条。

  • ScrollRect → 滚动容器：转换为带 ScrollPane 的组件，不单独抽为组件。

  • Dropdown → 下拉框（ComboBox）：展开模板（Template）剥离为独立子组件。

  • InputField → 文本输入（TextInput）：对应 FairyGUI 文本输入。

容器 / 列表

  • Horizontal/Vertical/Grid LayoutGroup → list：子项达到阈值时识别为 list，并提取为子组件。

遮罩 / 裁剪

  • RectMask2D / Mask → 遮罩（Mask）：两者共用同一套逻辑：作为独立组件边界提取（可配置），组件根设 overflow=hidden 近似矩形裁剪。Mask 的遮罩图（自身 Image）仅在 showMaskGraphic=false 时跳渲染。

顶层结构

  • Canvas → 包（package）：每个顶层 Prefab 对应一个 FairyGUI 组件。

安装注意事项

  • 本工具是 Unity 编辑器扩展，需配合 Unity 编辑器（Unity 2020.3 或更高版本，建议 2021 LTS）使用，运行于 Play 模式之外。

  • 导出产物需在 FairyGUI 编辑器（从 https://fairygui.com/ 下载）中打开做后续编辑。

  • 把 UGUI_to_FairyGUI 文件夹放在 Assets 下任意位置均可被识别（通常放在 Assets/UGUI_to_FairyGUI）。

  • TextMeshPro 场景需确保项目已导入 TMP 包（转换器会运行时检测 TMP 是否可用）。

使用教程（必须）

1. 打开工具

菜单入口均在 SkyLad 菜单下：

  1. SkyLad / Export to FairyGUI：打开导出设置面板，执行导出。

  2. SkyLad / Deduplication Editor：打开组件去重编辑器，做结构分析、dup→rep 合并、类型指定等。

2. 完整操作流程

  1. 准备 Prefab

    把要转换的 UGUI Prefab 整理到一个目录（例如 Assets/UI/Prefabs）。确保 Prefab 引用的图片在 Assets/ 下可访问。

  2. 打开设置面板

    菜单 SkyLad / Export to FairyGUI，打开「FairyGUI 导出设置」窗口。

  3. 设置目录与项目类型

    • 默认 Prefab 根目录：设置后，每次导出将跳过目录选择步骤，直接使用此路径。

    • 默认导出目录：设置后，导出将默认输出到该目录下的 FairyGUI 工程。

    • FairyGUI 项目类型：选择目标平台类型，对应 .fairy 文件中 projectDescription 的 type 属性。

    也可不设置，导出时再在弹窗中选择目录。

  4. （可选）配置组件去重

    菜单 SkyLad / Deduplication Editor，点击「分析所有组件」，生成去重分析结果（JSON）。在该编辑器里可以：

    • 查看并合并结构重复的组件（dup → rep）；

    • 为组件指定 FairyGUI 组件类型（如 Button / Slider / ComboBox 等）；

    • 设置是否「分析时自动给 Prefab 添加类型标记脚本」；

    • 维护转换类型正则规则与 Prefab 跳过规则。

    分析完成后，去重结果会自动作为导出时的权威配置。

  5. 执行导出

    回到设置面板，点击「导出到 FairyGUI」。导出流程会：

    • 清理旧的导出目录（如开启了「清理导出的 FairyGUI 目录」）；

    • 扫描 Prefab 根目录下的所有 Prefab；

    • 按配置做组件去重与子组件提取；

    • 生成 FairyGUI 包结构与资源文件。

    若发现同级同名 GameObject 且未开启「导出时重命名重复节点」，导出会中止并提示先修复重名（可用设置面板「修复重名」按钮）。

  6. 在 FairyGUI 中打开

    用 FairyGUI 编辑器打开导出目录下的工程。由于 FairyGUI 的包名由工具管理生成，首次打开时请用 FairyGUI 生成所有 package 的唯一 id。

3. 资源与引用

  • 图片位置：Prefab 引用的图片只需在 Assets/ 目录下任意位置即可，工具会按引用关系收集并拷贝，不要求放在特定目录。

  • Unity 内置资源：来自 Unity 内置的 UI 精灵、默认贴图等虚拟资源不是磁盘真实文件，导出器会按像素渲染为 PNG 自动写出，无需手动替换（压缩纹理 / 图集打包的精灵可再核对导出质量）。

  • Packages/ 与外部路径资源：这类资源当前版本不导出 PNG，需要你在 FairyGUI 里手动替换（后续可补自动导出）。

  • 嵌套 Prefab：与 Button / Slider 等交互组件一视同仁，都是「组件边界」——递归提取为独立组件，父组件原位置只保留一个 <component src> 引用节点；同一嵌套 Prefab 无论被多少个父组件引用，都只生成一份组件定义，多个引用指向它，跨实例共享去重。

更新声明

v0.8.0

  1. 支持中英文界面：窗口新增语言下拉框，可在中文 / 英文之间切换。

  2. 部件角色识别统一：icon、标题、背景、进度条、滑块手柄等部件的识别规则统一成一套，Prefab 与 Json 两种模式结果一致，不再出现识别漂移。

  3. 滑块手柄导出为按钮子组件：符合 FairyGUI 规范，手柄定位更贴合舞台边缘。

  4. 组件背景自动跟随拉伸：按钮、标签、滑块、进度条、滚动条、下拉框、输入框的背景图都会跟随父级缩放，无需手动设锚点。

  5. 遮罩支持增强：普通 Mask 组件现在也能正确导出为裁剪组件（此前仅支持 RectMask2D）。

  6. 列表 / 嵌套坐标修复：组件本身即列表时能正确生成带子项的结构；嵌套组件、退化根尺寸、坐标归一化等一批坐标相关 bug 已修复。

  7. 去重更精细：去重分组改为按资产名细分（不再把不同按钮变种塌成一组）；新增「尺寸是否参与去重」独立开关；去重 JSON 会写出空条目以覆盖旧映射。

  8. 组件提取可配置：设置面板新增开关，可单独控制滑块 / 滚动条 / 下拉框 / 输入框 / 开关 / 遮罩是否提取为独立组件。

  9. 描边与阴影可配置：新增描边宽度、描边色、阴影色、描边识别关键词等设置，并可自定义进度文本的命名规则。

v0.7.0

  • 带 Z 轴旋转的节点现在能正确导出：旋转节点作为独立组件提取，旋转效果保留在组件上，不再丢失或重复旋转。

v0.6.0

  • 新增「尺寸纳入去重指纹」开关：开启后，结构相同但尺寸不同的组件可以分别导出，互不合并。

  • 优化子节点命名规则，修复背景图与状态图标命名冲突的问题。

  • 修复嵌套组件、遮罩子项的尺寸与坐标偶尔异常的问题。

  • 修复列表开启自动尺寸时子项关联规则异常的问题。

v0.5.0

  • 导出配置改为保存在项目内（团队可共享、不影响其他项目）。

  • 新增文本描边/阴影导出，并补充描边宽度、描边色、阴影色、描边识别关键词等设置。

  • 修复文本字体颜色（含半透明）偶尔丢失的问题。

  • 优化按钮背景图/图标命名规则，完善 Toggle 选中图标导出。

  • 列表判定更一致；子组件坐标自动归零框定。

  • 多次导出同一 Prefab 时组件 ID 保持稳定。

v0.4.0

  • 新增组件去重编辑器：可合并重复组件、指定组件类型。

  • 新增类型标记车道（Prefab / Json）与自动标注开关。

  • 运行时自动检测 TextMeshPro 与 Legacy Text。

  • 支持公共包提取，跨包共享资源自动归并。

  • 嵌套 Prefab 作为独立组件提取并跨实例复用。

v0.3.0

  • 完善列表子组件提取与排重。

  • 完善 Slider / ScrollBar / Dropdown / InputField 交互组件导出。

v0.2.0

  • 基础 UGUI → FairyGUI 结构映射。

  • Button / Toggle 状态与过渡效果导出。

v0.1.0

  • 初始版本，支持基础 Prefab 扫描与图片收集。

补充说明：

  • 本工具为 Unity 编辑器扩展，以编译后的程序集（DLL）形式分发，仅提供「UGUI Prefab → FairyGUI 工程」的转换能力，不包含任何演示用界面素材。

  • 导出产物需在 FairyGUI 编辑器中按需手工微调（动画、事件、自定义 Shader、粒子等不在自动转换范围内）；工具不保证 100% 零修改即可直接上线。

  • 售出后如遇到使用问题，可通过上方「联系作者」中的渠道反馈，作者提供使用指导，但不对已自行修改后的工程结果做保证。