diff --git a/.gitignore b/.gitignore index bb864160..80c18438 100644 --- a/.gitignore +++ b/.gitignore @@ -34,3 +34,5 @@ Thumbs.db #///////////////////////////////////////////////////////////////////////////// temp + +.env diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..e08d3abd --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,73 @@ +## 分支结构 + +- `master` 分支存放项目文档、演示项目的源码和其它文件 +- `v1.0.0-v2.4.9` 类似这种格式的分支存放引擎源码与类型提示文件 + +## 目录结构 + +在源码分支下： + +- `engine` JavaScript 引擎 +- `jsb-adapter` 原生平台 JSB 适配器 +- `adapters` 小游戏平台适配器 +- `cocos2d-x` C++ 原生平台引擎 +- `creator-sp.d.ts` 引擎 TypeScript 类型提示 + +在 `master` 分支下： + +- `src` 只留一份指向源码分支的说明文档 +- `extension` 支持性引擎扩展 +- `docs` 存放着文档网站源码，使用 Docusaurus 开发 +- `demo` 存放着 Cocos Creator 演示项目源码 +- `scripts` 工具脚本 +- `media` 媒体素材 + +## 开发流程 + +### 适配新引擎版本 + +- 以旧版本分支为基础创建新分支，比如旧版本 `v1.2.0-v2.4.9` 适配到引擎 `v2.4.13`，则命名为 `v1.2.0-v2.4.13` +- 分别打开新旧引擎的各个源码目录，使用对比工具逐个进行比对，将改动同步到社区版引擎 +- 参考以往的提交记录填写描述并提交后即可发布新版本 + +### 本地开发 + +- 在演示项目扩展目录建立软链接，指向当前开发中的扩展目录 +- 在各个平台打包运行进行测试 + +## 自动发布脚本 + +- 建议使用脚本前，先大概了解手动发布流程的步骤 +- 前往 `scripts` 目录并执行 `npm i` 安装依赖 +- 新建 `.env` 文件，填写 `GITHUB_TOKEN`（如果还需发布付费扩展，需填写 ssh 的 `HOST` `PORT` `USERNAME` `PASSWORD`） +- 返回根目录，执行 `node --env-file=.env scripts/index.js` 启动发布脚本 +- 按照脚本的提示进行发布 + +## 手动发布流程 + +### 更新版本号 + +- 修改 `engine`、`jsb-adapter`、`cocos2d-x` 根目录的 `VERSION.md` 文件。 +- 修改源码目录的 `README.md` 文件。 +- 修改 `sp.js` 的 `version` 属性。 +- 修改 `extension` 的 `package.json` 文件中的 `version` 属性。 + +### 准备压缩包 + +- 删除 `cocos2d-x` 目录中的 `build/build` 目录，没有用处。 +- 删除 `engine` 目录中的 `node_modules` 目录，可能导致解压失败。 +- 编译 JavaScript 引擎。 +- 编译原生模拟器。 +- 将几个源码目录、类型提示文件、`enhance-kit-support` 放到压缩包根目录内。 + +### 更新 DEMO + +- 编译 `web-mobile` 和 `web-desktop` 项目。 +- 将这两个项目目录放在 `docs/static/demo` 相应版本号的目录中。 +- 查找仓库内所有链接并更新至当前版本号。 + +### 正式发布 + +- 上传压缩包到 Github 的 Release。 +- 在 Github Release 中填写更新日志。 +- 将文档分出当前版本，并发布新版本文档。 diff --git a/README-DEV.md b/README-DEV.md deleted file mode 100644 index 9beb85fc..00000000 --- a/README-DEV.md +++ /dev/null @@ -1,61 +0,0 @@ -## 项目结构 - -- `master` 分支存放项目文档、演示项目的源码和其它文件。 -- `v1.0.0-v2.4.9` 类似这种格式的分支存放引擎源码与类型提示文件。 - -## 目录结构 - -在源码分支下： - -- `engine` JavaScript 引擎 -- `jsb-adapter` 原生平台 JSB 适配器 -- `cocos2d-x` C++ 原生平台引擎 -- `creator-sp.d.ts` 引擎 TypeScript 类型提示 - -在 `master` 分支下： - -- `src` 只留一份指向源码分支的说明文档 -- `extension` 引擎扩展 -- `docs` 存放着文档网站源码，使用 Docusaurus 开发。 -- `demo` 存放着 Cocos Creator 演示项目源码。 - -## 发布新版本 - -### 更新版本号 - -1. 修改 `engine`、`jsb-adapter`、`cocos2d-x` 根目录的 `VERSION.md` 文件。 -2. 修改 `sp.js` 的 `version` 属性。 -3. 修改 `extension` 的 `package.json` 文件中的 `version` 属性。 -4. 修改文档中相关的版本号。 - -### 更新 DEMO - -1.编译 `web-mobile` 和 `web-desktop` 项目。 -2.将这两个项目目录放在名称是当前版本号的目录中，然后放在 `docs/static/demo` 中。 -3.修改文档中相关的演示项目路径。 - -### 准备压缩包 - -1.将对 engine 的改动整合到 Git Patch，然后将 Patch 按相应的引擎目录放置在 `patches` 目录并放在压缩包根目录内。 -2.删除 `cocos2d-x` 目录中的 `build/build` 目录，没有用处，删除 `engine` 目录中的 `node_modules` 目录，可能导致解压失败。 -3.编译 JavaScript 引擎和原生模拟器，再将三个引擎目录放到压缩包根目录内，包括类型提示文件。 -4.将 `enhance-kit-support` 目录放在压缩包根目录内。 -5.更新文档的更新日志。 - -### 发布压缩包 - -1.上传压缩包到 Github 的 Release，修改文档内所有下载地址。 -2.将文档分出当前版本，并发布新版本文档。 - -### 同步到 Gitee - -1.同步仓库 -2.同步 Gitee Pages - -## 版本计划 - -- 原生平台上支持 Spine 与其它组件合批 -- 动态图集支持预乘纹理 -- 补充原理文档 -- Char 模式因为 bleed 问题只能复用完全相同宽高的区域，试着增加一个选项，能够先用空纹理覆盖，之所以做选项是不知道性能消耗大不大 -- 新增静态合批：在一个节点树的根节点挂上一个组件，该组件会快照这个节点树并显示为一张图片，然后只接管渲染，不影响其它逻辑，也可以选择直接删除掉被快照的所有节点 diff --git a/README.md b/README.md index fdeaa396..dcd8d06e 100644 --- a/README.md +++ b/README.md @@ -1,150 +1,137 @@ # Cocos Enhance Kit -![logo](/docs/static/img/logo2.png) +![logo](/media/logo-round@0.25x.png) -这是一个提供 Cocos Creator 引擎特性增强、修复与优化的**开源非官方增强包**。 +这是 [Cocos Creator](https://www.cocos.com/creator) v2.x 社区分叉版本，**提供了大量的新特性、性能改进与修复**。 -该项目使用自定义引擎的方式在符合原始引擎架构设计的基础上为 Cocos Creator 引擎加入新的特性、修复已知问题以及性能优化。 +未来将继续秉持着**完全开源、完全兼容**的理念提供新特性、优化与修复。 -正因为如此，增强包中的大部分特性能像升级引擎版本一样无需改动项目代码即可生效。 +非常欢迎，并且希望你能和我们一起来完善这个项目！ -
+## 主要特性 -> 项目的起源 -> ->2021 年 2 月，Cocos 发布 Cocos Creator 3.0，之后不会再开发 2.x 版本的新特性，但 2.x 在一些方面还并不完善，所以这个非官方的引擎“魔改”合集应运而生。 -> ->给项目取名的时候想到相似的事情发生在 2014 年 4 月，官方停止了对 Windows XP 的维护，之后 Harkaz 发布了一个非官方增强包 Service Pack 4 (SP4)。 -> ->受到这个命名的启发，遂想将项目取名为 Service Pack。 -> ->但是这个名字有点怪怪的，最后在 麒麟子(Kylins) 的帮助下，我们为项目想到了一个更好的名字，Enhance Kit，再次感谢 麒麟子(Kylins)。 +### 完全兼容 -
+社区版的现在乃至未来都会做到以下几点： - +- 兼容旧项目，无需改动项目代码即可切换到社区版。 +- 不会对项目本身进行任何改动，随时可以切换回官方版。 +- 任何特性都可以选择性开启，保证项目的可控性。 - +并且全平台兼容！ -- [重要特性](#重要特性) -- [功能演示](#功能演示) -- [使用方法](#使用方法) -- [更新日志](#更新日志) - - [Enhance Kit v1.2.0](#enhance-kit-v120) - - [Enhance Kit v1.1.0](#enhance-kit-v110) - - [Enhance Kit v1.0.0](#enhance-kit-v100) -- [贡献指南](#贡献指南) -- [常见问题](#常见问题) - - [为什么要直接修改引擎？](#为什么要直接修改引擎) - - [启动 Cocos Creator 报 Error: Can not parse this input:undefined 错误](#启动-cocos-creator-报-error-can-not-parse-this-inputundefined-错误) - - [原生平台或模拟器报错：Assertion failed: (_type == Type::String), function toString, file Value.cpp, line 496.](#原生平台或模拟器报错assertion-failed-_type--typestring-function-tostring-file-valuecpp-line-496) - - [使用模拟器预览时出现各种问题](#使用模拟器预览时出现各种问题) - - [Spine 组件出现 Uncaught TypeError: Cannot read property ‘load’ of null, location: src/cocos2d-jsb.b5158.js 等问题](#spine-组件出现-uncaught-typeerror-cannot-read-property-load-of-null-location-srccocos2d-jsbb5158js-等问题) +### 支持多纹理渲染 - +在之前，每个相邻的节点使用不同的纹理渲染时会打断合批，我们一般通过调节节点顺序、合并图集的方式来避免这个问题。 -## 重要特性 +但是实际应用起来情况复杂，且操作麻烦，无法优化到极致，而较高的 DrawCall 数量会导致设备性能下降、发热的问题。 -- **支持多纹理渲染**（多纹理材质、多纹理合批） - ![demo1](/docs/static/demo-imgs/demo1.png) +现在，由于支持了多纹理渲染，可允许多达 8 张不同纹理进行渲染时也不会打断合批，**在最坏的情况下，也能将项目的 DrawCall 数量减少至 1/8**！ -- **支持高 DPI 文本渲染**（Label、RichText 组件） - ![demo4](/docs/static/demo-imgs/demo4.png) +并且，该特性在使用动态合图时会自动启用，无需任何改动即可得到优化效果。 -- **重构动态合图**（支持自动多纹理合批、优化算法、复用废弃空间等特性） - ![demo2](/docs/static/demo-imgs/demo2.png) +![demo1](/docs/static/demo-imgs/demo1.png) -- **重构 Label 组件的 CHAR 缓存模式**（支持自动多纹理合批、多图集、复用废弃空间等特性） - ![demo3](/docs/static/demo-imgs/demo3.png) +### 支持高清文本渲染 -- **Spine 组件支持与其它组件合批、合入动态图集与 SpriteFrame 换装** - ![demo5](/docs/static/demo-imgs/demo5.png) +在之前，Cocos Creator 引擎默认以 1x 的分辨率渲染字体，所以有时候在某些 `Retina` 设备上会感觉到字体很模糊。 -## 功能演示 +由于引擎本身不支持对其进行调节，我们会通过将 Label 的 `fontSize` 放大一倍，然后将 `scale` 缩小一倍的方式解决字体渲染模糊的问题。 -[Web Desktop 演示项目](https://smallmain.gitee.io/cocos-enhance-kit/demo/v1.0.0/web-desktop/index.html) +现在，增加了高清文本渲染的支持，你只需要通过一句代码： -[Web Mobile 演示项目](https://smallmain.gitee.io/cocos-enhance-kit/demo/v1.0.0/web-mobile/index.html)（请将设备横屏） +```ts +cc.sp.labelRetinaScale = 2; +``` -> 增强包对引擎的改动完全开源，每个改动会带有原理说明文档，当你发现问题时请与我们进行反馈，如果你有兴致，可以默默帅气地提交一个 PR，帮助我们一起完善这个项目。 +即可调整引擎文本渲染的分辨率，获得高清的文本渲染效果。 + +![demo4](/docs/static/demo-imgs/demo4.png) + +### 动态合图增强 + +除了上面提到将动态合图支持了自动多纹理渲染之外，我们其实几乎重构了整个动态合图模块。 + +现在的动态合图即优化了算法，还**支持废弃空间复用**，这对于项目的性能优化空间的提升是巨大的。 + +并且，**Spine 现在也可以参与动态合图**了！ + +![demo2](/docs/static/demo-imgs/demo2.png) + +### Label 组件增强 + +Label 一直是项目优化的最难点，因为它完全不能和其它的渲染组件进行合批，甚至大部分情况下也不能和其它 Label 组件合批。 + +在之前，使用 `Bitmap` 模式可以加入动态合图，以达到合批的目的，但受引擎动态合图不能复用废弃空间的限制，导致项目越运行，可以动态合图的空间就越小，很容易就会将动态图集塞满，所以基本不会在实际的项目中使用。 + +`Char` 模式也有类似的问题，内部的字符纹理即不支持复用，还最高仅支持 1 张纹理，纹理很容易就被填满导致无法渲染文本，不会在实际项目中使用。 + +但是现在，Label 得到了以下重大的改进： + +- 重构后的动态合图支持复用，`Bitmap` 模式的使用不再受限！ +- `Char` 模式得到重构，**支持废弃空间复用，支持最多 8 张字符纹理，支持自动多纹理合批**！ +- RichText 也得到同样的所有改进，并且开放了自定义材质的设置。 + +![demo3](/docs/static/demo-imgs/demo3.png) + +### Spine 组件增强 + +除了 Label 之外，如果你的项目用到了 Spine 组件，那么它大概率会成为项目第二个优化难点。 + +现在，Spine 也得到了重大改进，**支持与其它组件合批，支持参与动态合图，还能无缝使用 SpriteFrame 进行换装**！ + +![demo5](/docs/static/demo-imgs/demo5.png) + +### TiledMap 组件优化 + +单个 TiledMap 组件可能存在多个 TiledLayer，启用 Culling 特性后，每个 Layer 都需要单独计算 Culling 数据。 + +现在在满足条件的情况下可以复用 Culling 数据，以减少项目 CPU 的性能消耗。 + +## 演示 + +[Web Desktop](https://smallmain.github.io/cocos-enhance-kit/demo/v1.0.0/web-desktop/index.html) + +[Web Mobile](https://smallmain.github.io/cocos-enhance-kit/demo/v1.0.0/web-mobile/index.html)（请将设备横屏） ## 使用方法 -请阅读文档的 [安装指南](https://smallmain.gitee.io/cocos-enhance-kit/docs/installation-guide/installation-intro) 与 [入门教程](https://smallmain.gitee.io/cocos-enhance-kit/docs/start-guide/start-guide-intro)。 +请阅读 [文档](https://smallmain.github.io/cocos-enhance-kit/docs/installation/installation-auto) 进行安装。 ## 更新日志 -### Enhance Kit v1.2.0 - -- **[新特性] cc.TiledLayer 支持复用 Culling 数据** -- [修复] 修复 MotionStreak 初始化报错的问题 -- [修复] 修复勾选延迟加载资源时资源不会加载的问题 - -### Enhance Kit v1.1.0 - -- **[新特性] 动态合图在符合条件的情况下会忽略 padding 将纹理加入动态图集** -- [修复] 修复动态图集 maxFrameSize 能设置为超出图集尺寸大小的问题 -- [修复] 修复 Spine 动态合图时未判断 attachment 是否存在 region 对象导致报错的问题 -- [修复] 修复 Android 平台打包出现 Implicit instantiation of undefined template 错误 - -### Enhance Kit v1.0.0 - -- **[新特性] 支持多纹理渲染** -- **[新特性] 重构动态图集，支持多个新特性** -- **[新特性] 重构 cc.Label 的 Char 缓存模式，支持多个新特性** -- **[新特性] 支持高 DPI 文本渲染** -- **[新特性] Spine 组件支持参与动态图集、与其它组件合批、使用 SpriteFrame 换装** -- [新特性] cc.Label、cc.RichText、cc.Sprite、cc.MotionStreak、Spine 组件支持使用多纹理材质，并支持自动切换材质机制 -- [新特性] cc.RichText 支持使用自定义材质 -- [修复] 直接修改 Effect 的属性不回导致其变体的 hash 值刷新 -- [修复] CHAR 缓存模式 hash 计算可能会有重复的问题 -- [调整] 默认禁用 Label 原生 TTF 渲染器 - -[点此](https://smallmain.gitee.io/cocos-enhance-kit/docs/update-log) 查看所有的更新日志。 +请前往 [Github Release](https://github.com/smallmain/cocos-enhance-kit/releases) 查看。 ## 贡献指南 -非常欢迎你能和我们一起来完善这个项目，请通过 Github 进行： - -- 如果你发现了问题请建立 `Issues` -- 如果你有好的想法，请进入 `Discussions` -- 如果你有新的代码提交，请建立 `Pull requests` - -**原则上你提交的任何修改都不能影响引擎原有功能，不允许删除引擎原有的特性，请认真思考代码设计。** +- 如果你有任何问题或者想法请建立新的 `Issues`，我们会尽自己所能帮助你！ +- 如果你有新的代码提交，请建立新的 `Pull requests` 以完成合并。 ## 常见问题 -### 为什么要直接修改引擎？ +**为什么要直接修改引擎？** -直接修改引擎可能是大部分人认为的下下策，比如我们常听到的： +官方对 2.x 版本已经停止了更新（仅做一些维护工作），修改引擎不会遇到在官方新版本发布后需要用大量时间去适配，或者特性冲突的问题。 -- 可以通过 “修改对象原型” 等编程技巧将改动做成一个插件脚本 -- 没接触过自定义引擎，不知道该如何使用 -- 已经修改过引擎了，不能直接进行标准安装，会覆盖原有的修改 +如果不自定义引擎，则无法兼容原生平台，即使不兼容，使用 Hack 的方式，某些特性的实现需要大量拷贝代码，包体会增大，可维护性会降低。 -以上问题我们都思考过，首先，现在引擎的 2.x 版本已经停止了更新（仅做一些维护工作），也就是说修改引擎不会遇到在官方新版本发布后需要用大量时间去适配的情况。 +最后，我们希望它接近 “原生” 的使用体验，就像只是一次引擎的无痛升级。 -其次，即使增强包的所有改动都能做成一个插件脚本，但无法兼容原生平台，并且一般都需要大量拷贝代码，包体会增大，可维护性会大幅降低。 +**启动 Cocos Creator 报 Error: Can not parse this input:undefined 错误** -最后，我们希望它接近 “原生” 的使用体验，就像引擎本来就有的功能一样，对于没有接触过自定义引擎的人，可以通过引擎扩展一键安装。 +你可能忘记安装配套的引擎扩展，所以没有找到社区版的内置资源，导致报错，请仔细阅读文档重新安装。 -对于已经修改过引擎的人，由于增强包提供的是 Git Patch，所以可以让你在原有的基础上轻松应用增强包的改动，你甚至可以只选取你想要的特性进行应用。 +**原生平台或模拟器报错：Assertion failed: (_type == Type::String), function toString, file Value.cpp, line 496.** -### 启动 Cocos Creator 报 Error: Can not parse this input:undefined 错误 +你可能没有替换引擎的 `jsb-adapter` 部分，或者说没有重启以使替换生效。 -这是你可能忘记安装配套的引擎扩展，所以没有找到增强包的内置资源导致的报错。 +并且原生平台需额外注意，升级后的首次构建可能需先删除原有的构建工程才会生效。 -### 原生平台或模拟器报错：Assertion failed: (_type == Type::String), function toString, file Value.cpp, line 496. +**使用模拟器预览时出现各种问题** -这是你没有替换引擎的 `jsb-adapter` 部分，或者说没有重启以生效。 +可能是因为模拟器没有重新编译导致的，请按照官方的 [引擎定制文档](https://docs.cocos.com/creator/2.4/manual/zh/advanced-topics/engine-customization.html#25-%E7%BC%96%E8%AF%91%E6%A8%A1%E6%8B%9F%E5%99%A8) 重新编译原生模拟器即可。 -注意：原生平台构建时可能需要先删除原有的 build 文件，替换操作才会生效。 - -### 使用模拟器预览时出现各种问题 - -可能是因为模拟器没有重新编译导致的，请按照官方的 [引擎定制文档](https://docs.cocos.com/creator/2.4/manual/zh/advanced-topics/engine-customization.html#25-%E7%BC%96%E8%AF%91%E6%A8%A1%E6%8B%9F%E5%99%A8) 重新编译模拟器即可。 - -### Spine 组件出现 Uncaught TypeError: Cannot read property ‘load’ of null, location: src/cocos2d-jsb.b5158.js 等问题 +**Spine 组件出现 Uncaught TypeError: Cannot read property ‘load’ of null, location: src/cocos2d-jsb.b5158.js 等问题** 这是引擎自身的问题，由于释放 Spine 资源，然后再次加载相同 Spine 资源时导致，具体请看： @@ -155,3 +142,12 @@ 1. 引擎已经有一个修复此问题的 PR，但还未合入，可自行合入：[PR #4307](https://github.com/cocos/engine-native/pull/4307) 2. 需要进行释放的 spine 资源，不让其参与动态合图（通过控制 Spine 组件的合图开关）。 3. 不释放需要参与动态合图的 spine 资源。 + +该问题已在 v2.4.13 版本修复，请升级社区版版本至 v2.0.0 以上。 + +## 支持我们 + +社区版的开发需要大量的工作来进行，你的支持是我们最大的动力： + +- 请给我们的项目仓库一个 [Star](https://github.com/smallmain/cocos-enhance-kit)！ +- 购买可有可无的 [一键安装扩展](https://store.cocos.com/app/detail/3824) 赞助我们！ diff --git a/demo/README.md b/demo/README.md index 919e43fe..952e6aec 100755 --- a/demo/README.md +++ b/demo/README.md @@ -1,9 +1,9 @@ # Cocos Enhance Kit Demo -这是对增强包所有特性做展示的 Cocos Creator 演示项目。 +用于展示社区版主要特性的演示项目。 ## 如何运行 -1. 将项目克隆下来之后，根据文档中的 [安装指南](https://smallmain.gitee.io/cocos-enhance-kit/docs/installation-guide/installation-intro) 安装增强包。 - -2. 重启编辑器后运行项目的 `main.fire` 场景。 +1. 克隆演示项目。 +2. 在项目中安装好社区版本引擎。 +3. 运行项目的 `main.fire` 场景。 diff --git a/docs/docs/best-practices/_category_.json b/docs/docs/best-practices/_category_.json new file mode 100644 index 00000000..abdcf804 --- /dev/null +++ b/docs/docs/best-practices/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "最佳实践", + "position": 3, + "collapsed": false +} diff --git a/docs/docs/start-guide/assets/changespine.png b/docs/docs/best-practices/assets/changespine.png similarity index 100% rename from docs/docs/start-guide/assets/changespine.png rename to docs/docs/best-practices/assets/changespine.png diff --git a/docs/docs/start-guide/assets/labelscaledemo.png b/docs/docs/best-practices/assets/labelscaledemo.png similarity index 100% rename from docs/docs/start-guide/assets/labelscaledemo.png rename to docs/docs/best-practices/assets/labelscaledemo.png diff --git a/docs/docs/start-guide/batcher-guide.md b/docs/docs/best-practices/batcher-guide.md similarity index 81% rename from docs/docs/start-guide/batcher-guide.md rename to docs/docs/best-practices/batcher-guide.md index 8e1ce5f4..fc07e084 100644 --- a/docs/docs/start-guide/batcher-guide.md +++ b/docs/docs/best-practices/batcher-guide.md @@ -3,45 +3,12 @@ sidebar_position: 1 description: "在游戏开发中享受不用关注 Draw Call 的快乐。" --- -# 新 UI 渲染批次合并指南 +# 提升项目性能 在官方文档的进阶主题中有一个 [UI 渲染批次合并指南](https://docs.cocos.com/creator/2.4/manual/zh/advanced-topics/ui-auto-batch.html)，批次合并一直是游戏开发中重要的优化手段，如果你未阅读过官方的指南，可以先阅读一遍。 当 **多纹理渲染**、**新动态图集** 等特性出现后，在进行批次合并时可以变得更加简单且自动化。 - - ---- -## 什么是多纹理渲染？ - -在以前的认识里，我们知道相邻的节点使用不同的纹理（Texture）会导致不能合并批次。 - -其根本原因是纹理是使用 uniform 变量传给着色器的，而需要合并批次的话不允许每次渲染都拥有不同的 uniform 变量值。 - -增强包实现的是先设置多个 uniform 变量，比如将 8 张纹理写入到 "texture1" "texture2" "texture3"... 的 8 个 uniform 变量中，然后在着色器里再判断应该在渲染时使用哪个 uniform 变量。 - -这样的话如果所有渲染都只用这 8 张纹理，就都能合并为 1 个批次。 - -这要求设备支持采样多个纹理，而在现代绝大多数设备中都至少支持采样 8 张纹理，所以这不是问题。 - -当然除了这种方法，还有另外几种进行多纹理合批的方法，例如 "Texture Array" 和 "Bindless"，但都有实用性与兼容性的问题。 - -:::info 提示 - -以这种方式实现的多纹理渲染并不是没有弊端的： - -因为会多传递一个顶点属性，并且需要在着色器中去判断该使用哪个纹理，导致**合并批次并不一定会提升性能**。 - -所以我们建议在多个档次设备中实际测试项目是否使用多纹理渲染的性能差距。 - -如果你对这种技术有所担心，可以看看这些： - -**PixiJS 引擎在 2016 年发布的 v4 版本就已经正式实装了多纹理渲染机制** [资料出处](https://medium.com/goodboy-digital/gpu-multi-texture-sprite-batching-21c90ae8f89b)。 - -**Phaser 引擎在 v4 与 v3 版本都实装了多纹理渲染机制（2019 - 2020年）**[资料出处](https://www.patreon.com/posts/39665256)。 - -::: - --- ## 启用动态合图 diff --git a/docs/docs/start-guide/new-features.md b/docs/docs/best-practices/new-features.md similarity index 100% rename from docs/docs/start-guide/new-features.md rename to docs/docs/best-practices/new-features.md diff --git a/docs/docs/start-guide/breaking-change.md b/docs/docs/breaking-change.md similarity index 94% rename from docs/docs/start-guide/breaking-change.md rename to docs/docs/breaking-change.md index 7db638c8..8f706ee1 100644 --- a/docs/docs/start-guide/breaking-change.md +++ b/docs/docs/breaking-change.md @@ -1,5 +1,5 @@ --- -sidebar_position: 4 +sidebar_position: 5 description: "一般情况下都不需要了解。" --- @@ -35,7 +35,7 @@ cc.macro.ENABLE_NATIVE_TTF_RENDERER = false; 这不意味着你不能手动调整了，而是建议你阅读新动态图集和新 Char 缓存模式相关的文档后再考虑是否有必要进行调整。 -关于这个你可以从 [新 UI 渲染批次合并指南](./batcher-guide.md) 进行了解。 +关于这个你可以查看 [提升项目性能](./best-practices/batcher-guide.md) 了解。 - **动态图集重复纹理的判断从 `texture._id` 改为使用 `texture._uuid`** @@ -56,7 +56,7 @@ cc.macro.ENABLE_NATIVE_TTF_RENDERER = false; - **暂不支持自定义材质** -如果项目中有组件在使用 Char 缓存模式并且设置了自定义材质则可能会失效，具体原因可前往 [新的 Char 缓存模式](../user-guide/text-render/text-char-mode.md) 文档进行了解。 +如果项目中有组件在使用 Char 缓存模式并且设置了自定义材质则可能会失效，具体原因可前往 [新的 Char 缓存模式](./user-guide/text-render/text-char-mode.md) 文档进行了解。 - **如果你的项目依赖 Char 缓存模式的内部实现细节，请重新检查相关代码** diff --git a/docs/docs/installation-guide/_category_.json b/docs/docs/installation-guide/_category_.json deleted file mode 100644 index af2c1ac7..00000000 --- a/docs/docs/installation-guide/_category_.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "label": "安装指南", - "position": 2, - "collapsed": false, - "link": { - "type": "doc", - "id": "installation-intro" - } -} diff --git a/docs/docs/installation-guide/installation-engine-plugin.md b/docs/docs/installation-guide/installation-engine-plugin.md deleted file mode 100644 index 0b2ecf20..00000000 --- a/docs/docs/installation-guide/installation-engine-plugin.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -sidebar_position: 1 -description: "推荐使用此方式进行一键安装。" ---- - -# 使用引擎扩展安装 - ---- -## 前往 Cocos Store 下载 - -在 Cocos Store 搜索名为 **Cocos Enhance Kit** 的引擎扩展，或者 [点此跳转](https://store.cocos.com/app/detail/3824)。 - -这个扩展不是免费的，**但其唯一的作用就是帮助你管理增强包的版本（查看、安装和卸载增强包）。** - -:::tip 常见问题 - -- **Enhance Kit 不是开源项目吗？？？** - - Enhance Kit 是完全开源的项目，这个引擎扩展只会为你提供自动化的安装方式，以后也只会有版本管理方面的功能。 - - 你可以选择 [手动安装](./installation-manual.md)，也只需要几步即可完成。 - -- **如何反馈有关这个扩展的问题或建议** - - 若遇到与这个扩展相关的问题或者建议，不要在增强包的 Github 仓库反馈，请在扩展的 **商店评论区** 进行反馈。 - - 因为这个扩展的收益是个人的，所以也只由个人维护。 - -::: - ---- -## 查询信息 - -安装好扩展后，可在 Cocos Creator 的菜单栏依次点击 **扩展 - 增强包管理 - 查看信息**，会打印当前环境信息。 - -![plugin-info](./assets/plugin-info.png) - -你可以看到当前引擎版本支持一键安装的增强包版本，已安装的增强包版本等信息。 - ---- -## 一键安装 - -安装好扩展后，可在 Cocos Creator 的菜单栏依次点击 **扩展 - 增强包管理 - 安装增强包 - 安装最新版本**，会自动开始安装增强包。 - -![plugin-install](./assets/plugin-install.png) - -:::note 扩展做了什么事 - -扩展帮您自动完成了手动安装时需要做的所有步骤，包括自定义引擎和放置 TypeScript 类型提示文件。 - -::: - -预览项目并检查 Devtools Console 打印的是否为 `Cocos Creator SP v2.4.x`，是的话则已经成功安装。 - -![installedconsole](./assets/installed-console.png) - -接下来推荐你从 [入门教程](../start-guide/start-guide-intro.mdx) 开始了解增强包为你的开发都带来了哪些新特性！ - ---- -## 更多特性 - -在增强包发布新版本之后，你可能还没做好升级的准备，这时候你可以点击 **扩展 - 增强包管理 - 安装增强包 - 安装其它版本** 安装增强包的历史版本。 - -该扩展会收录增强包发布过的所有版本。 - -增强包只会适配引擎的最新版本，如果你需要在其它引擎版本上安装增强包，一般需要手动使用 Git Patch。 - -之后扩展可能会额外适配更多的引擎版本，这取决于大家具体的需求如何。 diff --git a/docs/docs/installation-guide/installation-intro.mdx b/docs/docs/installation-guide/installation-intro.mdx deleted file mode 100644 index a4a3ec37..00000000 --- a/docs/docs/installation-guide/installation-intro.mdx +++ /dev/null @@ -1,14 +0,0 @@ -import DocCardList from '@theme/DocCardList'; -import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; - -# 安装指南 - -增强包主要使用 [自定义引擎](https://docs.cocos.com/creator/2.4/manual/zh/advanced-topics/engine-customization.html) 的方式对引擎进行修改。 - -但由于自定义引擎不能添加内置资源与扩展内置组件的 Inspector，所以还需要安装配套的引擎扩展。 - -对于使用 TypeScript 的项目，增强包提供了 `creator-sp.d.ts` 类型提示文件。 - -以下是两种常用的安装方式： - - diff --git a/docs/docs/installation-guide/installation-manual.md b/docs/docs/installation-guide/installation-manual.md deleted file mode 100644 index bc0cb194..00000000 --- a/docs/docs/installation-guide/installation-manual.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -sidebar_position: 2 -description: "需掌握一定的自定义引擎知识。" ---- - -# 手动安装 - -## 下载 Enhance Kit 压缩包 - -[点此下载压缩包](../update-log.md) - ---- -## 标准安装 - -**请确保您的项目所使用的引擎版本与增强包适配的引擎版本一致，否则请使用 [补丁安装](#补丁安装)。** - -:::tip 提示 - -建议升级到最新的引擎版本，官方只会对 2.x 版本只会进行维护性更新，所以不用担心其稳定性问题。 - -如果你的项目引擎版本较低，可以看一看 [使用引擎扩展安装](./installation-engine-plugin.md) ，支持对多个引擎版本进行一键安装。 - -::: - -### 1.替换自定义引擎 - -下载增强包后，解压压缩包可以看到压缩包内的 `engine` `cocos2d-x` `jsb-adapter` 这三个目录分别是已经整理好的 **JavaScript 引擎**、**Cocos2d-x 引擎** 和 **jsb-adpater**。 - -接着打开 Cocos Creator 菜单的 **项目 - 项目设置 - 自定义引擎**。 - -分别填写 **JavaScript 引擎路径**（对应 `engine` 目录）和 **Cocos2d-x 引擎路径**（对应 `cocos2d-x` 目录）。 - -![custom-engine](./assets/custom-engine.png) - -然后点击 Cocos Creator 主界面右上角的 **编辑器** 按钮，进入到编辑器的资源目录。 - -![ide-cocos-path](./assets//ide-cocos-path.png) - -接着使用压缩包内的 `jsb-adapter` 替换掉编辑器的 `Resources/builtin/jsb-adapter` 目录。 - -:::info 提示 - -如果你的项目不需要在原生平台上运行，则只定制 JavaScript 引擎即可。 - -::: - -### 2.安装引擎扩展 - -:::caution 注意 - -**请勿将此引擎扩展与 [使用引擎扩展安装](./installation-engine-plugin) 中的引擎扩展混淆！** - -**该扩展提供了必需的内置资源，是增强包开源的一部分，请勿同时安装两个引擎扩展，这会引起冲突！** - -::: - -压缩包内 `enhance-kit-support` 目录即是扩展本身，将其放到项目的 `packages` 目录即可。 - -增强包需要使用名为 `sp` 的 AssetBundle 存放资源，如果你的项目有使用 AssetBundle，请**确保该名称未被占用**。 - -没有必要将这个 Asset Bundle 设为远程包或者 Zip 压缩，里面只有 Effect 着色器资源。 - -更多详情可阅读官方的 [安装扩展](https://docs.cocos.com/creator/2.4/manual/zh/extension/install-and-share.html) 文档。 - -### 3.TypeScript 类型提示（可选） - -如果你的项目使用 TypeScript，可将压缩包内 `creator-sp.d.ts` 文件拷贝到项目根目录中。 - -![dts](assets/dts.png) - -部分代码编辑器可能需要重启之后类型提示才会生效。 - -### 4.重启 Cocos Creator - -完成以上的步骤后重启 Cocos Creator。 - -可在项目预览时检查 Devtools Console 打印的是否为 `Cocos Creator SP v2.4.x`，是的话则已经成功安装。 - -![](./assets/installed-console.png) - -接下来推荐你从 [入门教程](../start-guide/start-guide-intro.mdx) 开始了解增强包为你的开发都带来了哪些新特性！ - ---- -## 补丁安装 - -:::caution 提示 - -**建议至少将 Cocos Creator 升级到 v2.4.x 版本，增强包所做的改动不保证对 v2.4 版本以下的兼容性。** - -补丁安装需要掌握一定的 [Git](https://git-scm.com/doc) 知识和修改引擎源码的能力。 - -::: - -补丁安装实际上就是打 Git Patch，**在压缩包内的 `patches` 目录放着最新的 Git Patch 文件。** - -这种方式理论上可以在任意版本的引擎上进行，但由于这种方式如果需要正确的进行下去本就需要你拥有相关的知识与能力，所以我们不会说的很细致。 - -Git Patch 存储了我们所有的源码提交信息，所以你可以只挑选你想要的提交进行应用，在引擎目录去打补丁文件就等同于应用了我们对引擎的改动，之后就可以按照官方的自定义引擎文档去使用了。 - -打补丁一般使用两种命令： - -- 直接提交使用 `git am` -- 只将改动保留到工作区使用 `git apply` - -最好在打补丁时加上输出详细信息的命令参数以更好地确认补丁应用的情况。 - -常见的问题是我们在仓库的 `engine`、`jsb-adapter`、`cocos2d-x` 文件夹存放源码，那么提供的补丁文件对源码的应用路径也会是 `./engine` 这样的二级目录，如果你直接在引擎目录应用补丁，可能会发生没反应、补丁被跳过的问题，需要使用相应的命令参数来修正补丁应用的路径。 - -在完成自定义引擎的工作后，请别忘了安装引擎扩展哦。（可参考[标准安装的第 2 步](#2安装引擎扩展)进行操作）。 diff --git a/docs/docs/installation/_category_.json b/docs/docs/installation/_category_.json new file mode 100644 index 00000000..be44d7ff --- /dev/null +++ b/docs/docs/installation/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "安装", + "position": 2, + "collapsed": false +} diff --git a/docs/docs/installation-guide/assets/custom-engine.png b/docs/docs/installation/assets/custom-engine.png similarity index 100% rename from docs/docs/installation-guide/assets/custom-engine.png rename to docs/docs/installation/assets/custom-engine.png diff --git a/docs/docs/installation-guide/assets/dts.png b/docs/docs/installation/assets/dts.png similarity index 100% rename from docs/docs/installation-guide/assets/dts.png rename to docs/docs/installation/assets/dts.png diff --git a/docs/docs/installation-guide/assets/ide-cocos-path.png b/docs/docs/installation/assets/ide-cocos-path.png similarity index 100% rename from docs/docs/installation-guide/assets/ide-cocos-path.png rename to docs/docs/installation/assets/ide-cocos-path.png diff --git a/docs/docs/installation-guide/assets/installed-console.png b/docs/docs/installation/assets/installed-console.png similarity index 100% rename from docs/docs/installation-guide/assets/installed-console.png rename to docs/docs/installation/assets/installed-console.png diff --git a/docs/docs/installation-guide/assets/plugin-info.png b/docs/docs/installation/assets/plugin-info.png similarity index 100% rename from docs/docs/installation-guide/assets/plugin-info.png rename to docs/docs/installation/assets/plugin-info.png diff --git a/docs/docs/installation-guide/assets/plugin-install.png b/docs/docs/installation/assets/plugin-install.png similarity index 100% rename from docs/docs/installation-guide/assets/plugin-install.png rename to docs/docs/installation/assets/plugin-install.png diff --git a/docs/docs/installation/installation-auto.md b/docs/docs/installation/installation-auto.md new file mode 100644 index 00000000..6bff3a66 --- /dev/null +++ b/docs/docs/installation/installation-auto.md @@ -0,0 +1,65 @@ +--- +sidebar_position: 1 +description: "推荐使用此方式进行一键安装。" +--- + +# 一键安装 + +我们提供了一个**付费扩展**，该扩展**唯一的作用即是帮助你一键安装和管理社区版的版本**。 + +它也作为对我们给予肯定和支持的**赞助通道**。 + +:::tip 声明 + +- **Enhance Kit 不是免费的开源项目吗？** + + 再次重申 Enhance Kit 本身是**完全免费开源**的项目，该扩展**永远**只提供一键安装和版本管理的功能。 + + 也就是说，你可以选择 [手动安装](./installation-manual.md) 来使用，两者没有任何本质区别，也只需要几步即可完成。 + +::: + +## 安装扩展 + +[点此跳转到商店页面](https://store.cocos.com/app/detail/3824) 下载并安装版本管理扩展。 + +## 一键安装 + +依次点击 Cocos Creator 的菜单栏 **扩展 - 增强包管理 - 安装增强包 - 安装最新版本**，会自动开始安装社区版。 + +![plugin-install](./assets/plugin-install.png) + +:::caution 注意 + +- 社区版会增加一个名称为 `sp` 的 AssetBundle 以存放内置资源，**请确保你的项目未设置同名的 AssetBundle 引起冲突**。 +- 没有必要将这个 Asset Bundle 设为远程包或者 Zip 压缩，里面只有几个着色器资源。 + +::: + +:::note 扩展原理 + +扩展使用脚本帮您自动完成手动安装时需要做的步骤，比如设置自定义引擎和放置 TypeScript 类型提示文件。 + +::: + +### 安装其它版本 + +依次点击 Cocos Creator 的菜单栏 **扩展 - 增强包管理 - 安装增强包 - 安装其它版本** 可以安装当前引擎支持安装的所有版本。 + +可以重复执行安装操作，扩展会自动进行覆盖。 + +## 检查安装状态 + +你可以运行项目并检查 Console 是否有打印类似 `Cocos Creator SP v2.4.x` 的日志，有的话则已经成功安装。 + +![installedconsole](./assets/installed-console.png) + +接下来推荐你继续阅读文档中剩下的内容以了解你能够使用的新特性！ + +## 查看信息 + +依次点击 Cocos Creator 的菜单栏 **扩展 - 增强包管理 - 查看信息**，会打印当前环境信息。 + +![plugin-info](./assets/plugin-info.png) + +你可以看到当前引擎版本、支持一键安装的社区版版本和已安装的社区版版本等信息。 diff --git a/docs/docs/installation/installation-manual.md b/docs/docs/installation/installation-manual.md new file mode 100644 index 00000000..5cc5eb29 --- /dev/null +++ b/docs/docs/installation/installation-manual.md @@ -0,0 +1,74 @@ +--- +sidebar_position: 2 +description: "需掌握一定的自定义引擎知识。" +--- + +# 手动安装 + +## 下载并解压 + +前往 [Github Release](https://github.com/smallmain/cocos-enhance-kit/releases) 下载对应版本的压缩包。 + +**请确保您的项目的引擎版本与下载的社区版的引擎版本一致。** + +:::tip 提示 + +建议升级到最新的引擎版本，官方只会对 2.x 版本只会进行维护性更新，所以不用担心其稳定性问题。 + +::: + +解压压缩包后可以看到以下目录和文件： + +- `engine`（JavaScript engine） +- `cocos2d-x`（Cocos2d-x engine） +- `jsb-adapter`（JSB adpater） +- `adapters`（Minigame adpaters） +- `enhance-kit-support`（支持性引擎扩展） +- `creator-sp.d.ts`（社区版类型文件） + +## 替换自定义引擎 + +依次进入 Cocos Creator 菜单的 **项目 - 项目设置 - 自定义引擎**。 + +分别填写 **JavaScript 引擎路径**（对应 `engine` 目录）和 **Cocos2d-x 引擎路径**（对应 `cocos2d-x` 目录）。 + +![custom-engine](./assets/custom-engine.png) + +然后点击 Cocos Creator 主界面右上角的 **编辑器** 按钮，进入到编辑器的资源目录。 + +![ide-cocos-path](./assets//ide-cocos-path.png) + +接着使用压缩包内的 `jsb-adapter` 替换掉编辑器的 `Resources/builtin/jsb-adapter` 目录。 + +最后使用压缩包内的 `adapters` 替换掉编辑器的 `Resources/builtin/adapters` 目录。 + +## 安装支持性引擎扩展 + +按照官方的 [扩展安装](https://docs.cocos.com/creator/2.4/manual/zh/extension/install-and-share.html) 文档将压缩包内的 `enhance-kit-support` 目录放到项目的 `packages` 目录即可。 + +:::caution 注意 + +- 请勿将此引擎扩展与 [一键安装](./installation-auto) 中的付费引擎扩展混淆！ +- 该扩展提供社区版运行所需的内置资源，是开源的一部分，**请勿同时安装两个引擎扩展，这会引起冲突**！ +- 社区版会增加一个名称为 `sp` 的 AssetBundle 以存放内置资源，**请确保你的项目未设置同名的 AssetBundle 引起冲突**。 +- 没有必要将这个 Asset Bundle 设为远程包或者 Zip 压缩，里面只有几个着色器资源。 + +::: + +## TypeScript 类型提示（可选） + +如果你的项目使用 TypeScript，可将压缩包内 `creator-sp.d.ts` 文件拷贝到项目根目录中以获取新的代码提示。 + +![dts](assets/dts.png) + +部分代码编辑器可能需要重启之后类型提示才会生效。 + +## 重启 Cocos Creator + +完成以上的步骤后重启 Cocos Creator。 + +你可以运行项目并检查 Console 是否有打印类似 `Cocos Creator SP v2.4.x` 的日志，有的话则已经成功安装。 + +![installedconsole](./assets/installed-console.png) + +接下来推荐你继续阅读文档中剩下的内容以了解你能够使用的新特性！ diff --git a/docs/docs/intro.md b/docs/docs/intro.md index 2d3c89fe..01e66654 100644 --- a/docs/docs/intro.md +++ b/docs/docs/intro.md @@ -4,132 +4,130 @@ title: 介绍 hide_title: true --- +
+ ![logo](/img/logo2.png) -这是一个提供 Cocos Creator 引擎特性增强、修复与优化的**开源非官方增强包**。 +这是 [Cocos Creator](https://www.cocos.com/creator) v2.x 社区分叉版本，**提供了大量的新特性、性能改进与修复**。 -该项目使用自定义引擎的方式在符合原始引擎架构设计的基础上为 Cocos Creator 引擎加入新的特性、修复已知问题以及性能优化。 +未来将继续秉持着**完全开源、完全兼容**的理念提供新特性、优化与修复。 -正因为如此，增强包中的大部分特性能像升级引擎版本一样无需改动项目代码即可生效。 +非常欢迎，并且希望你能和我们一起来完善这个项目！ -:::info 项目的起源 +## 主要特性 -2021 年 2 月，Cocos 发布 Cocos Creator 3.0，之后不会再开发 2.x 版本的新特性，但 2.x 在一些方面还并不完善，所以这个非官方的引擎“魔改”合集应运而生。 +### 完全兼容 -给项目取名的时候想到相似的事情发生在 2014 年 4 月，官方停止了对 Windows XP 的维护，之后 Harkaz 发布了一个非官方增强包 Service Pack 4 (SP4)。 +社区版的现在乃至未来都会做到以下几点： -受到这个命名的启发，遂想将项目取名为 Service Pack。 +- 兼容旧项目，无需改动项目代码即可切换到社区版。 +- 不会对项目本身进行任何改动，随时可以切换回官方版。 +- 任何特性都可以选择性开启，保证项目的可控性。 -但是这个名字有点怪怪的，最后在 麒麟子(Kylins) 的帮助下，我们为项目想到了一个更好的名字，Enhance Kit，再次感谢 麒麟子(Kylins)。 +并且全平台兼容！ -::: +### 支持多纹理渲染 -## 重要特性 +在之前，每个相邻的节点使用不同的纹理渲染时会打断合批，我们一般通过调节节点顺序、合并图集的方式来避免这个问题。 -- **支持多纹理渲染**（多纹理材质、多纹理合批） - ![demo1](/demo-imgs/demo1.png) - -- **支持高 DPI 文本渲染**（Label、RichText 组件） - ![demo4](/demo-imgs/demo4.png) +但是实际应用起来情况复杂，且操作麻烦，无法优化到极致，而较高的 DrawCall 数量会导致设备性能下降、发热的问题。 -- **重构动态合图**（支持自动多纹理合批、优化算法、复用废弃空间等特性） - ![demo2](/demo-imgs/demo2.png) +现在，由于支持了多纹理渲染，可允许多达 8 张不同纹理进行渲染时也不会打断合批，**在最坏的情况下，也能将项目的 DrawCall 数量减少至 1/8**！ -- **重构 Label 组件的 CHAR 缓存模式**（支持自动多纹理合批、多图集、复用废弃空间等特性） - ![demo3](/demo-imgs/demo3.png) +并且，该特性在使用动态合图时会自动启用，无需任何改动即可得到优化效果。 -- **Spine 组件支持与其它组件合批、合入动态图集与 SpriteFrame 换装** - ![demo5](/demo-imgs/demo5.png) +![demo1](/demo-imgs/demo1.png) -## 功能演示 +### 支持高清文本渲染 -[Web Desktop 演示项目](https://smallmain.gitee.io/cocos-enhance-kit/demo/v1.0.0/web-desktop/index.html) +在之前，Cocos Creator 引擎默认以 1x 的分辨率渲染字体，所以有时候在某些 `Retina` 设备上会感觉到字体很模糊。 -[Web Mobile 演示项目](https://smallmain.gitee.io/cocos-enhance-kit/demo/v1.0.0/web-mobile/index.html)（请将设备横屏） +由于引擎本身不支持对其进行调节，我们会通过将 Label 的 `fontSize` 放大一倍，然后将 `scale` 缩小一倍的方式解决字体渲染模糊的问题。 -:::note 提示 +现在，增加了高清文本渲染的支持，你只需要通过一句代码： -增强包对引擎的改动完全开源，每个改动会带有原理说明文档，当你发现问题时请与我们进行反馈，如果你有兴致，可以默默帅气地提交一个 PR，帮助我们一起完善这个项目。 +```ts +cc.sp.labelRetinaScale = 2; +``` -::: +即可调整引擎文本渲染的分辨率，获得高清的文本渲染效果。 + +![demo4](/demo-imgs/demo4.png) + +### 动态合图增强 + +除了上面提到将动态合图支持了自动多纹理渲染之外，我们其实几乎重构了整个动态合图模块。 + +现在的动态合图即优化了算法，还**支持废弃空间复用**，这对于项目的性能优化空间的提升是巨大的。 + +并且，**Spine 现在也可以参与动态合图**了！ + +![demo2](/demo-imgs/demo2.png) + +### Label 组件增强 + +Label 一直是项目优化的最难点，因为它完全不能和其它的渲染组件进行合批，甚至大部分情况下也不能和其它 Label 组件合批。 + +在之前，使用 `Bitmap` 模式可以加入动态合图，以达到合批的目的，但受引擎动态合图不能复用废弃空间的限制，导致项目越运行，可以动态合图的空间就越小，很容易就会将动态图集塞满，所以基本不会在实际的项目中使用。 + +`Char` 模式也有类似的问题，内部的字符纹理即不支持复用，还最高仅支持 1 张纹理，纹理很容易就被填满导致无法渲染文本，不会在实际项目中使用。 + +但是现在，Label 得到了以下重大的改进： + +- 重构后的动态合图支持复用，`Bitmap` 模式的使用不再受限！ +- `Char` 模式得到重构，**支持废弃空间复用，支持最多 8 张字符纹理，支持自动多纹理合批**！ +- RichText 也得到同样的所有改进，并且开放了自定义材质的设置。 + +![demo3](/demo-imgs/demo3.png) + +### Spine 组件增强 + +除了 Label 之外，如果你的项目用到了 Spine 组件，那么它大概率会成为项目第二个优化难点。 + +现在，Spine 也得到了重大改进，**支持与其它组件合批，支持参与动态合图，还能无缝使用 SpriteFrame 进行换装**！ + +![demo5](/demo-imgs/demo5.png) + +### TiledMap 组件优化 + +单个 TiledMap 组件可能存在多个 TiledLayer，启用 Culling 特性后，每个 Layer 都需要单独计算 Culling 数据。 + +现在在满足条件的情况下可以复用 Culling 数据，以减少项目 CPU 的性能消耗。 ## 使用方法 -请阅读文档的 [安装指南](./installation-guide/installation-intro.mdx) 与 [入门教程](./start-guide/start-guide-intro.mdx)。 - -## 更新日志 - -### Enhance Kit v1.2.0 - -- **[新特性] cc.TiledLayer 支持复用 Culling 数据** -- [修复] 修复 MotionStreak 初始化报错的问题 -- [修复] 修复勾选延迟加载资源时资源不会加载的问题 - -### Enhance Kit v1.1.0 - -- **[新特性] 动态合图在符合条件的情况下会忽略 padding 将纹理加入动态图集** -- [修复] 修复动态图集 maxFrameSize 能设置为超出图集尺寸大小的问题 -- [修复] 修复 Spine 动态合图时未判断 attachment 是否存在 region 对象导致报错的问题 -- [修复] 修复 Android 平台打包出现 Implicit instantiation of undefined template 错误 - -### Enhance Kit v1.0.0 - -- **[新特性] 支持多纹理渲染** -- **[新特性] 重构动态图集，支持多个新特性** -- **[新特性] 重构 cc.Label 的 Char 缓存模式，支持多个新特性** -- **[新特性] 支持高 DPI 文本渲染** -- **[新特性] Spine 组件支持参与动态图集、与其它组件合批、使用 SpriteFrame 换装** -- [新特性] cc.Label、cc.RichText、cc.Sprite、cc.MotionStreak、Spine 组件支持使用多纹理材质，并支持自动切换材质机制 -- [新特性] cc.RichText 支持使用自定义材质 -- [修复] 直接修改 Effect 的属性不回导致其变体的 hash 值刷新 -- [修复] CHAR 缓存模式 hash 计算可能会有重复的问题 -- [调整] 默认禁用 Label 原生 TTF 渲染器 - -[点此](./update-log) 查看所有的更新日志。 +请阅读文档的 [入门指南](TODO)。 ## 贡献指南 -非常欢迎你能和我们一起来完善这个项目，请通过 Github 进行： - -- 如果你发现了问题请建立 `Issues` -- 如果你有好的想法，请进入 `Discussions` -- 如果你有新的代码提交，请建立 `Pull requests` - -**原则上你提交的任何修改都不能影响引擎原有功能，不允许删除引擎原有的特性，请认真思考代码设计。** +- 如果你有任何问题或者想法请建立新的 `Issues`，我们会尽自己所能帮助你！ +- 如果你有新的代码提交，请建立新的 `Pull requests` 以完成合并。 ## 常见问题 -### 为什么要直接修改引擎？ +**为什么要直接修改引擎？** -直接修改引擎可能是大部分人认为的下下策，比如我们常听到的： +官方对 2.x 版本已经停止了更新（仅做一些维护工作），修改引擎不会遇到在官方新版本发布后需要用大量时间去适配，或者特性冲突的问题。 -- 可以通过 “修改对象原型” 等编程技巧将改动做成一个插件脚本 -- 没接触过自定义引擎，不知道该如何使用 -- 已经修改过引擎了，不能直接进行标准安装，会覆盖原有的修改 +如果不自定义引擎，则无法兼容原生平台，即使不兼容，使用 Hack 的方式，某些特性的实现需要大量拷贝代码，包体会增大，可维护性会降低。 -以上问题我们都思考过，首先，现在引擎的 2.x 版本已经停止了更新（仅做一些维护工作），也就是说修改引擎不会遇到在官方新版本发布后需要用大量时间去适配的情况。 +最后，我们希望它接近 “原生” 的使用体验，就像只是一次引擎的无痛升级。 -其次，即使增强包的所有改动都能做成一个插件脚本，但无法兼容原生平台，并且一般都需要大量拷贝代码，包体会增大，可维护性会大幅降低。 +**启动 Cocos Creator 报 Error: Can not parse this input:undefined 错误** -最后，我们希望它接近 “原生” 的使用体验，就像引擎本来就有的功能一样，对于没有接触过自定义引擎的人，可以通过引擎扩展一键安装。 +你可能忘记安装配套的引擎扩展，所以没有找到增强包的内置资源，导致报错，请仔细阅读文档。 -对于已经修改过引擎的人，由于增强包提供的是 Git Patch，所以可以让你在原有的基础上轻松应用增强包的改动，你甚至可以只选取你想要的特性进行应用。 +**原生平台或模拟器报错：Assertion failed: (_type == Type::String), function toString, file Value.cpp, line 496.** -### 启动 Cocos Creator 报 Error: Can not parse this input:undefined 错误 +你可能没有替换引擎的 `jsb-adapter` 部分，或者说没有重启以使替换生效。 -这是你可能忘记安装配套的引擎扩展，所以没有找到增强包的内置资源导致的报错。 +并且原生平台需额外注意，升级后的首次构建可能需先删除原有的构建工程才会生效。 -### 原生平台或模拟器报错：Assertion failed: (_type == Type::String), function toString, file Value.cpp, line 496. +**使用模拟器预览时出现各种问题** -这是你没有替换引擎的 `jsb-adapter` 部分，或者说没有重启以生效。 +可能是因为模拟器没有重新编译导致的，请按照官方的 [引擎定制文档](https://docs.cocos.com/creator/2.4/manual/zh/advanced-topics/engine-customization.html#25-%E7%BC%96%E8%AF%91%E6%A8%A1%E6%8B%9F%E5%99%A8) 重新编译原生模拟器即可。 -注意：原生平台构建时可能需要先删除原有的 build 文件，替换操作才会生效。 - -### 使用模拟器预览时出现各种问题 - -可能是因为模拟器没有重新编译导致的，请按照官方的 [引擎定制文档](https://docs.cocos.com/creator/2.4/manual/zh/advanced-topics/engine-customization.html#25-%E7%BC%96%E8%AF%91%E6%A8%A1%E6%8B%9F%E5%99%A8) 重新编译模拟器即可。 - -### Spine 组件出现 Uncaught TypeError: Cannot read property ‘load’ of null, location: src/cocos2d-jsb.b5158.js 等问题 +**Spine 组件出现 Uncaught TypeError: Cannot read property ‘load’ of null, location: src/cocos2d-jsb.b5158.js 等问题** 这是引擎自身的问题，由于释放 Spine 资源，然后再次加载相同 Spine 资源时导致，具体请看： @@ -140,3 +138,12 @@ hide_title: true 1. 引擎已经有一个修复此问题的 PR，但还未合入，可自行合入：[PR #4307](https://github.com/cocos/engine-native/pull/4307) 2. 需要进行释放的 spine 资源，不让其参与动态合图（通过控制 Spine 组件的合图开关）。 3. 不释放需要参与动态合图的 spine 资源。 + +该问题已在 v2.4.13 版本修复，请升级增强包版本至 v2.0.0 以上。 + +## 支持我们 + +社区版的开发需要大量的工作来进行，你的支持是我们最大的动力： + +- 请给我们的项目仓库一个 [Star](https://github.com/smallmain/cocos-enhance-kit)！ +- 购买可有可无的 [一键安装扩展](https://store.cocos.com/app/detail/3824) 赞助我们！ diff --git a/docs/docs/start-guide/_category_.json b/docs/docs/start-guide/_category_.json deleted file mode 100644 index f2162559..00000000 --- a/docs/docs/start-guide/_category_.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "label": "入门教程", - "position": 3, - "collapsed": false, - "link": { - "type": "doc", - "id": "start-guide-intro" - } -} diff --git a/docs/docs/start-guide/advance-batcher-guide.md b/docs/docs/start-guide/advance-batcher-guide.md deleted file mode 100644 index c1138440..00000000 --- a/docs/docs/start-guide/advance-batcher-guide.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -sidebar_position: 2 -description: "极致地减少游戏 Draw Call。" ---- - -# 进阶合批指南 - -:::caution TODO - -施工中... - -::: diff --git a/docs/docs/start-guide/start-guide-intro.mdx b/docs/docs/start-guide/start-guide-intro.mdx deleted file mode 100644 index 1f2599a0..00000000 --- a/docs/docs/start-guide/start-guide-intro.mdx +++ /dev/null @@ -1,8 +0,0 @@ -import DocCardList from '@theme/DocCardList'; -import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; - -# 入门指南 - -这个教程会简单地介绍如何利用增强包提供的新特性来更好地使用 Cocos Creator 引擎： - - diff --git a/docs/docs/theory-guide/_category_.json b/docs/docs/theory-guide/_category_.json deleted file mode 100644 index 8831e2b8..00000000 --- a/docs/docs/theory-guide/_category_.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "label": "原理文档", - "position": 5, - "collapsed": true, - "link": { - "type": "doc", - "id": "theory-guide-intro" - } -} diff --git a/docs/docs/theory-guide/char-theory.md b/docs/docs/theory-guide/char-theory.md deleted file mode 100644 index 72fa8b06..00000000 --- a/docs/docs/theory-guide/char-theory.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -sidebar_position: 3 -description: "详细了解新 Char 缓存模式的实现方式。" ---- - -# 新 Char 缓存模式 - -:::caution TODO - -施工中... - -::: diff --git a/docs/docs/theory-guide/dynamic-batcher-theory.md b/docs/docs/theory-guide/dynamic-batcher-theory.md deleted file mode 100644 index d2937ba2..00000000 --- a/docs/docs/theory-guide/dynamic-batcher-theory.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -sidebar_position: 2 -description: "详细了解新动态合图的实现方式。" ---- - -# 新动态合图 - -:::caution TODO - -施工中... - -::: diff --git a/docs/docs/theory-guide/high-dpi-theory.md b/docs/docs/theory-guide/high-dpi-theory.md deleted file mode 100644 index 578b363d..00000000 --- a/docs/docs/theory-guide/high-dpi-theory.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -sidebar_position: 4 -description: "详细了解高 DPI 文本渲染的实现方式。" ---- - -# 高 DPI 文本渲染 - -:::caution TODO - -施工中... - -::: diff --git a/docs/docs/theory-guide/multi-theory.md b/docs/docs/theory-guide/multi-theory.md deleted file mode 100644 index c63160cd..00000000 --- a/docs/docs/theory-guide/multi-theory.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -sidebar_position: 1 -description: "详细了解多纹理渲染的实现方式。" ---- - -# 多纹理渲染 - -:::caution TODO - -施工中... - -::: diff --git a/docs/docs/theory-guide/richtext-custom-material-theory.md b/docs/docs/theory-guide/richtext-custom-material-theory.md deleted file mode 100644 index aac4ce93..00000000 --- a/docs/docs/theory-guide/richtext-custom-material-theory.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -sidebar_position: 5 -description: "详细了解使 RichText 支持自定义材质的实现方式。" ---- - -# 使 RichText 支持自定义材质 - -:::caution TODO - -施工中... - -::: diff --git a/docs/docs/theory-guide/spine-theory.md b/docs/docs/theory-guide/spine-theory.md deleted file mode 100644 index 60174be7..00000000 --- a/docs/docs/theory-guide/spine-theory.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -sidebar_position: 5 -description: "详细了解增强 Spine 的实现方式。" ---- - -# 增强 Spine - -:::caution TODO - -施工中... - -::: diff --git a/docs/docs/theory-guide/theory-guide-intro.mdx b/docs/docs/theory-guide/theory-guide-intro.mdx deleted file mode 100644 index d7f7adac..00000000 --- a/docs/docs/theory-guide/theory-guide-intro.mdx +++ /dev/null @@ -1,10 +0,0 @@ -import DocCardList from '@theme/DocCardList'; -import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; - -# 原理文档 - -:::caution TODO - -施工中... - -::: diff --git a/docs/docs/theory-guide/tiledmap-theory.md b/docs/docs/theory-guide/tiledmap-theory.md deleted file mode 100644 index 29ec69bb..00000000 --- a/docs/docs/theory-guide/tiledmap-theory.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -sidebar_position: 5 -description: "详细了解增强 TiledMap 的实现方式。" ---- - -# 增强 TiledMap - -:::caution TODO - -施工中... - -::: diff --git a/docs/docs/uninstall-guide.md b/docs/docs/uninstall-guide.md index 96318351..de7d5bef 100644 --- a/docs/docs/uninstall-guide.md +++ b/docs/docs/uninstall-guide.md @@ -2,9 +2,9 @@ sidebar_position: 6 --- -# 卸载指南 +# 卸载 -增强包不会对项目进行修改，但就像要将引擎降级一样，这种操作还是有风险的，所以我们提供两种卸载方式以供参考： +增强包不会对项目进行修改，但如果你的项目已经使用了就像要将引擎降级一样，这种操作还是有风险的，所以我们提供两种卸载方式以供参考： :::tip 提示 diff --git a/docs/docs/update-log.md b/docs/docs/update-log.md index 0b997875..a82f640a 100644 --- a/docs/docs/update-log.md +++ b/docs/docs/update-log.md @@ -4,38 +4,4 @@ sidebar_position: 7 # 更新日志 ---- -## Enhance Kit v1.2.0 - -适配 Cocos Creator v2.4.12、v2.4.10、v2.4.9 版本，[点此下载压缩包](https://github.com/smallmain/cocos-enhance-kit/releases/tag/v1.2.0) - -- **[新特性] cc.TiledLayer 支持复用 Culling 数据** -- [修复] 修复 MotionStreak 初始化报错的问题 -- [修复] 修复勾选延迟加载资源时资源不会加载的问题 - ---- -## Enhance Kit v1.1.0 - -适配 Cocos Creator v2.4.9 版本，[点此下载压缩包](https://github.com/smallmain/cocos-enhance-kit/releases/tag/v1.1.0) - -- **[新特性] 动态合图在符合条件的情况下会忽略 padding 将纹理加入动态图集** -- [修复] 修复动态图集 maxFrameSize 能设置为超出图集尺寸大小的问题 -- [修复] 修复 Spine 动态合图时未判断 attachment 是否存在 region 对象导致报错的问题 -- [修复] 修复 Android 平台打包出现 Implicit instantiation of undefined template 错误 - ---- -## Enhance Kit v1.0.0 - -适配 Cocos Creator v2.4.9 版本，[点此下载压缩包](https://github.com/smallmain/cocos-enhance-kit/releases/tag/v1.0.0) - -- **[新特性] 支持多纹理渲染** -- **[新特性] 重构动态图集，支持多个新特性** -- **[新特性] 重构 cc.Label 的 Char 缓存模式，支持多个新特性** -- **[新特性] 支持高 DPI 文本渲染** -- **[新特性] Spine 组件支持参与动态图集、与其它组件合批、使用 SpriteFrame 换装** -- [新特性] cc.Label、cc.RichText、cc.Sprite、cc.MotionStreak、Spine 组件支持使用多纹理材质，并支持自动切换材质机制 -- [新特性] cc.RichText 支持使用自定义材质 -- [修复] 直接修改 Effect 的属性不回导致其变体的 hash 值刷新 -- [修复] CHAR 缓存模式 hash 计算可能会有重复的问题 -- [调整] 默认禁用 Label 原生 TTF 渲染器 - +请前往 [Github Release](https://github.com/smallmain/cocos-enhance-kit/releases) 查看。 diff --git a/docs/docs/user-guide/_category_.json b/docs/docs/user-guide/_category_.json index d44dd7f3..177bda0e 100644 --- a/docs/docs/user-guide/_category_.json +++ b/docs/docs/user-guide/_category_.json @@ -1,9 +1,5 @@ { "label": "使用指南", "position": 4, - "collapsed": false, - "link": { - "type": "doc", - "id": "user-guide-intro" - } + "collapsed": false } diff --git a/docs/docs/user-guide/multi-render/multi-batcher.md b/docs/docs/user-guide/multi-render/multi-batcher.md index ab8c23d4..bd9f0a42 100644 --- a/docs/docs/user-guide/multi-render/multi-batcher.md +++ b/docs/docs/user-guide/multi-render/multi-batcher.md @@ -5,7 +5,7 @@ description: "了解如何手动进行多纹理合批。" # 多纹理合批 -在 [新 UI 渲染批次合并指南](../../start-guide/batcher-guide.md#充分利用动态合图) 中提到了动态合图与多纹理渲染结合后，能让多张图集纹理在同一批次渲染。 +在 [提升项目性能](../../best-practices/batcher-guide.md) 中提到了动态合图与多纹理渲染结合后，能让多张图集纹理在同一批次渲染。 如果你阅读过 [多纹理材质](./multi-material.md) 文档的话，肯定知道能使用 `MultiHandler` 的接口来动态设置材质的纹理插槽来实现。 @@ -122,4 +122,4 @@ batcher.reset(); ### 它的用途 -在 [进阶合批指南](../../start-guide/advance-batcher-guide.md) 中有提供一些常见的使用案例。 +在 [进阶合批指南](../../best-practices/advance-batcher-guide.md) 中有提供一些常见的使用案例。 diff --git a/docs/docs/user-guide/multi-render/multi-material.md b/docs/docs/user-guide/multi-render/multi-material.md index 3ab11ff8..90ff85d2 100644 --- a/docs/docs/user-guide/multi-render/multi-material.md +++ b/docs/docs/user-guide/multi-render/multi-material.md @@ -53,7 +53,7 @@ Spine 组件使用多纹理材质时会强制勾选 `enableBatch`，因为不开 除了直接在内置着色器的基础上修改之外，任何着色器中如果存在一个宏 `USE_MULTI_TEXTURE = true`，则会被认为是多纹理材质。 -[演示项目](https://smallmain.gitee.io/cocos-enhance-kit/demo/v1.0.0/web-desktop/index.html) 中有自定义材质的示范代码。 +演示项目中有自定义材质的示范代码可以参考。 :::tip 提示 diff --git a/docs/docs/user-guide/multi-render/multi-render-intro.mdx b/docs/docs/user-guide/multi-render/multi-render-intro.mdx index d72345e8..bde9bb5f 100644 --- a/docs/docs/user-guide/multi-render/multi-render-intro.mdx +++ b/docs/docs/user-guide/multi-render/multi-render-intro.mdx @@ -5,13 +5,33 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; :::tip 提示 -多纹理渲染属底层设施，如果你不是准备手动使用多纹理材质或者多纹理合批管理器的话，请跳过本特性文档。 +多纹理渲染属于底层设施，如果你不是准备手动使用多纹理材质或者多纹理合批管理器的话，请跳过本特性文档。 ::: -多纹理渲染在 [新 UI 渲染批次合并指南](../../start-guide/batcher-guide.md#什么是多纹理渲染) 中有所介绍。 +## 什么是多纹理渲染？ -其原理非常简单，并且为了让它能以最简单的方式在引擎中使用，已经在内部做好了封装： +在以前的认识里，我们知道相邻的节点使用不同的纹理（Texture）会导致不能合并批次。 + +其根本原因是纹理是使用 uniform 变量传给着色器的，而需要合并批次的话不允许每次渲染都拥有不同的 uniform 变量值。 + +增强包实现的是先设置多个 uniform 变量，比如将 8 张纹理写入到 "texture1" "texture2" "texture3"... 的 8 个 uniform 变量中，然后在着色器里再判断应该在渲染时使用哪个 uniform 变量。 + +这样的话如果所有渲染都只用这 8 张纹理，就都能合并为 1 个批次。 + +这要求设备支持采样多个纹理，而在现代绝大多数设备中都至少支持采样 8 张纹理，所以这不是问题。 + +当然除了这种方法，还有另外几种进行多纹理合批的方法，例如 "Texture Array" 和 "Bindless"，但都有实用性与兼容性的问题。 + +:::info 那么，代价是什么？ + +因为会多传递一个顶点属性，并且需要在着色器中去判断该使用哪个纹理，导致**合并批次并不一定会提升性能**。 + +所以我们建议在多个档次设备中实际测试项目是否使用多纹理渲染的性能差距。 + +::: + +为了让多纹理渲染能以最简单的方式在引擎中使用，社区版已经在内部对其做好了一些封装： diff --git a/docs/docs/user-guide/spine/spine-skin.md b/docs/docs/user-guide/spine/spine-skin.md index 08ab80e1..89ad3f0f 100644 --- a/docs/docs/user-guide/spine/spine-skin.md +++ b/docs/docs/user-guide/spine/spine-skin.md @@ -88,4 +88,4 @@ const clonedSkeletonData = skeletonData.clone(); 使用以上代码克隆 SkeletonData 后再进行换装，赋值给 Spine 组件，那么替换操作就只会对这个 Spine 组件生效。 --- -以上所有用法你可以在 [演示项目](https://smallmain.gitee.io/cocos-enhance-kit/demo/v1.0.0/web-desktop/index.html) 中找到示范代码。 +以上所有用法你可以在演示项目中找到示范代码。 diff --git a/docs/docs/user-guide/text-render/text-char-mode.md b/docs/docs/user-guide/text-render/text-char-mode.md index 7af5ab9f..bc5a67d9 100644 --- a/docs/docs/user-guide/text-render/text-char-mode.md +++ b/docs/docs/user-guide/text-render/text-char-mode.md @@ -4,7 +4,7 @@ description: "详细了解该缓存模式重构后的所有新特性。" --- # 新的 Char 缓存模式 -在 [新 UI 渲染批次合并指南](../../start-guide/batcher-guide.md#充分利用动态合图) 中提到 Bitmap 与 Char 缓存模式都支持了废弃字符空间复用的特性，但 Char 缓存模式的内部变化比较大，并且提供了一些可调整的设置项，使用上依旧只需要设置缓存模式即可。 +在 [提升项目性能](../../best-practices/batcher-guide.md) 中提到 Bitmap 与 Char 缓存模式都支持了废弃字符空间复用的特性，但 Char 缓存模式的内部变化比较大，并且提供了一些可调整的设置项，使用上依旧只需要设置缓存模式即可。 --- ## 在场景切换时清空所有字符图集 diff --git a/docs/docs/user-guide/text-render/text-high-dpi.md b/docs/docs/user-guide/text-render/text-high-dpi.md index 79f3f16c..c4bcab4b 100644 --- a/docs/docs/user-guide/text-render/text-high-dpi.md +++ b/docs/docs/user-guide/text-render/text-high-dpi.md @@ -4,7 +4,7 @@ description: "一行代码开启高清文本渲染。" --- # 高 DPI 支持 -可阅读 [上手其它新特性](../../start-guide/new-features.md#高-dpi-文本渲染) 了解基本的使用方法，除了注意性能以外，没有其它的注意事项。 +可阅读 [上手其它新特性](../../best-practices/new-features.md#高-dpi-文本渲染) 了解基本的使用方法，除了注意性能以外，没有其它的注意事项。 --- ## 调整全局开关 diff --git a/docs/docs/user-guide/user-guide-intro.mdx b/docs/docs/user-guide/user-guide-intro.mdx deleted file mode 100644 index 5368d877..00000000 --- a/docs/docs/user-guide/user-guide-intro.mdx +++ /dev/null @@ -1,16 +0,0 @@ -import DocCardList from '@theme/DocCardList'; -import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; - -# 使用指南 - -在 [入门教程](../start-guide/start-guide-intro.mdx) 里，你应该对如何更好地使用安装增强包后的引擎已经有所了解了。 - -通过该指南你可以更详细地了解增强包为引擎添加的每个特性与改动： - - - -:::caution 注意 - -在几乎所有平台上引擎都是使用 WebGL 渲染模式，所以增强包的大部分特性都未支持引擎的 Canvas 渲染模式，部分特性在 3D 节点下不生效。 - -::: diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index fa162d02..600fadd2 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -7,7 +7,7 @@ const darkCodeTheme = require('prism-react-renderer/themes/dracula'); /** @type {import('@docusaurus/types').Config} */ const config = { title: 'Cocos Enhance Kit', - tagline: '提供 Cocos Creator 引擎特性增强、修复与优化的开源非官方增强包', + tagline: '这是 Cocos Creator v2.x 社区分叉版本，提供了大量的新特性、性能改进与修复。', url: 'https://smallmain.github.io', baseUrl: '/cocos-enhance-kit/', onBrokenLinks: 'throw', @@ -36,17 +36,6 @@ const config = { docs: { sidebarPath: require.resolve('./sidebars.js'), includeCurrentVersion: true, - versions: { - "1.2.0": { - label: "v1.2.0", - }, - "1.1.0": { - label: "v1.1.0", - }, - "1.0.0": { - label: "v1.0.0", - } - } }, blog: { showReadingTime: true, @@ -64,10 +53,7 @@ const config = { navbar: { title: 'Cocos Enhance Kit', // style: 'primary', - logo: { - alt: 'Cocos Enhance Kit', - src: 'img/logo.png', - }, + items: [ { to: '/', @@ -82,7 +68,7 @@ const config = { label: '文档', }, { - href: 'https://smallmain.gitee.io/cocos-enhance-kit/demo/v1.0.0/web-desktop/index.html', + href: 'https://smallmain.github.io/cocos-enhance-kit/demo/v1.0.0/web-desktop/index.html', label: '演示', position: 'right', }, @@ -95,7 +81,7 @@ const config = { // { to: '/blog', label: 'Blog', position: 'left' }, { href: 'https://github.com/smallmain/cocos-enhance-kit', - label: '加星鼓励', + label: 'Github', position: 'right', className: 'header-github-link', }, diff --git a/docs/src/components/HomepageFeatures/index.tsx b/docs/src/components/HomepageFeatures/index.tsx index 44d5fcdb..c929cf1c 100644 --- a/docs/src/components/HomepageFeatures/index.tsx +++ b/docs/src/components/HomepageFeatures/index.tsx @@ -1,5 +1,5 @@ -import React from 'react'; import clsx from 'clsx'; +import React from 'react'; import styles from './styles.module.css'; type FeatureItem = { @@ -10,18 +10,26 @@ type FeatureItem = { const FeatureList: FeatureItem[] = [ { - title: '性能提升', + title: '增强特性', description: ( <> - 众多特性让你无需任何改动即可让项目的性能得到提升，并且能通过手动优化达到更好的效果。 + 新增文本高 DPI 渲染、Spine 换装等实用特性，让你的游戏开发更加省时省力省心。 ), }, { - title: '完全开源', + title: '性能提升', description: ( <> - 增强包是完全开源的项目，包括对原生引擎、JavaScript 引擎的改动都附有详细的原理文档。 + 多纹理渲染、动态合图、Label 增强等众多优化让你的游戏性能得到成倍的提升！ + + ), + }, + { + title: '开箱即用', + description: ( + <> + 本项目代码完全开源，包括对原生引擎、JavaScript 引擎的改动都附有详细的使用文档。 ), }, @@ -29,21 +37,13 @@ const FeatureList: FeatureItem[] = [ title: '原生体验', description: ( <> - 所有特性都通过自定义引擎实现，这种深度整合能带来其他方式所没有的 “原生” 的使用体验。 - - ), - }, - { - title: '增强特性', - description: ( - <> - 文本高 DPI 渲染、Spine 换装等实用特性的加入，让你的游戏开发更加省时省力省心。 + 所有特性都通过自定义引擎实现，这种深度整合能带来前所未有的 “原生” 使用体验。 ), }, ]; -function Feature({title, Svg, description}: FeatureItem) { +function Feature({ title, Svg, description }: FeatureItem) { return (
{/*
diff --git a/docs/src/css/custom.css b/docs/src/css/custom.css index ab42eafb..289efb42 100644 --- a/docs/src/css/custom.css +++ b/docs/src/css/custom.css @@ -6,110 +6,109 @@ /* You can override the default Infima variables here. */ :root { - --ifm-color-primary: #5b3aa1; - --ifm-color-primary-dark: #523491; - --ifm-color-primary-darker: #4d3189; - --ifm-color-primary-darkest: #402971; - --ifm-color-primary-light: #6440b1; - --ifm-color-primary-lighter: #6943b9; - --ifm-color-primary-lightest: #7b59c3; - --ifm-code-font-size: 85%; - --ifm-code-padding-horizontal: 0.3rem; - --ifm-global-radius: 0.3rem; - --ifm-code-border-radius: 0.2rem; - --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1); - --ifm-h1-font-size: 2.5rem; - --ifm-heading-font-weight: 500; - --ifm-button-font-weight: var(--ifm-heading-font-weight); - --ifm-hr-background-color: var(--ifm-color-emphasis-200); + --ifm-color-primary: #27729b; + --ifm-color-primary-dark: #23678c; + --ifm-color-primary-darker: #216184; + --ifm-color-primary-darkest: #1b506d; + --ifm-color-primary-light: #2b7dab; + --ifm-color-primary-lighter: #2d83b2; + --ifm-color-primary-lightest: #3394ca; + --ifm-code-font-size: 85%; + --ifm-code-padding-horizontal: 0.3rem; + --ifm-global-radius: 0.3rem; + --ifm-code-border-radius: 0.2rem; + --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1); + --ifm-h1-font-size: 2.5rem; + --ifm-heading-font-weight: 500; + --ifm-button-font-weight: var(--ifm-heading-font-weight); + --ifm-hr-background-color: var(--ifm-color-emphasis-200); } .navbar__title { - font-weight: 600; + font-weight: 600; } .navbar__link { - font-weight: var(--ifm-font-weight-normal); + font-weight: var(--ifm-font-weight-normal); } .menu { - font-weight: var(--ifm-font-weight-normal); + font-weight: var(--ifm-font-weight-normal); } .badge { - font-weight: var(--ifm-font-weight-normal); + font-weight: var(--ifm-font-weight-normal); } /* For readability concerns, you should choose a lighter palette in dark mode. */ -[data-theme='dark'] { - --ifm-color-primary: #c0a3ff; - --ifm-color-primary-dark: #a379ff; - --ifm-color-primary-darker: #9564ff; - --ifm-color-primary-darkest: #6a26ff; - --ifm-color-primary-light: #ddcdff; - --ifm-color-primary-lighter: #ebe2ff; - --ifm-color-primary-lightest: #ffffff; - --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3); +[data-theme="dark"] { + --ifm-color-primary: #c0a3ff; + --ifm-color-primary-dark: #a379ff; + --ifm-color-primary-darker: #9564ff; + --ifm-color-primary-darkest: #6a26ff; + --ifm-color-primary-light: #ddcdff; + --ifm-color-primary-lighter: #ebe2ff; + --ifm-color-primary-lightest: #ffffff; + --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3); } @media screen and (max-width: 996px) { - :root { - --ifm-font-size-base: 16px; - } + :root { + --ifm-font-size-base: 16px; + } - .banner-img { - display: none; - } + .banner-img { + display: none; + } } @media screen and (min-width: 997px) { - :root { - --ifm-font-size-base: 16px; - } + :root { + --ifm-font-size-base: 16px; + } - .hero__subtitle { - margin-top: 2rem; - } + .hero__subtitle { + margin-top: 2rem; + } - .hero__title { - font-size: 4rem; - margin-left: -20px; - } + .hero__title { + font-size: 4rem; + margin-left: -20px; + } - .markdown h1:first-child { - --ifm-h1-font-size: 2.5rem; - } + .markdown h1:first-child { + --ifm-h1-font-size: 2.5rem; + } - .title_node_modules-\@docusaurus-theme-classic-lib-next-theme-DocCategoryGeneratedIndexPage-styles-module { - --ifm-h1-font-size: 2.5rem !important; - } + .title_node_modules-\@docusaurus-theme-classic-lib-next-theme-DocCategoryGeneratedIndexPage-styles-module { + --ifm-h1-font-size: 2.5rem !important; + } - .markdown { - --ifm-h3-vertical-rhythm-top: 2; - } + .markdown { + --ifm-h3-vertical-rhythm-top: 2; + } - hr { - margin-top: 2.5rem; - } - - .markdown>h2 { - margin-bottom: calc(var(--ifm-heading-vertical-rhythm-bottom) * var(--ifm-leading) * 1.5); - } + hr { + margin-top: 2.5rem; + } + .markdown > h2 { + margin-bottom: calc(var(--ifm-heading-vertical-rhythm-bottom) * var(--ifm-leading) * 1.5); + } } .menu__caret:before { - background: var(--ifm-menu-link-sublist-icon) 50% / 2rem 1.5rem; + background: var(--ifm-menu-link-sublist-icon) 50% / 2rem 1.5rem; } -html[data-theme=light] .navbar__item.header-github-link { - background: url(data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjgiIGhlaWdodD0iMjciIGZpbGw9Im5vbmUiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+PHBhdGggZmlsbC1ydWxlPSJldmVub2RkIiBjbGlwLXJ1bGU9ImV2ZW5vZGQiIGQ9Ik0xMy42MDEgMGExMy41OTcgMTMuNTk3IDAgMCAwLTQuMjk4IDI2LjQ5OGMuNjc2LjEyNi45MjgtLjI5NS45MjgtLjY1NSAwLS4zMjUtLjAxMS0xLjM5NC0uMDE4LTIuNTMxLTMuNzgzLjgyMi00LjU4LTEuNjAzLTQuNTgtMS42MDMtLjYxOS0xLjU3Ni0xLjUxLTEuOTktMS41MS0xLjk5LTEuMjM0LS44NDUuMDkyLS44MjcuMDkyLS44MjcgMS4zNjYuMDk3IDIuMDg1IDEuNCAyLjA4NSAxLjQgMS4yMTMgMi4wNzkgMy4xODEgMS40OCAzLjk1NiAxLjEyNi4xMjMtLjg3OC40NzUtMS40NzcuODY0LTEuODE3LTMuMDEtLjM0LTYuMTk2LTEuNTA2LTYuMTk2LTYuNzE2YTUuMjU3IDUuMjU3IDAgMCAxIDEuNDAzLTMuNjU0Yy0uMTQyLS4zNDItLjYwOC0xLjcyNS4xMy0zLjYwMiAwIDAgMS4xNDItLjM2NSAzLjc0IDEuMzkzYTEyLjkyIDEyLjkyIDAgMCAxIDYuODEgMGMyLjU4NS0xLjc0OSAzLjczNi0xLjM5MyAzLjczNi0xLjM5My43MzkgMS44NzMuMjc1IDMuMjU1LjEzMyAzLjYwMmE1LjI1NSA1LjI1NSAwIDAgMSAxLjM5OCAzLjY1YzAgNS4yMjMtMy4xOCA2LjM3MS02LjIwNyA2LjcxLjQ4Ni40Mi45MiAxLjI0OS45MiAyLjUxNiAwIDEuODItLjAxMyAzLjI4NS0uMDEzIDMuNzMxIDAgLjM2My4yNDMuNzg2LjkzMi42NTNBMTMuNTk2IDEzLjU5NiAwIDAgMCAxMy42MDEgMHoiIGZpbGw9IiMyMTIyMkMiLz48cGF0aCBkPSJNNS4xNTQgMTkuNTJjLS4wMy4wNjgtLjEzNS4wODgtLjIyNS4wNDNzLS4xNTYtLjEzNy0uMTI0LS4yMDVjLjAzMS0uMDY3LjEzNy0uMDg3LjIyNS0uMDQyLjA4OC4wNDUuMTU1LjEzNy4xMjIuMjA0aC4wMDJ6bS41NTEuNjE1Yy0uMDY1LjA2LS4xOTEuMDMyLS4yNzktLjA2M2EuMjA3LjIwNyAwIDAgMS0uMDM4LS4yODFjLjA2Ny0uMDYxLjE4OS0uMDMyLjI3OS4wNjMuMDkuMDk0LjEwNi4yMjUuMDM4LjI4MXptLjUzNi43ODNjLS4wODMuMDU5LS4yMjUgMC0uMzA0LS4xMTctLjA3OS0uMTE3LS4wODMtLjI2NSAwLS4zMjQuMDg0LS4wNTguMjI1IDAgLjMwNC4xMTUuMDc5LjExNS4wODQuMjY4IDAgLjMyNnptLjc0My43NTdhLjI1NS4yNTUgMCAwIDEtLjM1OC0uMDZjLS4xMi0uMTExLS4xNTMtLjI2Ni0uMDc2LS4zNDguMDc2LS4wOC4yMjUtLjA2LjM1LjA1Mi4xMjcuMTEzLjE1NC4yNjYuMDc1LjM0N2wuMDEuMDA5em0xLjAwNC40MzljLS4wMzMuMTA2LS4xODQuMTU1LS4zNC4xMS0uMTU1LS4wNDUtLjI1NC0uMTctLjIyNS0uMjc5LjAzLS4xMDguMTg1LS4xNTcuMzQtLjExLjE1Ni4wNDcuMjU1LjE3LjIyNS4yNzl6IiBmaWxsPSIjZmZmIi8+PHBhdGggZD0iTTkuMSAyMi4xOTVjMCAuMTEzLS4xMjYuMjA1LS4yODguMjA3LS4xNjIuMDAyLS4yOTItLjA4NS0uMjk1LS4xOTgtLjAwMi0uMTEzLjEyNi0uMjA1LjI5LS4yMDcuMTY1LS4wMDIuMjkzLjA4OC4yOTMuMTk4em0xLjAzNi0uMTc1Yy4wMi4xMS0uMDkyLjIyNS0uMjUyLjI1Mi0uMTYuMDI3LS4zMDQtLjAzOS0uMzI0LS4xNDktLjAyLS4xMS4wOTQtLjIyNS4yNTItLjI1Mi4xNTgtLjAyNy4zMDQuMDM4LjMyNC4xNDh6IiBmaWxsPSIjMUUxRjI3Ii8+PC9zdmc+) 0/20px 20px no-repeat; +html[data-theme="light"] .navbar__item.header-github-link { + background: url(data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjgiIGhlaWdodD0iMjciIGZpbGw9Im5vbmUiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+PHBhdGggZmlsbC1ydWxlPSJldmVub2RkIiBjbGlwLXJ1bGU9ImV2ZW5vZGQiIGQ9Ik0xMy42MDEgMGExMy41OTcgMTMuNTk3IDAgMCAwLTQuMjk4IDI2LjQ5OGMuNjc2LjEyNi45MjgtLjI5NS45MjgtLjY1NSAwLS4zMjUtLjAxMS0xLjM5NC0uMDE4LTIuNTMxLTMuNzgzLjgyMi00LjU4LTEuNjAzLTQuNTgtMS42MDMtLjYxOS0xLjU3Ni0xLjUxLTEuOTktMS41MS0xLjk5LTEuMjM0LS44NDUuMDkyLS44MjcuMDkyLS44MjcgMS4zNjYuMDk3IDIuMDg1IDEuNCAyLjA4NSAxLjQgMS4yMTMgMi4wNzkgMy4xODEgMS40OCAzLjk1NiAxLjEyNi4xMjMtLjg3OC40NzUtMS40NzcuODY0LTEuODE3LTMuMDEtLjM0LTYuMTk2LTEuNTA2LTYuMTk2LTYuNzE2YTUuMjU3IDUuMjU3IDAgMCAxIDEuNDAzLTMuNjU0Yy0uMTQyLS4zNDItLjYwOC0xLjcyNS4xMy0zLjYwMiAwIDAgMS4xNDItLjM2NSAzLjc0IDEuMzkzYTEyLjkyIDEyLjkyIDAgMCAxIDYuODEgMGMyLjU4NS0xLjc0OSAzLjczNi0xLjM5MyAzLjczNi0xLjM5My43MzkgMS44NzMuMjc1IDMuMjU1LjEzMyAzLjYwMmE1LjI1NSA1LjI1NSAwIDAgMSAxLjM5OCAzLjY1YzAgNS4yMjMtMy4xOCA2LjM3MS02LjIwNyA2LjcxLjQ4Ni40Mi45MiAxLjI0OS45MiAyLjUxNiAwIDEuODItLjAxMyAzLjI4NS0uMDEzIDMuNzMxIDAgLjM2My4yNDMuNzg2LjkzMi42NTNBMTMuNTk2IDEzLjU5NiAwIDAgMCAxMy42MDEgMHoiIGZpbGw9IiMyMTIyMkMiLz48cGF0aCBkPSJNNS4xNTQgMTkuNTJjLS4wMy4wNjgtLjEzNS4wODgtLjIyNS4wNDNzLS4xNTYtLjEzNy0uMTI0LS4yMDVjLjAzMS0uMDY3LjEzNy0uMDg3LjIyNS0uMDQyLjA4OC4wNDUuMTU1LjEzNy4xMjIuMjA0aC4wMDJ6bS41NTEuNjE1Yy0uMDY1LjA2LS4xOTEuMDMyLS4yNzktLjA2M2EuMjA3LjIwNyAwIDAgMS0uMDM4LS4yODFjLjA2Ny0uMDYxLjE4OS0uMDMyLjI3OS4wNjMuMDkuMDk0LjEwNi4yMjUuMDM4LjI4MXptLjUzNi43ODNjLS4wODMuMDU5LS4yMjUgMC0uMzA0LS4xMTctLjA3OS0uMTE3LS4wODMtLjI2NSAwLS4zMjQuMDg0LS4wNTguMjI1IDAgLjMwNC4xMTUuMDc5LjExNS4wODQuMjY4IDAgLjMyNnptLjc0My43NTdhLjI1NS4yNTUgMCAwIDEtLjM1OC0uMDZjLS4xMi0uMTExLS4xNTMtLjI2Ni0uMDc2LS4zNDguMDc2LS4wOC4yMjUtLjA2LjM1LjA1Mi4xMjcuMTEzLjE1NC4yNjYuMDc1LjM0N2wuMDEuMDA5em0xLjAwNC40MzljLS4wMzMuMTA2LS4xODQuMTU1LS4zNC4xMS0uMTU1LS4wNDUtLjI1NC0uMTctLjIyNS0uMjc5LjAzLS4xMDguMTg1LS4xNTcuMzQtLjExLjE1Ni4wNDcuMjU1LjE3LjIyNS4yNzl6IiBmaWxsPSIjZmZmIi8+PHBhdGggZD0iTTkuMSAyMi4xOTVjMCAuMTEzLS4xMjYuMjA1LS4yODguMjA3LS4xNjIuMDAyLS4yOTItLjA4NS0uMjk1LS4xOTgtLjAwMi0uMTEzLjEyNi0uMjA1LjI5LS4yMDcuMTY1LS4wMDIuMjkzLjA4OC4yOTMuMTk4em0xLjAzNi0uMTc1Yy4wMi4xMS0uMDkyLjIyNS0uMjUyLjI1Mi0uMTYuMDI3LS4zMDQtLjAzOS0uMzI0LS4xNDktLjAyLS4xMS4wOTQtLjIyNS4yNTItLjI1Mi4xNTgtLjAyNy4zMDQuMDM4LjMyNC4xNDh6IiBmaWxsPSIjMUUxRjI3Ii8+PC9zdmc+) 0/20px 20px no-repeat; } .navbar__item.header-github-link { - padding-left: 1.6rem; - padding-bottom: 0.2rem; - margin-left: 1rem; - margin-right: -1rem; - background: url(data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjgiIGhlaWdodD0iMjciIGZpbGw9Im5vbmUiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+PHBhdGggZmlsbC1ydWxlPSJldmVub2RkIiBjbGlwLXJ1bGU9ImV2ZW5vZGQiIGQ9Ik0xMy42MDEgMGExMy41OTcgMTMuNTk3IDAgMCAwLTQuMjk4IDI2LjQ5OGMuNjc2LjEyNi45MjgtLjI5NS45MjgtLjY1NSAwLS4zMjUtLjAxMS0xLjM5NC0uMDE4LTIuNTMxLTMuNzgzLjgyMi00LjU4LTEuNjAzLTQuNTgtMS42MDMtLjYxOS0xLjU3Ni0xLjUxLTEuOTktMS41MS0xLjk5LTEuMjM0LS44NDUuMDkyLS44MjcuMDkyLS44MjcgMS4zNjYuMDk3IDIuMDg1IDEuNCAyLjA4NSAxLjQgMS4yMTMgMi4wNzkgMy4xODEgMS40OCAzLjk1NiAxLjEyNi4xMjMtLjg3OC40NzUtMS40NzcuODY0LTEuODE3LTMuMDEtLjM0LTYuMTk2LTEuNTA2LTYuMTk2LTYuNzE2YTUuMjU3IDUuMjU3IDAgMCAxIDEuNDAzLTMuNjU0Yy0uMTQyLS4zNDItLjYwOC0xLjcyNS4xMy0zLjYwMiAwIDAgMS4xNDItLjM2NSAzLjc0IDEuMzkzYTEyLjkyIDEyLjkyIDAgMCAxIDYuODEgMGMyLjU4NS0xLjc0OSAzLjczNi0xLjM5MyAzLjczNi0xLjM5My43MzkgMS44NzMuMjc1IDMuMjU1LjEzMyAzLjYwMmE1LjI1NSA1LjI1NSAwIDAgMSAxLjM5OCAzLjY1YzAgNS4yMjMtMy4xOCA2LjM3MS02LjIwNyA2LjcxLjQ4Ni40Mi45MiAxLjI0OS45MiAyLjUxNiAwIDEuODItLjAxMyAzLjI4NS0uMDEzIDMuNzMxIDAgLjM2My4yNDMuNzg2LjkzMi42NTNBMTMuNTk2IDEzLjU5NiAwIDAgMCAxMy42MDEgMHoiIGZpbGw9IiNmZmYiLz48cGF0aCBkPSJNNS4xNTQgMTkuNTJjLS4wMy4wNjgtLjEzNS4wODgtLjIyNS4wNDNzLS4xNTYtLjEzNy0uMTI0LS4yMDVjLjAzMS0uMDY3LjEzNy0uMDg3LjIyNS0uMDQyLjA4OC4wNDUuMTU1LjEzNy4xMjIuMjA0aC4wMDJ6bS41NTEuNjE1Yy0uMDY1LjA2LS4xOTEuMDMyLS4yNzktLjA2M2EuMjA3LjIwNyAwIDAgMS0uMDM4LS4yODFjLjA2Ny0uMDYxLjE4OS0uMDMyLjI3OS4wNjMuMDkuMDk0LjEwNi4yMjUuMDM4LjI4MXptLjUzNi43ODNjLS4wODMuMDU5LS4yMjUgMC0uMzA0LS4xMTctLjA3OS0uMTE3LS4wODMtLjI2NSAwLS4zMjQuMDg0LS4wNTguMjI1IDAgLjMwNC4xMTUuMDc5LjExNS4wODQuMjY4IDAgLjMyNnptLjc0My43NTdhLjI1NS4yNTUgMCAwIDEtLjM1OC0uMDZjLS4xMi0uMTExLS4xNTMtLjI2Ni0uMDc2LS4zNDguMDc2LS4wOC4yMjUtLjA2LjM1LjA1Mi4xMjcuMTEzLjE1NC4yNjYuMDc1LjM0N2wuMDEuMDA5em0xLjAwNC40MzljLS4wMzMuMTA2LS4xODQuMTU1LS4zNC4xMS0uMTU1LS4wNDUtLjI1NC0uMTctLjIyNS0uMjc5LjAzLS4xMDguMTg1LS4xNTcuMzQtLjExLjE1Ni4wNDcuMjU1LjE3LjIyNS4yNzl6bTEuMTEyLjA4MWMwIC4xMTMtLjEyNi4yMDUtLjI4OC4yMDctLjE2Mi4wMDItLjI5Mi0uMDg1LS4yOTUtLjE5OC0uMDAyLS4xMTMuMTI2LS4yMDUuMjktLjIwNy4xNjUtLjAwMi4yOTMuMDg4LjI5My4xOTh6bTEuMDM2LS4xNzVjLjAyLjExLS4wOTIuMjI1LS4yNTIuMjUyLS4xNi4wMjctLjMwNC0uMDM5LS4zMjQtLjE0OS0uMDItLjExLjA5NC0uMjI1LjI1Mi0uMjUyLjE1OC0uMDI3LjMwNC4wMzguMzI0LjE0OHoiIGZpbGw9IiNmZmYiLz48L3N2Zz4=) 0/20px 20px no-repeat; + padding-left: 1.6rem; + padding-bottom: 0.2rem; + margin-left: 1rem; + margin-right: -1rem; + background: url(data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjgiIGhlaWdodD0iMjciIGZpbGw9Im5vbmUiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+PHBhdGggZmlsbC1ydWxlPSJldmVub2RkIiBjbGlwLXJ1bGU9ImV2ZW5vZGQiIGQ9Ik0xMy42MDEgMGExMy41OTcgMTMuNTk3IDAgMCAwLTQuMjk4IDI2LjQ5OGMuNjc2LjEyNi45MjgtLjI5NS45MjgtLjY1NSAwLS4zMjUtLjAxMS0xLjM5NC0uMDE4LTIuNTMxLTMuNzgzLjgyMi00LjU4LTEuNjAzLTQuNTgtMS42MDMtLjYxOS0xLjU3Ni0xLjUxLTEuOTktMS41MS0xLjk5LTEuMjM0LS44NDUuMDkyLS44MjcuMDkyLS44MjcgMS4zNjYuMDk3IDIuMDg1IDEuNCAyLjA4NSAxLjQgMS4yMTMgMi4wNzkgMy4xODEgMS40OCAzLjk1NiAxLjEyNi4xMjMtLjg3OC40NzUtMS40NzcuODY0LTEuODE3LTMuMDEtLjM0LTYuMTk2LTEuNTA2LTYuMTk2LTYuNzE2YTUuMjU3IDUuMjU3IDAgMCAxIDEuNDAzLTMuNjU0Yy0uMTQyLS4zNDItLjYwOC0xLjcyNS4xMy0zLjYwMiAwIDAgMS4xNDItLjM2NSAzLjc0IDEuMzkzYTEyLjkyIDEyLjkyIDAgMCAxIDYuODEgMGMyLjU4NS0xLjc0OSAzLjczNi0xLjM5MyAzLjczNi0xLjM5My43MzkgMS44NzMuMjc1IDMuMjU1LjEzMyAzLjYwMmE1LjI1NSA1LjI1NSAwIDAgMSAxLjM5OCAzLjY1YzAgNS4yMjMtMy4xOCA2LjM3MS02LjIwNyA2LjcxLjQ4Ni40Mi45MiAxLjI0OS45MiAyLjUxNiAwIDEuODItLjAxMyAzLjI4NS0uMDEzIDMuNzMxIDAgLjM2My4yNDMuNzg2LjkzMi42NTNBMTMuNTk2IDEzLjU5NiAwIDAgMCAxMy42MDEgMHoiIGZpbGw9IiNmZmYiLz48cGF0aCBkPSJNNS4xNTQgMTkuNTJjLS4wMy4wNjgtLjEzNS4wODgtLjIyNS4wNDNzLS4xNTYtLjEzNy0uMTI0LS4yMDVjLjAzMS0uMDY3LjEzNy0uMDg3LjIyNS0uMDQyLjA4OC4wNDUuMTU1LjEzNy4xMjIuMjA0aC4wMDJ6bS41NTEuNjE1Yy0uMDY1LjA2LS4xOTEuMDMyLS4yNzktLjA2M2EuMjA3LjIwNyAwIDAgMS0uMDM4LS4yODFjLjA2Ny0uMDYxLjE4OS0uMDMyLjI3OS4wNjMuMDkuMDk0LjEwNi4yMjUuMDM4LjI4MXptLjUzNi43ODNjLS4wODMuMDU5LS4yMjUgMC0uMzA0LS4xMTctLjA3OS0uMTE3LS4wODMtLjI2NSAwLS4zMjQuMDg0LS4wNTguMjI1IDAgLjMwNC4xMTUuMDc5LjExNS4wODQuMjY4IDAgLjMyNnptLjc0My43NTdhLjI1NS4yNTUgMCAwIDEtLjM1OC0uMDZjLS4xMi0uMTExLS4xNTMtLjI2Ni0uMDc2LS4zNDguMDc2LS4wOC4yMjUtLjA2LjM1LjA1Mi4xMjcuMTEzLjE1NC4yNjYuMDc1LjM0N2wuMDEuMDA5em0xLjAwNC40MzljLS4wMzMuMTA2LS4xODQuMTU1LS4zNC4xMS0uMTU1LS4wNDUtLjI1NC0uMTctLjIyNS0uMjc5LjAzLS4xMDguMTg1LS4xNTcuMzQtLjExLjE1Ni4wNDcuMjU1LjE3LjIyNS4yNzl6bTEuMTEyLjA4MWMwIC4xMTMtLjEyNi4yMDUtLjI4OC4yMDctLjE2Mi4wMDItLjI5Mi0uMDg1LS4yOTUtLjE5OC0uMDAyLS4xMTMuMTI2LS4yMDUuMjktLjIwNy4xNjUtLjAwMi4yOTMuMDg4LjI5My4xOTh6bTEuMDM2LS4xNzVjLjAyLjExLS4wOTIuMjI1LS4yNTIuMjUyLS4xNi4wMjctLjMwNC0uMDM5LS4zMjQtLjE0OS0uMDItLjExLjA5NC0uMjI1LjI1Mi0uMjUyLjE1OC0uMDI3LjMwNC4wMzguMzI0LjE0OHoiIGZpbGw9IiNmZmYiLz48L3N2Zz4=) 0/20px 20px no-repeat; } diff --git a/docs/src/pages/index.module.css b/docs/src/pages/index.module.css index 2a30d5a9..10c78fa5 100644 --- a/docs/src/pages/index.module.css +++ b/docs/src/pages/index.module.css @@ -4,21 +4,21 @@ */ .heroBanner { - padding: 4rem 0; - /* text-align: center; */ - position: relative; - overflow: hidden; + padding: 4rem 0; + /* text-align: center; */ + position: relative; + overflow: hidden; } @media screen and (max-width: 996px) { - .heroBanner { - padding: 2rem; - } + .heroBanner { + padding: 2rem; + } } .buttons { - display: flex; - align-items: center; - margin-top: 70px; - /* justify-content: center; */ + display: flex; + align-items: center; + margin-top: 10px; + /* justify-content: center; */ } diff --git a/docs/src/pages/index.tsx b/docs/src/pages/index.tsx index ab537097..c35e4f94 100644 --- a/docs/src/pages/index.tsx +++ b/docs/src/pages/index.tsx @@ -1,20 +1,20 @@ -import React from 'react'; -import clsx from 'clsx'; -import Layout from '@theme/Layout'; import Link from '@docusaurus/Link'; +import useBaseUrl from '@docusaurus/useBaseUrl'; import useDocusaurusContext from '@docusaurus/useDocusaurusContext'; -import styles from './index.module.css'; import HomepageFeatures from '@site/src/components/HomepageFeatures'; -import Rocket from '../../static/img/rocket.svg'; +import Layout from '@theme/Layout'; +import clsx from 'clsx'; +import React from 'react'; +import styles from './index.module.css'; function HomepageHeader() { const { siteConfig } = useDocusaurusContext(); return ( // -
+
-

{siteConfig.title}

+ logo

{siteConfig.tagline}

@@ -30,7 +30,11 @@ function HomepageHeader() { 768 + ? 'https://smallmain.github.io/cocos-enhance-kit/demo/v1.0.0/web-desktop/index.html' + : 'https://smallmain.github.io/cocos-enhance-kit/demo/v1.0.0/web-mobile/index.html' + } style={{ marginRight: 20 }} > 查看演示 diff --git a/docs/static/img/favicon.ico b/docs/static/img/favicon.ico index 1cb23c3a..2c82f061 100644 Binary files a/docs/static/img/favicon.ico and b/docs/static/img/favicon.ico differ diff --git a/docs/static/img/logo.png b/docs/static/img/logo.png index 1cb23c3a..394cfb9e 100644 Binary files a/docs/static/img/logo.png and b/docs/static/img/logo.png differ diff --git a/docs/static/img/logo2.png b/docs/static/img/logo2.png index d13866fa..81692b8b 100644 Binary files a/docs/static/img/logo2.png and b/docs/static/img/logo2.png differ diff --git a/docs/versioned_docs/version-1.0.0/intro.md b/docs/versioned_docs/version-1.0.0/intro.md index 590c0322..b0ea5ce7 100644 --- a/docs/versioned_docs/version-1.0.0/intro.md +++ b/docs/versioned_docs/version-1.0.0/intro.md @@ -68,7 +68,7 @@ hide_title: true - **[新特性] Spine 组件支持参与动态图集、与其它组件合批、使用 SpriteFrame 换装** - [新特性] cc.Label、cc.RichText、cc.Sprite、cc.MotionStreak、Spine 组件支持使用多纹理材质，并支持自动切换材质机制 - [新特性] cc.RichText 支持使用自定义材质 -- [修复] 直接修改 Effect 的属性不回导致其变体的 hash 值刷新 +- [修复] 直接修改 Effect 的属性不会导致其变体的 hash 值刷新 - [修复] CHAR 缓存模式 hash 计算可能会有重复的问题 - [调整] 默认禁用 Label 原生 TTF 渲染器 diff --git a/docs/versioned_docs/version-1.0.0/update-log.md b/docs/versioned_docs/version-1.0.0/update-log.md index aafefcb9..e80a6ecb 100644 --- a/docs/versioned_docs/version-1.0.0/update-log.md +++ b/docs/versioned_docs/version-1.0.0/update-log.md @@ -16,7 +16,7 @@ sidebar_position: 7 - **[新特性] Spine 组件支持参与动态图集、与其它组件合批、使用 SpriteFrame 换装** - [新特性] cc.Label、cc.RichText、cc.Sprite、cc.MotionStreak、Spine 组件支持使用多纹理材质，并支持自动切换材质机制 - [新特性] cc.RichText 支持使用自定义材质 -- [修复] 直接修改 Effect 的属性不回导致其变体的 hash 值刷新 +- [修复] 直接修改 Effect 的属性不会导致其变体的 hash 值刷新 - [修复] CHAR 缓存模式 hash 计算可能会有重复的问题 - [调整] 默认禁用 Label 原生 TTF 渲染器 diff --git a/docs/versioned_docs/version-1.1.0/intro.md b/docs/versioned_docs/version-1.1.0/intro.md index 225bca5a..775f23ea 100644 --- a/docs/versioned_docs/version-1.1.0/intro.md +++ b/docs/versioned_docs/version-1.1.0/intro.md @@ -75,7 +75,7 @@ hide_title: true - **[新特性] Spine 组件支持参与动态图集、与其它组件合批、使用 SpriteFrame 换装** - [新特性] cc.Label、cc.RichText、cc.Sprite、cc.MotionStreak、Spine 组件支持使用多纹理材质，并支持自动切换材质机制 - [新特性] cc.RichText 支持使用自定义材质 -- [修复] 直接修改 Effect 的属性不回导致其变体的 hash 值刷新 +- [修复] 直接修改 Effect 的属性不会导致其变体的 hash 值刷新 - [修复] CHAR 缓存模式 hash 计算可能会有重复的问题 - [调整] 默认禁用 Label 原生 TTF 渲染器 diff --git a/docs/versioned_docs/version-1.1.0/update-log.md b/docs/versioned_docs/version-1.1.0/update-log.md index 7203c088..c535525f 100644 --- a/docs/versioned_docs/version-1.1.0/update-log.md +++ b/docs/versioned_docs/version-1.1.0/update-log.md @@ -26,7 +26,7 @@ sidebar_position: 7 - **[新特性] Spine 组件支持参与动态图集、与其它组件合批、使用 SpriteFrame 换装** - [新特性] cc.Label、cc.RichText、cc.Sprite、cc.MotionStreak、Spine 组件支持使用多纹理材质，并支持自动切换材质机制 - [新特性] cc.RichText 支持使用自定义材质 -- [修复] 直接修改 Effect 的属性不回导致其变体的 hash 值刷新 +- [修复] 直接修改 Effect 的属性不会导致其变体的 hash 值刷新 - [修复] CHAR 缓存模式 hash 计算可能会有重复的问题 - [调整] 默认禁用 Label 原生 TTF 渲染器 diff --git a/docs/versioned_docs/version-1.2.0/intro.md b/docs/versioned_docs/version-1.2.0/intro.md index 2d3c89fe..06ab0d71 100644 --- a/docs/versioned_docs/version-1.2.0/intro.md +++ b/docs/versioned_docs/version-1.2.0/intro.md @@ -81,7 +81,7 @@ hide_title: true - **[新特性] Spine 组件支持参与动态图集、与其它组件合批、使用 SpriteFrame 换装** - [新特性] cc.Label、cc.RichText、cc.Sprite、cc.MotionStreak、Spine 组件支持使用多纹理材质，并支持自动切换材质机制 - [新特性] cc.RichText 支持使用自定义材质 -- [修复] 直接修改 Effect 的属性不回导致其变体的 hash 值刷新 +- [修复] 直接修改 Effect 的属性不会导致其变体的 hash 值刷新 - [修复] CHAR 缓存模式 hash 计算可能会有重复的问题 - [调整] 默认禁用 Label 原生 TTF 渲染器 diff --git a/docs/versioned_docs/version-1.2.0/update-log.md b/docs/versioned_docs/version-1.2.0/update-log.md index 0b997875..ce48f0fc 100644 --- a/docs/versioned_docs/version-1.2.0/update-log.md +++ b/docs/versioned_docs/version-1.2.0/update-log.md @@ -35,7 +35,7 @@ sidebar_position: 7 - **[新特性] Spine 组件支持参与动态图集、与其它组件合批、使用 SpriteFrame 换装** - [新特性] cc.Label、cc.RichText、cc.Sprite、cc.MotionStreak、Spine 组件支持使用多纹理材质，并支持自动切换材质机制 - [新特性] cc.RichText 支持使用自定义材质 -- [修复] 直接修改 Effect 的属性不回导致其变体的 hash 值刷新 +- [修复] 直接修改 Effect 的属性不会导致其变体的 hash 值刷新 - [修复] CHAR 缓存模式 hash 计算可能会有重复的问题 - [调整] 默认禁用 Label 原生 TTF 渲染器 diff --git a/media/favicon.ico b/media/favicon.ico new file mode 100644 index 00000000..2c82f061 Binary files /dev/null and b/media/favicon.ico differ diff --git a/media/logo-round.png b/media/logo-round.png new file mode 100644 index 00000000..55c70d9f Binary files /dev/null and b/media/logo-round.png differ diff --git a/media/logo-round.psd b/media/logo-round.psd new file mode 100644 index 00000000..ab49deb6 Binary files /dev/null and b/media/logo-round.psd differ diff --git a/media/logo-round@0.1x.png b/media/logo-round@0.1x.png new file mode 100644 index 00000000..65ae88c2 Binary files /dev/null and b/media/logo-round@0.1x.png differ diff --git a/media/logo-round@0.25x.png b/media/logo-round@0.25x.png new file mode 100644 index 00000000..81692b8b Binary files /dev/null and b/media/logo-round@0.25x.png differ diff --git a/media/logo-round@0.5x.png b/media/logo-round@0.5x.png new file mode 100644 index 00000000..394cfb9e Binary files /dev/null and b/media/logo-round@0.5x.png differ diff --git a/media/logo-without-text.png b/media/logo-without-text.png new file mode 100644 index 00000000..d6930872 Binary files /dev/null and b/media/logo-without-text.png differ diff --git a/media/logo-without-text.psd b/media/logo-without-text.psd new file mode 100644 index 00000000..890cae5e Binary files /dev/null and b/media/logo-without-text.psd differ diff --git a/media/logo-without-text@0.1x.png b/media/logo-without-text@0.1x.png new file mode 100644 index 00000000..dab253c3 Binary files /dev/null and b/media/logo-without-text@0.1x.png differ diff --git a/media/logo-without-text@0.25x.png b/media/logo-without-text@0.25x.png new file mode 100644 index 00000000..c176b45f Binary files /dev/null and b/media/logo-without-text@0.25x.png differ diff --git a/media/logo-without-text@0.5x.png b/media/logo-without-text@0.5x.png new file mode 100644 index 00000000..17c179ff Binary files /dev/null and b/media/logo-without-text@0.5x.png differ diff --git a/media/logo-without-text@0.75x.png b/media/logo-without-text@0.75x.png new file mode 100644 index 00000000..82588d01 Binary files /dev/null and b/media/logo-without-text@0.75x.png differ diff --git a/media/logo.psd b/media/logo.psd new file mode 100644 index 00000000..6ef7fe09 Binary files /dev/null and b/media/logo.psd differ diff --git a/scripts/index.js b/scripts/index.js new file mode 100644 index 00000000..6f13a79f --- /dev/null +++ b/scripts/index.js @@ -0,0 +1,446 @@ +import { confirm, input } from "@inquirer/prompts"; +import { $ } from "execa"; +import gracefulFs from "graceful-fs"; +import { Octokit } from 'octokit'; +import { basename, extname, join } from "path"; +import { cwd, env } from "process"; +import { maxSatisfying } from "semver"; +import { Client } from 'ssh2'; +import { Zip } from 'zip-lib'; +const { createReadStream, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } = gracefulFs; + +// 公共函数 +const $$ = $({ stdout: 'inherit', stderr: 'inherit' }); + +function copyDirectory(sourceDir, targetDir) { + // 创建目标目录 + mkdirSync(targetDir, { recursive: true }); + + // 读取源目录中的文件和子目录 + const files = readdirSync(sourceDir); + + // 遍历源目录中的文件和子目录 + files.forEach((file) => { + const sourcePath = join(sourceDir, file); + const targetPath = join(targetDir, file); + + // 判断是否为文件 + if (statSync(sourcePath).isFile()) { + // 如果是文件，则直接拷贝到目标目录 + copyFileSync(sourcePath, targetPath); + } else { + // 如果是子目录，则递归调用copyDir函数进行拷贝 + copyDir(sourcePath, targetPath); + } + }); +} + +async function uploadBySFTP(host, port, username, password, filePath, targetFilePath) { + return new Promise((resolve, reject) => { + const client = new Client(); + + client.on('ready', () => { + console.log('SSH 连接已建立'); + client.sftp((err, sftp) => { + if (err) { + reject(err); + client.end(); + return; + } + sftp.exists(targetFilePath, hasErr => { + if (!hasErr) { + resolve(); + client.end(); + return; + } + + const readStream = createReadStream(filePath); + const writeStream = sftp.createWriteStream(targetFilePath); + + writeStream.on('close', () => { + resolve(); + client.end(); + }); + + writeStream.on('error', (err) => { + reject(err); + client.end(); + }); + + readStream.pipe(writeStream); + }); + }); + }); + + client.on('error', (err) => { + reject(err); + }); + + client.connect({ + host, + port, + username, + password, + }); + }); +} + +// 试运行 +const DRYRUN = true; + +// 目录 +const masterPath = cwd(); +const sourcePath = await input({ + message: "请输入源码分支目录：", + required: true, + default: "/Users/smallmain/Documents/Work/cocos-service-pack-src", +}); +const extensionPath = await input({ + message: "请输入付费扩展目录（如果有的话）：", + required: false, + default: "/Users/smallmain/Documents/Work/cocos-service-pack-extension", +}); + +console.log("主分支目录：", masterPath); +console.log("源码目录：", sourcePath); +console.log("付费扩展目录：", extensionPath); + +// 版本号 +const engineVersion = await input({ + message: "请输入发布的引擎版本：", + required: true, + default: "1.0.0", +}); +const kitVersion = await input({ + message: "请输入发布的社区版版本：", + required: true, + default: "1.0.0", +}); + +// 更新源码 VERSION.md +readdirSync(sourcePath, { + recursive: true, + encoding: "utf-8", +}) + .filter(path => basename(path) === "VERSION.md") + .forEach(path => { + const filePath = join(sourcePath, path); + + if (!DRYRUN) { + writeFileSync(filePath, kitVersion); + } + + console.log("更新文件", filePath); + }); + +// 更新源码 README.md +const SOURCE_README = `Cocos Enhance Kit v${kitVersion} 引擎源码\n\n适配 v${engineVersion} 引擎\n`; +const sourceReadmePath = join(sourcePath, "README.md"); +if (!DRYRUN) { + writeFileSync(sourceReadmePath, SOURCE_README); +} +console.log("更新文件", sourceReadmePath); + +// 更新 sp.js 版本号 +const SPJS_REGEX = /version:\s*"(.*?)"/; +const spjsPath = join(sourcePath, "engine/cocos2d/core/sp/sp.js"); +const newSpjsContent = readFileSync(spjsPath, { encoding: "utf-8" }) + .replace(SPJS_REGEX, `version: "${kitVersion}"`); +if (!DRYRUN) { + writeFileSync(spjsPath, newSpjsContent); +} +console.log("更新文件", spjsPath); + +// 确保存在相应版本的支持性扩展 +const supportPath = join(masterPath, "extension", `v${kitVersion}`, "enhance-kit-support"); +if (!existsSync(supportPath)) { + const versions = readdirSync(join(masterPath, "extension")); + const latestVersion = maxSatisfying(versions, "*"); + const needCopy = await confirm({ + message: `未发现 v${kitVersion} 版本的支持性扩展，是否从 ${latestVersion} 拷贝?`, + default: true, + }); + if (needCopy) { + const src = join(masterPath, "extension", latestVersion); + const dest = join(masterPath, "extension", `v${kitVersion}`); + + if (!DRYRUN) { + copyDirectory(src, dest); + } + + console.log("拷贝目录", src, "->", dest); + } +} + +// 确保支持性扩展 package.json 版本号正确 +const supportPackageJsonPath = join(supportPath, "package.json"); +const supportPackageJson = JSON.parse(readFileSync(supportPackageJsonPath, { encoding: "utf-8" })); +supportPackageJson.version = kitVersion; +if (!DRYRUN) { + writeFileSync(supportPackageJsonPath, JSON.stringify(supportPackageJson, null, 2)); +} +console.log("更新文件", supportPackageJsonPath); + +// 准备压缩包 +const cppPath = join(sourcePath, "cocos2d-x"); +const cppBuildPath = join(cppPath, "build/build"); +const jsPath = join(sourcePath, "engine"); +const jsNpmPath = join(jsPath, "node_modules"); +const jsbPath = join(sourcePath, "jsb-adapter"); +const minigamePath = join(sourcePath, "adapters"); +const dtsPath = join(sourcePath, "creator-sp.d.ts"); +const zipPath = join(masterPath, `cocos-enhance-kit-v${kitVersion}-v${engineVersion}.zip`); + +if (!DRYRUN) { + rmSync(cppBuildPath, { force: true, recursive: true }); + rmSync(jsNpmPath, { force: true, recursive: true }); +} +console.log("删除目录", cppBuildPath); +console.log("删除目录", jsNpmPath); +if (!DRYRUN) { + console.log("开始编译 JavaScript 引擎"); + try { + await $$({ cwd: jsPath })`gulp build-dev`; + } catch (error) { + await confirm({ + message: `自动编译 JavaScript 引擎失败，请手动编译后继续`, + default: true, + }); + } +} +console.log("已编译 JavaScript 引擎"); +if (!DRYRUN) { + console.log("开始编译当前平台的原生模拟器"); + try { + await $$({ cwd: cppPath })`gulp gen-simulator`; + await $$({ cwd: cppPath })`gulp update-simulator-config`; + } catch (error) { + await confirm({ + message: `自动编译当前平台的原生模拟器失败，请手动编译后继续`, + default: true, + }); + } +} +console.log("已编译当前平台的原生模拟器"); + +// 创建压缩包 +if (!DRYRUN) { + const sourceZipFile = new Zip(); + console.log("正在压缩", jsPath); + sourceZipFile.addFolder(jsPath, "engine"); + console.log("正在压缩", cppPath); + sourceZipFile.addFolder(cppPath, "cocos2d-x"); + console.log("正在压缩", jsbPath); + sourceZipFile.addFolder(jsbPath, "jsb-adapter"); + console.log("正在压缩", minigamePath); + sourceZipFile.addFolder(minigamePath, "adapters"); + console.log("正在压缩", supportPath); + sourceZipFile.addFolder(supportPath, "enhance-kit-support"); + console.log("正在压缩", dtsPath); + sourceZipFile.addFile(dtsPath); + await sourceZipFile.archive(zipPath); +} +console.log("已压缩至文件", zipPath); + +// [付费扩展] +if (extensionPath) { + // 创建压缩包 + const payZipPath = join(masterPath, `${kitVersion}.zip`); + if (!DRYRUN) { + const sourceZipFile = new Zip(); + console.log("正在压缩", jsPath); + sourceZipFile.addFolder(jsPath, `${kitVersion}/engine`); + console.log("正在压缩", cppPath); + sourceZipFile.addFolder(cppPath, `${kitVersion}/cocos2d-x`); + console.log("正在压缩", jsbPath); + sourceZipFile.addFolder(jsbPath, `${kitVersion}/jsb-adapter`); + console.log("正在压缩", minigamePath); + sourceZipFile.addFolder(minigamePath, `${kitVersion}/adapters`); + console.log("正在压缩", dtsPath); + sourceZipFile.addFile(dtsPath, `${kitVersion}/creator-sp.d.ts`); + await sourceZipFile.archive(payZipPath); + } + console.log("已压缩至文件", payZipPath); + + // 上传至 downloadcdn.smallmain.com + const payZipUrl = `http://downloadcdn.smallmain.com/cocos-enhance-kit/${engineVersion}/${kitVersion}.zip`; + if (!DRYRUN) { + console.log("正在上传文件", payZipPath); + await uploadBySFTP( + env.HOST, + env.PORT, + env.USERNAME, + env.PASSWORD, + payZipPath, + `/www/wwwroot/download.smallmain.com/cocos-enhance-kit/${engineVersion}/${kitVersion}.zip`, + ); + } + console.log("已上传文件", payZipUrl); + + // 手动修改 config.json + await confirm({ + message: `请将压缩文件上传至各网盘，并修改 config.json 指向下载链接`, + default: true, + }); + + // 手动修改 package.json 的 version 字段 + await confirm({ + message: `请修改 package.json 的 version 确定版本号后继续`, + default: true, + }); + + // 压缩为扩展 zip 文件 + const extensionVersion = JSON.parse(readFileSync(join(extensionPath, "package.json"), { encoding: "utf-8" })).version; + const extensionZipPath = join(masterPath, `cocos-enhance-kit-extension-v${extensionVersion}.zip`); + if (!DRYRUN) { + const sourceZipFile = new Zip(); + readdirSync(extensionPath, { withFileTypes: true }) + .filter(v => v.name !== "packages") + .forEach(v => { + const path = join(v.path, v.name); + console.log("正在压缩", path); + if (v.isFile()) { + sourceZipFile.addFile(path, v.name); + } else { + sourceZipFile.addFolder(path, v.name); + } + }); + + // packages 目录需要仅保留 backup 目录，所以特殊处理 + const packagesPath = join(extensionPath, "packages"); + readdirSync(packagesPath, { withFileTypes: true }) + .forEach(v => { + if (v.isFile()) { + const path = join(v.path, v.name); + console.log("正在压缩", path); + sourceZipFile.addFile(path, join("packages", v.name)); + } else { + const relPath = join(v.name, "backup"); + const path = join(v.path, relPath); + console.log("正在压缩", path); + sourceZipFile.addFolder(path, join("packages", relPath)); + } + }); + + await sourceZipFile.archive(extensionZipPath); + } + console.log("已压缩至文件", extensionZipPath); + + // 手动上传到 Cocos Store + await confirm({ + message: `请手动上传 zip 文件到 Cocos Store`, + default: true, + }); +} + +// 更新 Demo +const demoBuildPath = join(masterPath, "demo/build"); +const demoDesktopBuildPath = join(demoBuildPath, "web-desktop"); +const demoMobileBuildPath = join(demoBuildPath, "web-mobile"); +const demoTargetPath = join(masterPath, "docs/static/demo", `v${kitVersion}`); +const demoDesktopTargetPath = join(demoTargetPath, "web-desktop"); +const demoMobileTargetPath = join(demoTargetPath, "web-mobile"); +if (!existsSync(demoTargetPath)) { + await confirm({ + message: `请测试并编译 Demo 项目，然后继续操作`, + default: true, + }); + if (!DRYRUN) { + copyDirectory(demoDesktopBuildPath, demoDesktopTargetPath); + copyDirectory(demoMobileBuildPath, demoMobileTargetPath); + } + console.log("拷贝目录", demoDesktopBuildPath, "->", demoDesktopTargetPath); + console.log("拷贝目录", demoMobileBuildPath, "->", demoMobileTargetPath); +} +readdirSync(masterPath, { + recursive: true, + encoding: "utf-8", +}) + .filter(path => [".ts", ".tsx", ".js", ".jsx", ".md", ".mdx"].includes(extname(path))) + .forEach(path => { + const filePath = join(masterPath, path); + + if (!statSync(filePath).isFile()) { + return; + } + + const content = readFileSync(filePath, { encoding: "utf-8" }); + const regexDesktop = /https:\/\/smallmain\.github\.io\/cocos-enhance-kit\/demo\/(v\d+\.\d+\.\d+)\/web-desktop\/index\.html/g; + const regexMobile = /https:\/\/smallmain\.github\.io\/cocos-enhance-kit\/demo\/(v\d+\.\d+\.\d+)\/web-mobile\/index\.html/g; + + if (!DRYRUN) { + writeFileSync(filePath, content.replace(regexDesktop, `https://smallmain.github.io/cocos-enhance-kit/demo/${targetVersion}/web-desktop/index.html`).replace(regexMobile, `https://smallmain.github.io/cocos-enhance-kit/demo/${targetVersion}/web-mobile/index.html`)); + } + + if (regexDesktop.test(content) || regexMobile.test(content)) { + console.log("更新文件", filePath); + } + }); + + +// 上传到 Github Release +const tag = `v${kitVersion}`; +let releaseUrl = "(undefined)"; +const needPublish = await confirm({ + message: `是否上传至 Github Release？（请先在源码分支创建 '${tag}' Tag）`, + default: true, +}); +if (needPublish && !DRYRUN) { + + const octokit = new Octokit({ + auth: env.GITHUB_TOKEN, + }); + + console.log("创建 Release：", tag); + + let releaseId = 0; + try { + const { data } = await octokit.rest.repos.getReleaseByTag({ + owner: "smallmain", + repo: "cocos-enhance-kit", + tag: tag, + }); + releaseId = data.id; + releaseUrl = data.html_url; + } catch (error) { + const { data } = await octokit.rest.repos.createRelease({ + owner: "smallmain", + repo: "cocos-enhance-kit", + name: tag, + tag_name: tag, + body: `适配 Cocos Creator v${engineVersion} 版本\n\n> 注意，如果你需要使用模拟器预览，请按照官方的 [引擎定制文档](https://docs.cocos.com/creator/2.4/manual/zh/advanced-topics/engine-customization.html#25-%E7%BC%96%E8%AF%91%E6%A8%A1%E6%8B%9F%E5%99%A8) 重新编译原生模拟器。`, + prerelease: false, + make_latest: "legacy", + }); + releaseId = data.id; + releaseUrl = data.html_url; + } + + console.log("上传至 Release：", zipPath); + const fileContent = readFileSync(zipPath); + await octokit.rest.repos.uploadReleaseAsset({ + owner: "smallmain", + repo: "cocos-enhance-kit", + release_id: releaseId, + data: fileContent, + name: basename(zipPath), + headers: { + 'content-type': 'application/zip', + }, + }); +} +console.log("已发布到 Github Release：", tag); + +// 手动更新 Github Release 的更新日志 +if (needPublish) { + await confirm({ + message: `请前往 ${releaseUrl} 填写更新日志`, + default: true, + }); +} + +// 手动发布新版本文档 +await confirm({ + message: `请使用命令 npm run docusaurus docs:version 1.1.0 创建新版本文档，并在 docs 目录执行 npm run deploy 发布`, + default: true, +}); diff --git a/scripts/package.json b/scripts/package.json new file mode 100644 index 00000000..ce92faf7 --- /dev/null +++ b/scripts/package.json @@ -0,0 +1,24 @@ +{ + "name": "scripts", + "version": "1.0.0", + "description": "", + "main": "index.js", + "type": "module", + "author": "", + "license": "ISC", + "dependencies": { + "@inquirer/prompts": "^7.0.0", + "execa": "^9.4.1", + "graceful-fs": "^4.2.11", + "octokit": "^4.0.2", + "semver": "^7.6.3", + "ssh2": "^1.16.0", + "zip-lib": "^1.0.4" + }, + "devDependencies": { + "@types/graceful-fs": "^4.1.9", + "@types/node": "^20", + "@types/semver": "^7.5.8", + "@types/ssh2": "^1.15.1" + } +}