diff --git a/README.md b/README.md index a7b0e349..f924fd10 100644 --- a/README.md +++ b/README.md @@ -96,15 +96,23 @@ Label 一直是项目优化的最难点，因为它完全不能和其它的渲 现在在满足条件的情况下可以复用 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.github.io/cocos-enhance-kit/docs/intro)。 + ## 使用方法 -请阅读 [文档](https://smallmain.github.io/cocos-enhance-kit/docs/installation/installation-auto) 进行安装。 +请阅读文档的 [一键安装](https://smallmain.github.io/cocos-enhance-kit/docs/installation/installation-auto)。 ## 更新日志 diff --git a/docs/docs/best-practices/assets/settings-panel.png b/docs/docs/best-practices/assets/settings-panel.png new file mode 100644 index 00000000..872474b7 Binary files /dev/null and b/docs/docs/best-practices/assets/settings-panel.png differ diff --git a/docs/docs/best-practices/new-features.md b/docs/docs/best-practices/new-features.md index 249e37f2..2583a0bc 100644 --- a/docs/docs/best-practices/new-features.md +++ b/docs/docs/best-practices/new-features.md @@ -7,6 +7,14 @@ description: "了解并上手社区版提供的新特性。" 社区版添加了一些实用的新特性，帮助你更好地开发游戏。 +## 社区版设置面板 + +由于 v2.x 没有提供官方 API 往引擎原有的设置面板上添加设置项，所以我们另外增加了一个设置面板。 + +依次点击编辑器菜单项 **项目 - 社区版设置** 打开设置面板： + +![settings-panel](./assets/settings-panel.png) + ## 支持 SpriteFrame 给 Spine 换装 官方文档中介绍了替换 attachment 对象进行换装的方法，但如果动画中有切换 attachment 的关键帧，这种方法就失效了。 diff --git a/docs/docs/best-practices/performance-guide.md b/docs/docs/best-practices/performance-guide.md index e2b0ee64..96473a87 100644 --- a/docs/docs/best-practices/performance-guide.md +++ b/docs/docs/best-practices/performance-guide.md @@ -97,3 +97,9 @@ Spine 组件现在不仅可以参与动态合图，还能与其他渲染组件 社区版新增了在满足一定条件的情况下可以复用 Culling 数据的特性，以减少 CPU 的性能消耗。 可前往 [复用 Culling 数据](../user-guide/tiledmap/tiledmap-culling.md) 文档了解更多详情。 + +## 启用多线程支持 + +社区版为引擎的部分系统增加了多线程支持，启用后可以释放其对主线程的占用，减少卡顿现象。 + +详情请阅读文档：[多线程支持](../user-guide/multithread/thread-intro)。 diff --git a/docs/docs/breaking-change.md b/docs/docs/breaking-change.md index a1dd2176..6418545c 100644 --- a/docs/docs/breaking-change.md +++ b/docs/docs/breaking-change.md @@ -7,8 +7,7 @@ description: "一般情况下都不需要了解。" 在添加新特性的过程中，有些变化在所难免，你可以浏览本文档以进行评估是否会对项目造成影响。 ---- -### 默认禁用原生 TTF 渲染器 +## 默认禁用原生 TTF 渲染器 引擎的 Label 在使用 Char 缓存模式并且使用 TTF 字体时，会使用一个原生 TTF 渲染器。 @@ -22,8 +21,7 @@ description: "一般情况下都不需要了解。" cc.macro.ENABLE_NATIVE_TTF_RENDERER = false; ``` ---- -### 动态图集的一些变化 +## 动态图集的一些变化 对动态图集的重构虽然保留了所有原有的公开接口，但实现细节与以前不同了。 @@ -49,8 +47,7 @@ cc.macro.ENABLE_NATIVE_TTF_RENDERER = false; 比如你的项目依赖一些动态图集未公开的类或者接口（引擎在 `creator.d.ts` 声明了的则是已经公开的），则可能需要重新编写。 ---- -### Char 缓存模式的一些变化 +## Char 缓存模式的一些变化 对 Char 缓存模式也进行了重构，内部变化比较大。 @@ -62,8 +59,7 @@ cc.macro.ENABLE_NATIVE_TTF_RENDERER = false; 比如你的项目依赖一些 Char 缓存模式未公开的类或者接口（引擎在 `creator.d.ts` 声明了的则是已经公开的），则可能需要重新编写。 ---- -### 材质 Hash 计算的变化 +## 材质 Hash 计算的变化 在之前，材质的 Hash 发生变化时不会同时更新现有的材质变体 Hash，这导致在修改前创建的变体不能与修改后创建的变体合批（因为 Hash 不同）。 @@ -74,3 +70,12 @@ cc.macro.ENABLE_NATIVE_TTF_RENDERER = false; 比如你复制了一个 `multi-2d-sprite` 材质，分别使用这两个材质的组件不再会进行合批。 这种情况比较少见，如果你的项目发生了这种情况，可以手动将新材质的 Hash 值设置为旧材质的 Hash 值，即可让这两个材质合批。 + +## 启用多线程时的破坏性改动 + +### 资源管线 + +当你启用多线程驱动资源管线时，`cacheManager` 的接口有以下不同： + +- `getTemp` 方法被 `getTempAsync` 方法代替，请检查你项目中相关的用法。 +- 启用多线程之后，会使用多线程版的缓存管理器，如果你的项目访问了未暴露的内部属性，请检查相关的用法。 diff --git a/docs/docs/installation/installation-manual.md b/docs/docs/installation/installation-manual.md index b2499a5c..f5cc5e8a 100644 --- a/docs/docs/installation/installation-manual.md +++ b/docs/docs/installation/installation-manual.md @@ -74,3 +74,5 @@ description: "需掌握一定的自定义引擎知识。" ![installedconsole](./assets/installed-console.png) 接下来推荐你继续阅读文档中剩下的内容以了解你能够使用的新特性！ + +如果编辑器输出了一条有关包体大小的警告，请阅读 [多线程支持](../user-guide/multithread/thread-intro#注意事项) 了解详情。 diff --git a/docs/docs/intro.md b/docs/docs/intro.md index 887c0725..ddfa0b83 100644 --- a/docs/docs/intro.md +++ b/docs/docs/intro.md @@ -94,9 +94,13 @@ Label 一直是项目优化的最难点，因为它完全不能和其它的渲 现在在满足条件的情况下可以复用 Culling 数据，以减少项目 CPU 的性能消耗。 +### 多线程支持 + +现在，引擎的部分系统增加了多线程支持，启用后可以释放其对主线程的占用，减少卡顿现象。 + ## 使用方法 -请阅读文档的 [入门指南](TODO)。 +请阅读文档的 [一键安装](./installation/installation-auto)。 ## 贡献指南 diff --git a/docs/docs/user-guide/multithread/_category_.json b/docs/docs/user-guide/multithread/_category_.json new file mode 100644 index 00000000..7b25cc97 --- /dev/null +++ b/docs/docs/user-guide/multithread/_category_.json @@ -0,0 +1,9 @@ +{ + "label": "多线程支持", + "position": 6, + "collapsed": true, + "link": { + "type": "doc", + "id": "thread-intro" + } +} diff --git a/docs/docs/user-guide/multithread/assets/tap-a.png b/docs/docs/user-guide/multithread/assets/tap-a.png new file mode 100644 index 00000000..384e9159 Binary files /dev/null and b/docs/docs/user-guide/multithread/assets/tap-a.png differ diff --git a/docs/docs/user-guide/multithread/assets/tap-a2.png b/docs/docs/user-guide/multithread/assets/tap-a2.png new file mode 100644 index 00000000..b0f1af1b Binary files /dev/null and b/docs/docs/user-guide/multithread/assets/tap-a2.png differ diff --git a/docs/docs/user-guide/multithread/assets/thread-settings.png b/docs/docs/user-guide/multithread/assets/thread-settings.png new file mode 100644 index 00000000..4f971c6f Binary files /dev/null and b/docs/docs/user-guide/multithread/assets/thread-settings.png differ diff --git a/docs/docs/user-guide/multithread/thread-asset-pipeline.md b/docs/docs/user-guide/multithread/thread-asset-pipeline.md new file mode 100644 index 00000000..d4198746 --- /dev/null +++ b/docs/docs/user-guide/multithread/thread-asset-pipeline.md @@ -0,0 +1,18 @@ +--- +sidebar_position: 2 +description: "在多线程中执行资源管线。" +--- + +# 资源管线 + +依次点击编辑器的菜单项 **项目 - 社区版设置**，然后勾选 **多线程驱动资源管线**，即可启用这一特性。 + +启用后，资源的下载和缓存部分都会在 Worker 线程中执行，完全释放对主线程的占用。 + +![analysis](./assets/tap-a.png) + +![analysis-2](./assets/tap-a2.png) + +这是在 Android 设备上，对游戏帧耗时的分析图，可以看到红框部分的消耗消失了，降低了每帧的耗时。 + +在启用后，会有一些接口与之前不一样，请前往 [破坏性变更](../../breaking-change#资源管线) 查看详情。 diff --git a/docs/docs/user-guide/multithread/thread-audio-system.md b/docs/docs/user-guide/multithread/thread-audio-system.md new file mode 100644 index 00000000..ecb8e04d --- /dev/null +++ b/docs/docs/user-guide/multithread/thread-audio-system.md @@ -0,0 +1,16 @@ +--- +sidebar_position: 2 +description: "在多线程中操作音频。" +--- + +# 音频系统 + +依次点击编辑器的菜单项 **项目 - 社区版设置**，然后勾选 **多线程驱动音频系统**，即可启用这一特性。 + +启用后，音频的所有操作都会在 Worker 线程中执行，完全释放对主线程的占用。 + +:::danger 注意 + +该特性正在开发中，请勿启用。 + +::: diff --git a/docs/docs/user-guide/multithread/thread-intro.mdx b/docs/docs/user-guide/multithread/thread-intro.mdx new file mode 100644 index 00000000..3604e371 --- /dev/null +++ b/docs/docs/user-guide/multithread/thread-intro.mdx @@ -0,0 +1,71 @@ +import DocCardList from '@theme/DocCardList'; +import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; + +# 多线程支持 + +:::caution 注意 + +以下所有多线程特性暂时仅适用于微信小游戏平台。 + +::: + +社区版为引擎的部分系统增加了多线程支持，启用后可以释放其对主线程的占用，减少卡顿现象。 + +你可以在社区版的设置面板启用多线程支持： + +![thread-settings](./assets/thread-settings.png) + +## 使用代码调整设置 + +你可以使用 [构建模板](https://docs.cocos.com/creator/2.4/manual/zh/publish/custom-project-build-template.html) 在 `game.js` 的 `__globalAdapter.init();` 语句执行之前声明宏来调整设置： + +- CC_WORKER_ASSET_PIPELINE（是否启用 Worker 驱动资源管线） +- CC_WORKER_AUDIO_SYSTEM（是否启用 Worker 驱动音频系统） +- CC_WORKER_DEBUG（是否启用 Worker 调试模式） + +例如这样： + +```js +// game.js +require('adapter-js-path'); +// --- 在 init 执行之前设置 --- +globalThis.CC_WORKER_ASSET_PIPELINE = isAndroid; +// -------------------------- +__globalAdapter.init(); +``` + +当 `init` 执行之后，由于引擎已经初始化完毕，就不能再对设置进行修改了。 + +## 注意事项 + +当你重启编辑器，或者启用/禁用多线程支持时，可能出现以下几种情况： + +**禁用多线程支持时输出的包体大小警告：** + +由于要实现多线程支持，社区版在包体内增加了一个 `workers` 目录，用于存放 Worker 线程的代码。 + +大小有 `30-50KB` 左右，当你禁用多线程时，这个目录可以被删除以减少包体。 + +具体流程如下： + +- 点击编辑器界面右上角的 **编辑器** 按钮，并跳转到 `Resources/builtin/adapters/platforms/wechat/res` 目录。 +- 删除该目录下的 `workers` 目录。 +- 打开该目录下的 `game.json`，删除 `workers` 字段并保存。 + +**启用多线程支持时输出的检测错误：** + +这是由于你按照上面的步骤删除了多线程所需的文件和配置，所以无法启用多线程支持，只需恢复或者重新安装完整的社区版即可。 + +:::tip 注意 + +**如果你正在使用付费扩展，则无需手动删除或重新安装，也不会输出任何警告或者错误。** + +因为付费扩展会存储已安装版本的备份文件，所以能够自动删除或重新安装。 + +如果付费扩展依然输出错误则可能是文件损坏，重新一键安装即可。 + +::: + +阅读下面的文档了解详情： + +