# creator2fgui > Cocos Creator 2.4.x Prefab 界面一键迁移为 FairyGUI 工程，省去手动对照重建 UI 骨架的全部重复劳动。 Cocos Creator 与 FairyGUI 是两套架构迥异的 UI 系统。本插件负责「Cocos Prefab → scene_extract.json 契约」的提取，再配合随附的 **Cocos2FairyGUI** 转换器完成「契约 → FairyGUI 工程」的生成。整个流程在 Cocos 编辑器内**离线完成**，不需要运行游戏；导出的工程可以直接用 FairyGUI 编辑器（CocosCreator 类型）打开继续编辑。导出后，建议以 **FairyGUI 工程作为后续 UI 迭代的主工程**，不再回头维护原始 Cocos Prefab。 **适用对象**：已经在 Cocos Creator 2.4.x（实测 2.4.15+）里用 Prefab 搭建了界面，希望迁移到 FairyGUI、或想同时产出 FairyGUI 版本的项目。 --- ## 目录 - [一、它解决什么问题](#一它解决什么问题) - [二、安装与卸载](#二安装与卸载) - [三、快速上手（4 步）](#三快速上手4步) - [四、导出设置说明](#四导出设置说明) - [五、常见问题（FAQ）](#五常见问题faq) - [六、代码结构与实现原理](#六代码结构与实现原理) - [七、组件映射一览](#七组件映射一览) - [八、联系作者](#八联系作者) - [九、更新声明](#九更新声明) - [十、购买须知](#十购买须知) --- ## 一、它解决什么问题 **痛点**：中小团队常需要参考其他游戏项目的 UI 设计来快速起步，而 Cocos Creator的 Prefab 结构与 FairyGUI 组件体系差异巨大，手动逐个重建 UI 骨架工作量大、易漏项、还容易在坐标系/旋转/缩放上踩坑。本插件把参考项目的界面结构一键提取、重新组织为自己的 FairyGUI 工程，大幅提升二次开发的起点效率；尤其对 **IAA（广告变现）小游戏**而言，界面代码在项目中占了很大比例，能快速复用与重构 UI 骨架，也有助于提高小游戏的过审几率。 **一句话定位**：工具解决的是**静态结构 + 资源 + 基础交互**的自动化迁移。动画、特效、遮罩、粒子、自定义脚本等系统级差异仍需在 FairyGUI 编辑器中手工处理。把它当作「省去重建骨架」的起步，而非开箱即用的成品。 ### 核心能力 - **结构自动还原**：商店、背包、图鉴这类列表通常只是 Prefab 内部的一棵子树，由 `cc.Layout` 组织、子项也埋在树里。传统做法要手动把每个子项拆成独立组件、再搭成 ``，量大且易漏。本插件在提取阶段就**递归扁平化**，自动把 list 子项、交互组件抽成独立组件，原位置只留引用。 - **坐标零偏差**：Cocos 的 Y 轴向上 / FGUI 的 Y 轴向下、旋转方向、锚点（pivot）、缩放中心——这些坐标系差异由插件在提取期就换算好，导出结果与 Cocos 里的视觉位置、旋转、缩放**一一对上**。 - **资源自动归位**：图片按 `.meta` 的 uuid 映射自动收集拷贝，图集子图（plist）连同裁剪信息与九宫格边距一并带出，无需手动切图。 - **确定性产物**：组件 / 资源 ID 基于名称确定性生成，多次导出同一 Prefab 结果稳定，便于版本对比与团队协作。 - **全量组件映射**：见[第七节组件映射一览](#七组件映射一览)。 - **List 子项自动提取**：自动识别 Grid / Horizontal / Vertical 的 `cc.Layout` 列表，平铺子节点抽成独立组件并生成 `` 的 `defaultItem` 与 ``。 - **交互组件边界提取**：Button / Slider / Toggle / ScrollBar / ProgressBar / EditBox 作为组件边界递归抽成独立组件，父级原位置只留 `` 引用；同一结构多处出现按指纹去重。 - **Radial 填充 → 环形进度条**：`cc.Sprite` 的 Filled + Radial 自动转为 FGUI ProgressBar，Cocos 里常见的圆形冷却/进度表现一键迁过来。 - **Widget 对齐 → Relation**：`cc.Widget` 的对齐约束提取为契约，供转换器生成 FGUI 的 relation，而非写死绝对坐标。 --- ## 二、安装与卸载 ### 安装（二选一） **方式 A：复制目录（推荐正式使用）** 1. 把 `creator2fgui` 整个目录复制到目标 Cocos 项目的 `packages/` 目录下； 2. 重启 Cocos Creator（或执行「开发者 → 刷新项目」）。 **方式 B：junction 链接（开发期推荐，源码改动即时同步）** ```powershell mklink /J "\packages\creator2fgui" "<本插件绝对路径>" ``` > 插件随附转换器 `Cocos2FairyGUI.exe`（分发在 `packages/creator2fgui/tools/`），为 self-contained 单文件，**免装 .NET**。 ### 环境要求 | 项目 | 要求 | |---|---| | Cocos Creator | **2.4.15+**（同分支 2.4.x 均可） | | FairyGUI 编辑器 | 需安装，用于打开导出工程做后续编辑（工程类型 `CocosCreator`） | | .NET 运行时 | 不需要（转换器是 self-contained 单文件） | ### 卸载删除 Cocos 项目 `packages/` 下的 `creator2fgui` 目录即可（junction 方式先删链接再删源目录）。 --- ## 三、快速上手（4 步） > 全程在 Cocos 编辑器内完成，无需运行游戏。 ### 第 1 步：整理好要转换的 Prefab 把要转换的 Cocos Prefab 放到 `assets/` 下的 UI 目录（如 `assets/UI/`），并确保它们引用的图片也在 `assets/` 下可访问。**建议**：一个界面一个 Prefab，命名清晰。 ### 第 2 步：打开插件面板并确认设置在 Cocos 菜单 **扩展 → Cocos2FairyGUI**，打开导出面板。一般无需改动，直接使用默认设置即可；如需自定义，见[第四节导出设置说明](#四导出设置说明)。 ### 第 3 步：一键导出点击面板底部 **「保存并导出」** 按钮。插件会自动完成： ``` 扫描 Prefab → 解析节点树 → 扁平化抽取(list/交互组件) → 拷贝图片资源 → 写出 scene_extract.json → 调用转换器生成 FairyGUI 工程 ``` 完成后，控制台会打印输出路径。 ### 第 4 步：在 FairyGUI 编辑器中打开工程用 FairyGUI 编辑器打开 `<项目根>/out/cocos_fgui`（FairyGUI 工程文件是 `.fairy`）。工程布局如下： ``` out/cocos_fgui/ ├── <工程名>.fairy # FairyGUI 工程文件（type=CocosCreator） ├── assets/ │ └── <包名>/ │ ├── package.xml # 包定义（组件 + 图片声明） │ ├── components/*.xml # 组件 XML │ └── images/*.png # 图片资源 └── settings/ # 工程设置 ``` 打开后即可看到与 Cocos 里一致的界面骨架，接下来只需按需微调动画、事件等即可。 --- ## 四、导出设置说明在面板中可以调整以下设置： | 设置项 | 默认值 | 说明 | |---|---|---| | `outDir` | `out/cocos_extract` | scene_extract.json 输出目录 | | `prefabRootDir` | 留空 | 指定扫描的 Prefab 根目录；留空自动扫描 UI 目录 | | `minListChildCount` | `3` | 子节点数达到该值才判定为 list | | `setRootToZero` | 开 | 抽取子组件时坐标归零并框定内容包围盒 | | 变体合并 | 关 | 相同结构的组件按指纹去重合并 | > 一般场景用默认值即可。若导出结果里 list 识别不对，可调整 `minListChildCount`。 --- ## 五、常见问题（FAQ） **Q1：导出后没有生成 FairyGUI 工程？** 检查 `packages/creator2fgui/tools/Cocos2FairyGUI.exe` 是否存在（被 .gitignore 忽略，需重新构建）；缺失时插件仍会产出 `scene_extract.json`，只是跳过工程生成。可手动用命令行转换，见[第六节](#六代码结构与实现原理)。 **Q2：导出结果里某些列表没被识别成 list？** 调大/调小 `minListChildCount`，或确认该列表是否用 `cc.Layout` 组织。 **Q3：界面位置/旋转和 Cocos 里不一样？** 检查是否用了非标准锚点 + 旋转/缩放组合；一般默认导出已做坐标换算，遇到特例请在 FairyGUI 编辑器中手动校正，并反馈给我们以便改进。 **Q4：能迁移动画/特效/粒子吗？** 不能。工具只迁移静态结构 + 资源 + 基础交互，动画、特效、粒子、自定义脚本需在 FairyGUI 编辑器中手工重建。 --- ## 六、代码结构与实现原理 ### 数据流 ``` Cocos .prefab (json) │ parsePrefab(): 反序列化对象池 → 节点树(cc.Node 挂 components) ▼ 节点树 + cc.SpriteFrame meta │ toContractNode(): 逐节点提取 → scene_extract 契约(JSON) ▼ scene_extract.json ──┬── 转换器(生成 FairyGUI 工程) │ │ GenerateComponent(): 契约 → components/*.xml │ │ GeneratePackage(): package.xml / images │ └── (也可直接供其他工具消费，纯 JSON 契约) ``` ### 插件端（JS，`lib/`） | 模块 | 职责 | |---|---| | `prefab-parser.js` | 把 `.prefab` 的对象池反序列化成一棵**节点树**：解析 `cc.Node` 的层级、`cc.RectTransform`（contentSize / anchorPoint）、`cc.Node` 的 `trs`（位置/旋转/缩放）、以及各组件挂载关系。 | | `component-extractor.js` | 核心提取器：遍历节点树，把每个节点转成**契约对象**。负责 `cc.Sprite`→`image`、`cc.Label`/`cc.RichText`→`text`、交互组件→`button`/`slider`/`toggle` 等；同时做**坐标系换算**（Y 翻转、旋转取负、缩放烘焙进尺寸）、读取组件 `_enabled`（禁用→不可见）。 | | `sprite-resolver.js` | 资源解析：通过 `.meta` 的 uuid 建立映射，把 `SpriteFrame` 的 uuid 解析成图片源路径；支持**多扫描根**（项目 assets + Cocos 引擎内置资源目录）；图集子图（plist）登记大图 uuid。 | | `flattener.js` | 递归扁平化：把埋在树里的 list 子项、交互组件抽成**独立组件**，原位置留 `` 引用；同结构组件按**指纹**去重复用；把抽出的子组件根坐标**归零并框定内容包围盒**。 | ### 关键设计 - **纯 Node 解析，可脱离编辑器单测**：提取逻辑不依赖 Cocos 运行时 `cc`，直接用 Node 就能跑 `lib` 模块（`node lib/prefab-parser.js`）。 - **坐标换算**：Cocos 局部坐标（相对父锚点）经 Y 翻转、旋转取负、缩放烘焙进尺寸（localScale 归 1），避免 FGUI 双重放大。 - **确定性 ID**：组件 / 资源 ID 基于名称确定性生成，多次导出稳定。 - **组件级 `_enabled`**：`cc.Sprite`/`cc.Label`/`cc.RichText` 的 `_enabled=false` 会被标记，转换器输出 `visible="false"`。 - **带 pivot 的元素自动配 `anchor="true"`**：FGUI 中设了非默认 pivot 必须同时 anchor=true，否则 pivot 坐标被错误解释。 ### 转换器（C#，`src/`） `FguiGenerator.cs` 读取 `scene_extract.json`，生成 FairyGUI 工程：组件 XML（`components/*.xml`）、包定义（`package.xml`）、图片拷贝（`images/*.png`）、工程设置（`settings/`）。转换器为 **.NET 8**，随插件分发为 **self-contained 单文件 exe**（`tools/Cocos2FairyGUI.exe`），可脱离 Cocos 独立运行： ```powershell # 命令行转换：Cocos2FairyGUI.Cli <输出目录> packages\creator2fgui\tools\Cocos2FairyGUI.exe "out\cocos_extract\scene_extract.json" "out\cocos_fgui" ``` --- ## 七、组件映射一览 | Cocos 2.x 组件 | 映射到 FGUI 契约 | |---|---| | `cc.Node`（contentSize / anchorPoint / trs） | `rect` + `transform` | | `cc.Sprite` | `image`（resourceKey = 图片路径，含 Sliced / Tiled / Filled 类型与九宫格边距）；**Filled + Radial 填充自动转为 ProgressBar** | | `cc.Label` | `text`（字号、对齐、颜色、行距） | | `cc.Button` | `button`（interactable + transition + 四态颜色 / 缩放） | | `cc.Slider` | `slider` | | `cc.Toggle` | `toggle`（含选中态） | | `cc.ScrollBar` | `scrollbar` | | `cc.ProgressBar` | `progressbar` | | `cc.EditBox` | `inputField`（文本 / 占位符 / 最大长度） | | `cc.Layout` | `layoutGroup`（Horizontal / Vertical / Grid，间距 / 内边距 / 列数 / 单元格尺寸） | | `cc.Mask` | `hasRectMask2D` | | `cc.ScrollView` | `scrollRect`（横向 / 纵向 / 惯性） | | `cc.Widget` | `widget`（对齐约束，供生成 FGUI relation） | ### 工程目录结构 ``` packages/creator2fgui/ ├── package.json # 插件描述 + 菜单 ├── main.js # 主入口：扫描 Prefab + 汇总输出 + 调用转换器 ├── settings.js # 导出设置（outDir / prefabRootDir / 扁平化开关 / 变体合并） ├── panel.js # 设置面板 UI ├── i18n/ # 中英文菜单文案（zh.js / en.js） ├── lib/ │ ├── prefab-parser.js # .prefab 对象池解析 → 节点树 │ ├── component-extractor.js # 节点树 → scene_extract 契约 + 坐标换算 │ ├── sprite-resolver.js # SpriteFrame uuid → 图片路径（扫描 .meta） │ └── flattener.js # 递归扁平化：抽 list 子项 / 交互组件为独立组件 └── tools/ └── Cocos2FairyGUI.exe # 随插件分发的转换器（self-contained 单文件） ``` --- ## 八、联系作者作者邮箱：support@skylad.com QQ：690636693 论坛 Store 专区用户反馈集中帖链接：[论坛反馈](https://forum.cocos.org/t/topic/176989) --- ## 九、更新声明 - 1.0.1 - **修复「目标 Prefab 目录 / 引擎资源根」浏览按钮无法选择目录的问题**。 - 目录选择对话框现在可正常弹出并自动回填路径，无需手动粘贴目录。 - 优化：目录浏览选中后即时写入设置文件，导出即用新值。 - 设计分辨率：面板增加设置自定义设计分辨率的功能。 - 1.0.0 - 首版上架：Cocos Creator 2.4.x Prefab → FairyGUI 工程一键迁移。 --- ## 购买须知本产品为付费虚拟商品，一经购买成功概不退款，请支付前谨慎确认购买内容。补充说明： - 本工具为 Cocos Creator 编辑器扩展，以脚本 + 随附转换器（exe）形式分发，仅提供「Cocos Creator Prefab → FairyGUI 工程」的转换能力，不包含任何演示用界面素材。 - 导出产物需在 FairyGUI 编辑器中按需手工微调（动画、事件、自定义 Shader、粒子等不在自动转换范围内）；工具不保证 100% 零修改即可直接上线。 - 售出后如遇到使用问题，可通过上方「联系作者」中的渠道反馈，作者提供使用指导，但不对已自行修改后的工程结果做保证。