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 版本的项目。
目录
一、它解决什么问题
痛点：中小团队常需要参考其他游戏项目的 UI 设计来快速起步，而 Cocos Creator的 Prefab 结构与 FairyGUI 组件体系差异巨大，手动逐个重建 UI 骨架工作量大、易漏项、还容易在坐标系/旋转/缩放上踩坑。
本插件把参考项目的界面结构一键提取、重新组织为自己的 FairyGUI 工程，大幅提升二次开发的起点效率；尤其对 IAA（广告变现）小游戏而言，界面代码在项目中占了很大比例，能快速复用与重构 UI 骨架，也有助于提高小游戏的过审几率。
一句话定位：工具解决的是静态结构 + 资源 + 基础交互的自动化迁移。动画、特效、遮罩、粒子、自定义脚本等系统级差异仍需在 FairyGUI 编辑器中手工处理。把它当作「省去重建骨架」的起步，而非开箱即用的成品。
核心能力
-
结构自动还原：商店、背包、图鉴这类列表通常只是 Prefab 内部的一棵子树，由
cc.Layout组织、子项也埋在树里。传统做法要手动把每个子项拆成独立组件、再搭成<list>，量大且易漏。本插件在提取阶段就递归扁平化，自动把 list 子项、交互组件抽成独立组件，原位置只留引用。 -
坐标零偏差：Cocos 的 Y 轴向上 / FGUI 的 Y 轴向下、旋转方向、锚点（pivot）、缩放中心——这些坐标系差异由插件在提取期就换算好，导出结果与 Cocos 里的视觉位置、旋转、缩放一一对上。
-
资源自动归位：图片按
.meta的 uuid 映射自动收集拷贝，图集子图（plist）连同裁剪信息与九宫格边距一并带出，无需手动切图。 -
确定性产物：组件 / 资源 ID 基于名称确定性生成，多次导出同一 Prefab 结果稳定，便于版本对比与团队协作。
-
全量组件映射：见第七节组件映射一览。
-
List 子项自动提取：自动识别 Grid / Horizontal / Vertical 的
cc.Layout列表，平铺子节点抽成独立组件并生成<list>的defaultItem与<item>。 -
交互组件边界提取：Button / Slider / Toggle / ScrollBar / ProgressBar / EditBox 作为组件边界递归抽成独立组件，父级原位置只留
<component src>引用；同一结构多处出现按指纹去重。 -
Radial 填充 → 环形进度条：
cc.Sprite的 Filled + Radial 自动转为 FGUI ProgressBar，Cocos 里常见的圆形冷却/进度表现一键迁过来。 -
Widget 对齐 → Relation：
cc.Widget的对齐约束提取为契约，供转换器生成 FGUI 的 relation，而非写死绝对坐标。
二、安装与卸载
安装（二选一）
方式 A：复制目录（推荐正式使用）
-
把
creator2fgui整个目录复制到目标 Cocos 项目的packages/目录下； -
重启 Cocos Creator（或执行「开发者 → 刷新项目」）。
方式 B：junction 链接（开发期推荐，源码改动即时同步）
mklink /J "<Cocos项目>\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 子项、交互组件抽成独立组件，原位置留 <component src> 引用；同结构组件按指纹去重复用；把抽出的子组件根坐标归零并框定内容包围盒。 |
关键设计
-
纯 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 独立运行：
# 命令行转换：Cocos2FairyGUI.Cli <scene_extract.json> <输出目录>
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
九、更新声明
-
1.0.0
- 首版上架：Cocos Creator 2.4.x Prefab → FairyGUI 工程一键迁移。
十、购买须知
本产品为付费虚拟商品，一经购买成功概不退款，请支付前谨慎确认购买内容。