xhgame_builder

Cocos Creator 资源扩展包构建与安装工具。支持打包、安装、卸载、备份与回滚工作流。

从 xhgame_ec_framework v1.5.0 分离为独立项目。

特性

• 构建与安装：按 setup.json 的 files 清单复制，ZIP 解压根目录智能选择
• 备份与回滚：卸载前生成 <code>.zip 与描述 JSON，回滚自动剥离顶级目录前缀
• 追加脚本：枚举/类属性追加（Factory/Table/GUI/Audio/Comp）
• 依赖校验：文件存在性、UUID 一致性（支持 replaceUuid）、组件安装依赖（同插件）

目录结构

src/
  Builder/          # 构建与安装工具代码
    AppendScript.ts
    BackupManager.ts
    Defined.ts
    LocalInstallManager.ts
    MetaManager.ts
    Util.ts
  Pack/             # 打包工具
    Pack.ts
  index.ts
extensions/         # 示例扩展资源包（*.setup.json 与 *.zip）
assets/             # 示例管理器与类型枚举文件（供追加脚本演示）
tests/              # 可运行测试用例

快速开始

安装依赖

bun install

运行测试

bun ./tests/run.test.mjs

工作流

打包（src/Pack/Pack.ts）

将项目 assets/.../<group>/<item> 复制到 extensions/<plugin>/packages/<group>/<item>，生成/更新 <group>/<item>.setup.json 的 files 清单供安装使用。

安装（src/Builder/LocalInstallManager.ts）

• 解压 ZIP 或使用同名目录作为源；仅复制 setup.json.files 中列出的相对路径
• 依赖校验：文件存在性、UUID 一致性（支持 replaceUuid）、组件安装依赖（同插件）
• 追加脚本：枚举/类属性追加（Factory/Table/GUI/Audio/Comp）
• 记录安装信息：<plugin>-installInfo.json

LocalInstallManager.installComponent(group, componentCode)

卸载与备份（src/Builder/BackupManager.ts）

• 卸载前备份：生成 <componentCode>.zip 与 <componentCode>.setup.json
• ZIP 顶层目录为组件码；回滚自动剥离 ${componentCode}/ 前缀，恢复至 assets
• 幂等恢复追加脚本与安装信息

LocalInstallManager.uninstallComponent(group, componentCode)
BackupManager.rollback(group, componentCode)

约定与路径

• 项目根查找：向上查找存在的 extensions 目录（Creator 环境使用 Editor.Project.path）
• 资源根：assets
• 扩展包目录：extensions/<plugin>/packages/<group>
• 备份目录：extensions/<plugin>/backups/<projectName>/<group>
• 安装信息：/<plugin>-installInfo.json

构建

npm run build

许可证

MIT