UGUI → FairyGUI 一键转换工具
一、简介
UGUI_to_FairyGUI 是一个 Unity 编辑器扩展，把使用 UGUI（Unity UI / uGUI）搭建的 Prefab 批量转换为 FairyGUI 的工程结构（package.xml + component + image 等资源）。
转换在编辑器内离线完成，不需要运行游戏。导出的工程可以直接用 FairyGUI 编辑器打开继续编辑。导出后，建议以 FairyGUI 工程作为后续 UI 迭代的主工程，不再回头维护原始 UGUI Prefab。
目标用户：已经在 Unity 里用 UGUI 做好了界面，希望迁移到 FairyGUI、或想同时产出 FairyGUI 版本的项目。
版本：v0.8.0
说明：文档与商店页中用于演示的界面截图、宣传图，所使用的 UI 工程来自其他第三方 GUI 资源商店，并不包含在本项目中。本工具只提供「UGUI Prefab → FairyGUI 工程」的转换能力，不包含任何演示用的界面素材。二、背景
Unity Asset Store 上有大量现成的 UGUI 界面资源包（主菜单、弹窗、设置面板、道具列表等）。小游戏平台（微信小游戏、抖音小游戏等）普遍使用 FairyGUI 作为跨项目 UI 方案——它提供可视化编辑器、像素级精确布局、资源按需加载、低内存占用等优势。
两者之间存在一个现实缺口：Asset Store 上的 UGUI 资源包丰富且便宜，但 FairyGUI 不能直接使用 UGUI 的 Prefab。如果手动对照还原——打开 UGUI 界面、数间距、看对齐、配图片、写脚本——一个中等复杂度的界面往往要花数小时去拆解大量基础组件。本工具的作用，就是把这部分重复劳动自动化。
三、UGUI 与 FairyGUI 的架构差异
维度UGUIFairyGUI坐标系中心锚点，anchor/min/max 决定拉伸左上角绝对坐标，按像素定位资源管理Sprite 分散在各目录统一的 package.xml + 按包管理组件树Prefab 层级 + RectTransformXML displayList + <component> 引用图片九宫格Image.type = Sliced，依赖 Sprite Editor 的 9-slice 设置<image scale="9grid">，边距在 XML 中声明按钮Button 组件 + OnClick 事件<component extention="Button"> + 内置 transition列表ScrollRect + Content + GridLayoutGroup 手动搭建<list> + <item> + defaultItem 声明式滚动ScrollRect 组件<scrollbar>（水平/垂直）组件，或 overflow 属性变体多个 Prefab，手动维护一致性组件去重 + repName 替换，或 override 单独生成
理解这些差异有助于判断哪些东西能自动转、哪些需要手动调整。
四、本项目解决的问题
Unity UI 项目中的界面通常是复杂的树形 Prefab。列表（商店、背包、图鉴等）一般作为 Prefab 内部的一个子树，由 LayoutGroup（Horizontal / Vertical / Grid）组织，子项也包含在这棵 Prefab 树里，而不是预先拆分成独立的 Prefab 资产。要把这样的列表搬进 FairyGUI，传统做法是手动把每个子项拆成独立 Prefab、再搭成 <list>，工作量大且容易遗漏。
UGUI_to_FairyGUI 是一个 Unity Editor 插件，能将 Unity UGUI Prefab 一键导出为 FairyGUI 编辑器可识别的 XML 文件，自动完成坐标系转换、资源映射、组件类型识别、交互定义迁移等基础层的映射工作。
重要：UGUI 和 FairyGUI 是两套架构迥异的 UI 系统。本工具解决的是静态结构 + 资源 + 基础交互的自动化迁移，无法覆盖动画、特效、遮罩、粒子、自定义脚本等系统级差异——这些部分仍需在 FairyGUI 编辑器中手工处理。工具产出的 XML 可直接在 FairyGUI 编辑器中打开修改，把它当作「省去重建骨架」的起步，而不是最终成品。五、核心能力
本工具具备以下核心能力：
- 一键导出：选择 Prefab 目录 → 选择输出目录 → 生成完整的 FairyGUI 工程（组件 XML、package.xml、.fairy 文件）。
- 全量组件映射：Image（Simple/Sliced/Filled）、Text/TMP、Button、Toggle、Slider、ScrollBar、ScrollRect、InputField、Dropdown、LayoutGroup（TMP 运行时自动检测，无需预装）。
- 按钮过渡效果保留：None/Animation → downEffect="scale"、ColorTint → controller + gearColor 六态颜色、SpriteSwap → controller + gearIcon 多态图标，完整映射为 FairyGUI 的 controller/gear 体系。
- 按钮命名约定：targetGraphic 对应的独立 Image 改名为 bg，状态图标节点保持 icon；icon 优先、bg 非必须、icon 与 bg 不会是同一对象。
- Toggle 选中图标：selectedIcon 取自 Toggle 的 graphic（checkmark），数据驱动。
- 引用组件覆写：dedup 重复项通过 <component> 引用 rep 组件时，title/icon/titleColor/titleFontSize 自动作为 <Button> 子节点传递到引用元素上。
- 九宫格保留：UGUI Image.Sliced → FGUI scale="9grid"，边距自动计算。
- 跨包图片共享优化：开启公共包后，被多个包引用的 Sprite 自动归入 Common/ 共享包，避免冗余。
- 嵌套 Prefab：与 Button / Slider 等一样视为组件边界，递归提取为独立组件，父组件原位置只留 <component src> 引用；同一嵌套 Prefab 在多处出现只生成一份定义，跨实例共享去重。
- 组件去重：分析所有 Prefab 的结构哈希，相同结构只导出一次，差异项通过 override 单独生成变体。
- List 子项自动提取：自动识别 Grid / Horizontal / Vertical LayoutGroup 列表，将层级下平铺的子节点提取为独立组件，生成 <list> 的 defaultItem 和 <item>，无需手动拆分 Prefab。嵌套 list 作为子项时不再误赋 Button 扩展。
- 组件类型配置：支持通过正则规则指定组件类型（Button/Label/Slider/ScrollBar/ComboBox），也可在去重编辑器或 Prefab 上手动调整。
- Prefab 重名修复：自动修复同级同名 GameObject（FairyGUI 要求名称唯一），避免导出阻塞。
- 确定性 ID 生成：所有组件 ID 基于名称的确定性哈希，多次导出同一预制的 ID 一致。
- Skip 规则：通过正则规则跳过不需要导出的 Prefab（如 Fx_ 开头的特效）。
- 文本描边/阴影：TMP 文本按材质/着色器关键词识别描边，导出为 FairyGUI 描边/阴影；提供默认描边宽度、描边色、阴影色等设置。