From b24154528741de71d13c154fa47ce8601c268f07 Mon Sep 17 00:00:00 2001 From: SmallMain Date: Wed, 22 Jun 2022 16:56:14 +0800 Subject: [PATCH] =?UTF-8?q?=E5=AF=B9=E6=96=87=E6=A1=A3=E8=BF=9B=E8=A1=8C?= =?UTF-8?q?=E6=B6=A6=E8=89=B2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README-DEV.md | 2 +- README.md | 64 ++++++++----------- .../installation-engine-plugin.md | 31 ++++----- .../installation-guide/installation-intro.mdx | 2 +- .../installation-guide/installation-manual.md | 10 +-- docs/docs/intro.md | 59 +++++++---------- docs/docs/start-guide/batcher-guide.md | 58 ++++++++--------- docs/docs/start-guide/breaking-change.md | 8 +-- docs/docs/start-guide/new-features.md | 4 +- docs/docs/start-guide/start-guide-intro.mdx | 4 +- docs/docs/uninstall-guide.md | 14 ++-- docs/docs/user-guide/user-guide-intro.mdx | 2 +- 12 files changed, 110 insertions(+), 148 deletions(-) diff --git a/README-DEV.md b/README-DEV.md index d4ac4fa7..3afc66bf 100644 --- a/README-DEV.md +++ b/README-DEV.md @@ -32,7 +32,7 @@ ### 准备压缩包 1.将对 engine 的改动整合到 Git Patch，然后将 Patch 按相应的引擎目录放置在仓库的 `patches` 目录中，并放在压缩包根目录内。 -2.将引擎放到压缩包根目录内（需保证去除了忽略文件），包括类型提示文件。 +2.将三个引擎目录放到压缩包根目录内，包括类型提示文件。 3.将 `service-pack-support` 目录放在压缩包根目录内。 4.更新文档的更新日志。 diff --git a/README.md b/README.md index d2dd6397..98d8ecfd 100644 --- a/README.md +++ b/README.md @@ -2,27 +2,23 @@ ![logo](/docs/static/img/logo2.png) -> 该项目当前为内部预览版，还在完善中，还未适配原生平台（cocos2d-x、jsb-adapter） +> 该项目当前为内部预览版，只提供未适配原生平台（cocos2d-x、jsb-adapter）的 Cocos Creator v2.4.5 版本 -这是一个对 Cocos Creator 引擎进行特性增强、修复与优化的**开源非官方服务包（Service Pack）**。 +这是一个提供 Cocos Creator 引擎特性增强、修复与优化的**开源非官方服务包**。 -该项目尽量以最符合原始架构设计的方式为引擎加入新的特性、修复已知问题以及优化性能。 +该项目使用自定义引擎的方式在符合原始引擎架构设计的基础上为 Cocos Creator 引擎加入新的特性、修复已知问题以及性能优化。 -正因为如此，大部分项目使用这个服务包就像升级引擎版本一样简单。 +正因为如此，服务包中的大部分特性能像升级引擎版本一样无需改动项目代码即可生效。
> 项目的起源 > ->2021 年 2 月，Cocos 发布 Cocos Creator 3.0，并在 3.x 发布之后不会再继续开发 2.x 版本的新特性，所有维护工作也会在 2023 年完全停止。 +>2021 年 2 月，Cocos 发布 Cocos Creator 3.0，之后不会再开发 2.x 版本的新特性，但 2.x 在一些方面还并不完善，所以这个非官方的引擎“魔改”合集应运而生。 > ->但是 2.x 在一些方面还并不完善，所以这个非官方的引擎“魔改”合集的开源项目应运而生。 +>给项目取名的时候想到相似的事情发生在 2014 年 4 月，官方停止了对 Windows XP 的维护，之后 Harkaz 发布了一个非官方服务包 Service Pack 4 (SP4)。 > ->相似的事情发生在 2014 年 4 月，官方停止了对 Windows XP 的维护，之后 Harkaz 发布了一个非官方服务包 Service Pack 4 (SP4)。 -> ->受到 Windows XP 命名的启发，这个非官方的引擎“魔改”合集取名为 Service Pack。 -> ->Service Pack 暂时只适配 Cocos Creator 2.x 版本，Cocos Creator 3.x 正在蒸蒸日上，其引擎架构还在不断地迭代（不稳定），若对其进行修改，之后的维护工作会非常大。 +>受到这个命名的启发，遂项目取名为 Service Pack。
@@ -38,6 +34,7 @@ - [贡献指南](#贡献指南) - [常见问题](#常见问题) - [为什么要直接修改引擎？](#为什么要直接修改引擎) + - [启动 Cocos Creator 报 Error: Can not parse this input:undefined 错误](#启动-cocos-creator-报-error-can-not-parse-this-inputundefined-错误) @@ -49,22 +46,17 @@ - **重构 Label 组件的 CHAR 缓存模式**（支持自动多纹理合批、多图集、复用废弃空间等特性） - **Spine 组件支持与其它组件合批、合入动态图集与 SpriteFrame 换装** -> 服务包对引擎的所有改动都是开源的，并且每个改动都会附上一篇原理说明的文档，当你发现问题时请进行反馈，或者直接默默地帅气地提交一个 PR，帮助我们一起完善这个项目。 +> 服务包对引擎的改动完全开源，每个改动会带有原理说明文档，当你发现问题时请与我们进行反馈，如果你有兴致，可以默默帅气地提交一个 PR，帮助我们一起完善这个项目。 ## 功能演示 [Web Desktop 演示项目](https://smallmain.github.io/cocos-service-pack/demo/v1.0.0-alpha/web-desktop/index.html) -[Web Mobile 演示项目](https://smallmain.github.io/cocos-service-pack/demo/v1.0.0-alpha/web-mobile/index.html) +[Web Mobile 演示项目](https://smallmain.github.io/cocos-service-pack/demo/v1.0.0-alpha/web-mobile/index.html)（请将设备横屏） ## 使用方法 -服务包通过自定义引擎的方式来修改引擎代码，你可以： - -- 通过我们发布的引擎扩展一键安装 -- 下载源码包进行手动安装 - -具体教程可以参考 [安装指南](https://smallmain.github.io/cocos-service-pack/docs/installation-guide/installation-intro)。 +请阅读文档的 [安装指南](https://smallmain.github.io/cocos-service-pack/docs/installation-guide/installation-intro) 与 [入门教程](https://smallmain.github.io/cocos-service-pack/docs/start-guide/start-guide-intro)。 ## 更新日志 @@ -81,40 +73,36 @@ - [修复] CHAR 缓存模式 hash 计算可能会有重复的问题 - [调整] 默认禁用 Label 原生 TTF 渲染器 -所有更新日志请移步 [此处](https://smallmain.github.io/cocos-service-pack/docs/update-log)。 +[点此](https://smallmain.github.io/cocos-service-pack/docs/update-log) 查看所有的更新日志。 ## 贡献指南 -非常欢迎你能和我们一起来完善这个项目，所有的一切都通过 Github 进行： +非常欢迎你能和我们一起来完善这个项目，请通过 Github 进行： -- 如果你有问题或者好的想法，请建立 `Issues` 或进入 `Discussions` 。 -- 如果你有新的代码提交，请建立 `Pull requests`。 +- 如果你发现了问题请建立 `Issues` +- 如果你有好的想法，请进入 `Discussions` +- 如果你有新的代码提交，请建立 `Pull requests` -原则上允许对引擎的任何增强与修改，但是**任何修改都必须兼容引擎原有的特性，不允许删除引擎原有的特性**，并且请认真思考代码设计。 +**原则上你提交的任何修改都不能影响引擎原有功能，不允许删除引擎原有的特性，请认真思考代码设计。** ## 常见问题 ### 为什么要直接修改引擎？ -直接修改引擎可能是大部分人认为的下下策，比如我们常听到的一些声音： +直接修改引擎可能是大部分人认为的下下策，比如我们常听到的： -- 通过 “修改对象的原型” 等一些编程技巧做成一个插件脚本 -- 没接触过自定义引擎，不知道该怎么用，感觉很可怕 -- 我已经修改过引擎的某些部分了，不能直接安装 +- 可以通过 “修改对象原型” 等编程技巧将改动做成一个插件脚本 +- 没接触过自定义引擎，不知道该如何使用 +- 已经修改过引擎了，不能直接进行标准安装，会覆盖原有的修改 -以上问题我们都思考过， +以上问题我们都思考过，首先，现在引擎的 2.x 版本已经停止了更新（仅做一些维护工作），也就是说修改引擎不会遇到在官方新版本发布后需要用大量时间去适配的情况。 -首先，现在引擎的 2.x 版本已经停止了更新（仅做一些维护工作），也就是说修改引擎不会遇到在官方新版本发布后需要用大量时间去适配的情况。 +其次，即使服务包的所有改动都能做成一个插件脚本，但无法兼容原生平台，并且一般都需要大量拷贝代码，包体会增大，可维护性会大幅降低。 -其次，即使服务包中的所有改动都能做成一个插件脚本，但是无法兼容原生平台，并且一般都需要大量拷贝代码，包体会增大，可维护性可能会大幅降低。 +最后，我们希望它接近 “原生” 的使用体验，就像引擎本来就有的功能一样，对于没有接触过自定义引擎的人，可以通过引擎扩展一键安装。 -最后，我们希望它接近 “原生” 的使用体验，就像引擎本来就有的功能一样，对于没有接触过自定义引擎的人，我们提供的引擎扩展可以一键安装。 +对于已经修改过引擎的人，由于服务包提供的是 Git Patch，所以可以让你在原有的基础上轻松应用服务包的改动，你甚至可以只选取你想要的特性进行应用。 -对于已经修改过引擎的人，由于服务包提供的是 Git Patch，所以可以让你在已有修改的基础上轻松应用上服务包的改动，甚至你可以只应用你想要的特性。 - -### Cocos Creator 报 Error: Can not parse this input:undefined 错误 +### 启动 Cocos Creator 报 Error: Can not parse this input:undefined 错误 没有找到服务包的内置资源，请记得安装配套的引擎扩展。 - ---- -**最后的最后，希望这个项目能帮助到你的学习或工作，enjoy！** diff --git a/docs/docs/installation-guide/installation-engine-plugin.md b/docs/docs/installation-guide/installation-engine-plugin.md index 8e0c7a69..fd191bf6 100644 --- a/docs/docs/installation-guide/installation-engine-plugin.md +++ b/docs/docs/installation-guide/installation-engine-plugin.md @@ -8,26 +8,21 @@ description: "推荐使用此方式进行一键安装。" --- ## 前往 Cocos Store 下载 -**这个扩展唯一的作用就是帮助你管理服务包的版本（查看已安装版本、安装、卸载）。** - 在 Cocos Store 搜索名为 **Cocos Service Pack** 的引擎扩展，或者 [点此跳转](pathname://TODO)。 -你需要花费 ¥13.14 下载并安装这个扩展。 - +这个扩展不是免费的，**但其唯一的作用就是帮助你管理服务包的版本（查看已安装版本、安装、卸载）。** :::tip 常见问题 - **Service Pack 不是开源项目吗？？？** - Service Pack 是完全开源的项目，涉及到引擎的每个修改我们都开放源码并提供原理文档。 + Service Pack 是完全开源的项目，这个引擎扩展只会为你提供自动化的安装方式，以后也只会有版本管理方面的功能。 - 这个引擎扩展只会为你提供自动化的安装方式，即使以后也只会添加版本管理方面的功能。 - - 你可以选择这里的 [手动安装](./installation-manual.md)，也只需要几分钟即可完成。 + 你可以选择 [手动安装](./installation-manual.md)，也只需要几步即可完成。 - **如何反馈有关这个扩展的问题或建议** - 若遇到与这个扩展相关的问题或者建议，请不要在 Cocos Service Pack 的仓库反馈，而是在扩展的 **商店评论区** 进行反馈。 + 若遇到与这个扩展相关的问题或者建议，不要在服务包的 Github 仓库反馈，请在扩展的 **商店评论区** 进行反馈。 因为这个扩展的收益是个人的，所以也只由个人维护。 @@ -36,19 +31,19 @@ description: "推荐使用此方式进行一键安装。" --- ## 一键安装 -在 Cocos Creator 的菜单栏依次点击 **扩展 - 服务包管理**，会弹出服务包管理界面。 +安装好扩展后，在 Cocos Creator 的菜单栏依次点击 **扩展 - 服务包管理**，会弹出服务包管理界面。 ![plugin-ui](./assets/plugin-ui.png) -如果是支持的引擎版本，**安装服务包** 的按钮会亮起，点击之后重启编辑器即完成安装。 +如果是支持的引擎版本，**安装服务包** 的按钮会亮起，点击之后等待安装完成，完成后重启编辑器即可。 :::note 扩展做了什么事 -扩展会自动修改项目的自定义引擎路径，并替换 `jsb-adapter`，在项目根目录放置 `creator.d.ts` 文件。 +扩展帮您自动完成了手动安装时需要做的所有步骤，包括自定义引擎和放置 TypeScript 类型提示文件。 ::: -可在项目预览时检查 Devtools Console 打印的是否为 `Cocos Creator SP v2.4.x`，是的话则已经成功安装。 +预览项目并检查 Devtools Console 打印的是否为 `Cocos Creator SP v2.4.x`，是的话则已经成功安装。 ![installedconsole](./assets/installed-console.png) @@ -57,13 +52,15 @@ description: "推荐使用此方式进行一键安装。" --- ## 支持的引擎版本 -服务包每次的版本更新都只会发布最新版本的引擎压缩包，而这个扩展会额外适配其他引擎版本并内置在扩展里。 +服务包只会适配引擎的最新版本，如果需要在其它引擎版本上安装服务包，一般需要使用 Git Patch。 + +而这个扩展会额外适配其他引擎版本，让你可以在更多版本的引擎上一键安装。 **该扩展至少会维护两个 Cocos Creator 版本，分别是 v2.4.6 与最新版本。** -选择维护这两个版本是因为在 v2.4.7 这个版本出现了破坏性变更，而 v2.4.7 也正好是官方开始暂停新特性开发，只进行维护的版本。 +选择维护这两个版本是因为在 v2.4.7 这个版本出现了破坏性变更，也是官方开始暂停新特性开发只进行维护的版本。 也就是说： -- 项目如果是使用小于 v2.4.7 版本的引擎可以完全无痛升级至 v2.4.6。 -- 项目如果是使用大于等于 v2.4.7 版本的引擎可以完全无痛升级至最新版。 +- 项目使用 < v2.4.7 版本的引擎可以完全无痛升级至 v2.4.6。 +- 项目使用 >= v2.4.7 版本的引擎可以完全无痛升级至最新版。 diff --git a/docs/docs/installation-guide/installation-intro.mdx b/docs/docs/installation-guide/installation-intro.mdx index 4e172375..6a30e820 100644 --- a/docs/docs/installation-guide/installation-intro.mdx +++ b/docs/docs/installation-guide/installation-intro.mdx @@ -5,7 +5,7 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; 服务包主要使用 [自定义引擎](https://docs.cocos.com/creator/2.4/manual/zh/advanced-topics/engine-customization.html) 的方式对引擎进行修改。 -但是，由于自定义引擎并不能添加内置资源与扩展组件的 inspector，所以还需要一点额外的步骤。 +但由于自定义引擎不能添加内置资源与扩展内置组件的 Inspector，所以还需要安装配套的引擎扩展。 对于使用 TypeScript 的项目，服务包提供了 `creator-sp.d.ts` 类型提示文件。 diff --git a/docs/docs/installation-guide/installation-manual.md b/docs/docs/installation-guide/installation-manual.md index dcaf54c0..612663d2 100644 --- a/docs/docs/installation-guide/installation-manual.md +++ b/docs/docs/installation-guide/installation-manual.md @@ -12,10 +12,7 @@ description: "需掌握一定的自定义引擎知识。" --- ## 标准安装 -请确保您的项目符合以下条件，否则请使用 [补丁安装](#补丁安装)。： - -- **项目所使用的引擎版本与服务包适配的引擎版本一致** -- **项目未使用自定义引擎** +**请确保您的项目所使用的引擎版本与服务包适配的引擎版本一致，否则请使用 [补丁安装](#补丁安装)。** :::tip 提示 @@ -29,13 +26,12 @@ description: "需掌握一定的自定义引擎知识。" 下载服务包后，解压压缩包可以看到压缩包内的 `engine` `cocos2d-x` `jsb-adapter` 这三个目录分别是已经整理好的 **JavaScript 引擎**、**Cocos2d-x 引擎** 和 **jsb-adpater**。 -打开 Cocos Creator 菜单的 **项目 - 项目设置 - 自定义引擎**。 +接着打开 Cocos Creator 菜单的 **项目 - 项目设置 - 自定义引擎**。 分别填写 **JavaScript 引擎路径**（对应 `engine` 目录）和 **Cocos2d-x 引擎路径**（对应 `cocos2d-x` 目录）。 ![custom-engine](./assets/custom-engine.png) - 然后点击 Cocos Creator 主界面右上角的 **编辑器** 按钮，进入到编辑器的资源目录。 ![ide-cocos-path](./assets//ide-cocos-path.png) @@ -46,7 +42,7 @@ description: "需掌握一定的自定义引擎知识。" 如果你的项目不需要在原生平台上运行，则只定制 JavaScript 引擎即可。 -如果你的项目需要在原生模拟器中预览，可能需要重新编译模拟器，更多详情可阅读官方的 [自定义引擎](https://docs.cocos.com/creator/2.4/manual/zh/advanced-topics/engine-customization.html) 文档。 +如果你的项目需要在原生模拟器中预览，可能需要编译模拟器，更多详情可阅读官方的 [自定义引擎](https://docs.cocos.com/creator/2.4/manual/zh/advanced-topics/engine-customization.html) 文档。 ::: diff --git a/docs/docs/intro.md b/docs/docs/intro.md index 21e679b0..c5687aaf 100644 --- a/docs/docs/intro.md +++ b/docs/docs/intro.md @@ -6,22 +6,20 @@ hide_title: true ![logo](/img/logo2.png) -这是一个对 Cocos Creator 引擎进行特性增强、修复与优化的**开源非官方服务包（Service Pack）**。 +这是一个提供 Cocos Creator 引擎特性增强、修复与优化的**开源非官方服务包**。 -该项目尽量以最符合原始架构设计的方式为引擎加入新的特性、修复已知问题以及优化性能。 +该项目使用自定义引擎的方式在符合原始引擎架构设计的基础上为 Cocos Creator 引擎加入新的特性、修复已知问题以及性能优化。 -正因为如此，大部分项目使用这个服务包就像升级引擎版本一样简单。 +正因为如此，服务包中的大部分特性能像升级引擎版本一样无需改动项目代码即可生效。 :::info 项目的起源 -2021 年 2 月，Cocos 发布 Cocos Creator 3.0，并在 3.x 发布之后不会再继续开发 2.x 版本的新特性，所有维护工作也会在 2023 年完全停止。 -但是 2.x 在一些方面还并不完善，所以这个非官方的引擎“魔改”合集的开源项目应运而生。 +2021 年 2 月，Cocos 发布 Cocos Creator 3.0，之后不会再开发 2.x 版本的新特性，但 2.x 在一些方面还并不完善，所以这个非官方的引擎“魔改”合集应运而生。 -相似的事情发生在 2014 年 4 月，官方停止了对 Windows XP 的维护，之后 Harkaz 发布了一个非官方服务包 Service Pack 4 (SP4)。 +给项目取名的时候想到相似的事情发生在 2014 年 4 月，官方停止了对 Windows XP 的维护，之后 Harkaz 发布了一个非官方服务包 Service Pack 4 (SP4)。 -受到 Windows XP 命名的启发，这个非官方的引擎“魔改”合集取名为 Service Pack。 +受到这个命名的启发，遂项目取名为 Service Pack。 -Service Pack 暂时只适配 Cocos Creator 2.x 版本，Cocos Creator 3.x 正在蒸蒸日上，其引擎架构还在不断地迭代（不稳定），若对其进行修改，之后的维护工作会非常大。 ::: ## 重要特性 @@ -34,7 +32,7 @@ Service Pack 暂时只适配 Cocos Creator 2.x 版本，Cocos Creator 3.x 正在 :::note 提示 -服务包对引擎的所有改动都是开源的，并且每个改动都会附上一篇原理说明的文档，当你发现问题时请进行反馈，或者直接默默地帅气地提交一个 PR，帮助我们一起完善这个项目。 +服务包对引擎的改动完全开源，每个改动会带有原理说明文档，当你发现问题时请与我们进行反馈，如果你有兴致，可以默默帅气地提交一个 PR，帮助我们一起完善这个项目。 ::: @@ -42,16 +40,11 @@ Service Pack 暂时只适配 Cocos Creator 2.x 版本，Cocos Creator 3.x 正在 [Web Desktop 演示项目](https://smallmain.github.io/cocos-service-pack/demo/v1.0.0-alpha/web-desktop/index.html) -[Web Mobile 演示项目](https://smallmain.github.io/cocos-service-pack/demo/v1.0.0-alpha/web-mobile/index.html) +[Web Mobile 演示项目](https://smallmain.github.io/cocos-service-pack/demo/v1.0.0-alpha/web-mobile/index.html)（请将设备横屏） ## 使用方法 -服务包通过自定义引擎的方式来修改引擎代码，你可以： - -- 通过我们发布的引擎扩展一键安装 -- 下载源码包进行手动安装 - -具体教程可以参考 [安装指南](./installation-guide/installation-intro.mdx)。 +请阅读文档的 [安装指南](./installation-guide/installation-intro.mdx) 与 [入门教程](./start-guide/start-guide-intro.mdx)。 ## 更新日志 @@ -68,40 +61,36 @@ Service Pack 暂时只适配 Cocos Creator 2.x 版本，Cocos Creator 3.x 正在 - [修复] CHAR 缓存模式 hash 计算可能会有重复的问题 - [调整] 默认禁用 Label 原生 TTF 渲染器 -所有更新日志请移步 [此处](./update-log.md)。 +[点此](https://smallmain.github.io/cocos-service-pack/docs/update-log) 查看所有的更新日志。 ## 贡献指南 -非常欢迎你能和我们一起来完善这个项目，所有的一切都通过 Github 进行： +非常欢迎你能和我们一起来完善这个项目，请通过 Github 进行： -- 如果你有问题或者好的想法，请建立 `Issues` 或进入 `Discussions` 。 -- 如果你有新的代码提交，请建立 `Pull requests`。 +- 如果你发现了问题请建立 `Issues` +- 如果你有好的想法，请进入 `Discussions` +- 如果你有新的代码提交，请建立 `Pull requests` -原则上允许对引擎的任何增强与修改，但是**任何修改都必须兼容引擎原有的特性，不允许删除引擎原有的特性**，并且请认真思考代码设计。 +**原则上你提交的任何修改都不能影响引擎原有功能，不允许删除引擎原有的特性，请认真思考代码设计。** ## 常见问题 ### 为什么要直接修改引擎？ -直接修改引擎可能是大部分人认为的下下策，比如我们常听到的一些声音： +直接修改引擎可能是大部分人认为的下下策，比如我们常听到的： -- 通过 “修改对象的原型” 等一些编程技巧做成一个插件脚本 -- 没接触过自定义引擎，不知道该怎么用，感觉很可怕 -- 我已经修改过引擎的某些部分了，不能直接安装 +- 可以通过 “修改对象原型” 等编程技巧将改动做成一个插件脚本 +- 没接触过自定义引擎，不知道该如何使用 +- 已经修改过引擎了，不能直接进行标准安装，会覆盖原有的修改 -以上问题我们都思考过， +以上问题我们都思考过，首先，现在引擎的 2.x 版本已经停止了更新（仅做一些维护工作），也就是说修改引擎不会遇到在官方新版本发布后需要用大量时间去适配的情况。 -首先，现在引擎的 2.x 版本已经停止了更新（仅做一些维护工作），也就是说修改引擎不会遇到在官方新版本发布后需要用大量时间去适配的情况。 +其次，即使服务包的所有改动都能做成一个插件脚本，但无法兼容原生平台，并且一般都需要大量拷贝代码，包体会增大，可维护性会大幅降低。 -其次，即使服务包中的所有改动都能做成一个插件脚本，但是无法兼容原生平台，并且一般都需要大量拷贝代码，包体会增大，可维护性可能会大幅降低。 +最后，我们希望它接近 “原生” 的使用体验，就像引擎本来就有的功能一样，对于没有接触过自定义引擎的人，可以通过引擎扩展一键安装。 -最后，我们希望它接近 “原生” 的使用体验，就像引擎本来就有的功能一样，对于没有接触过自定义引擎的人，我们提供的引擎扩展可以一键安装。 +对于已经修改过引擎的人，由于服务包提供的是 Git Patch，所以可以让你在原有的基础上轻松应用服务包的改动，你甚至可以只选取你想要的特性进行应用。 -对于已经修改过引擎的人，由于服务包提供的是 Git Patch，所以可以让你在已有修改的基础上轻松应用上服务包的改动，甚至你可以只应用你想要的特性。 - -### Cocos Creator 报 Error: Can not parse this input:undefined 错误 +### 启动 Cocos Creator 报 Error: Can not parse this input:undefined 错误 没有找到服务包的内置资源，请记得安装配套的引擎扩展。 - ---- -**最后的最后，希望这个项目能帮助到你的学习或工作，enjoy！** diff --git a/docs/docs/start-guide/batcher-guide.md b/docs/docs/start-guide/batcher-guide.md index 4fdba7e5..6c90654d 100644 --- a/docs/docs/start-guide/batcher-guide.md +++ b/docs/docs/start-guide/batcher-guide.md @@ -5,9 +5,11 @@ description: "在游戏开发中享受不用关注 Draw Call 的快乐。" # 新 UI 渲染批次合并指南 -在官方文档的进阶主题中，有一个 [UI 渲染批次合并指南](https://docs.cocos.com/creator/2.4/manual/zh/advanced-topics/ui-auto-batch.html)，在服务包的 **多纹理渲染**、**重构动态图集** 等新特性的出现后，对如何合并渲染批次需要有全新的理解。 +在官方文档的进阶主题中有一个 [UI 渲染批次合并指南](https://docs.cocos.com/creator/2.4/manual/zh/advanced-topics/ui-auto-batch.html)，批次合并一直是游戏开发中重要的优化手段，如果你未阅读过官方的指南，可以先阅读一遍。 + +当 **多纹理渲染**、**新动态图集** 等特性出现后，在进行批次合并时可以变得更加简单且自动化。 + -如果你未阅读过官方的指南，可以先阅读一遍。 --- ## 什么是多纹理渲染？ @@ -16,13 +18,13 @@ description: "在游戏开发中享受不用关注 Draw Call 的快乐。" 其根本原因是纹理是使用 uniform 变量传给着色器的，而需要合并批次的话不允许每次渲染都拥有不同的 uniform 变量值。 -服务包实现的合批方法是先设置好多个 uniform 变量，比如将 8 张纹理写入到 "texture1" "texture2" "texture3"... 的 8 个 uniform 变量中，然后在着色器里再判断应该在渲染时使用哪个 uniform 变量。 +服务包实现的是先设置多个 uniform 变量，比如将 8 张纹理写入到 "texture1" "texture2" "texture3"... 的 8 个 uniform 变量中，然后在着色器里再判断应该在渲染时使用哪个 uniform 变量。 -这样的话如果所有渲染都只用这 8 张纹理的话，就都能合并为 1 个批次。 +这样的话如果所有渲染都只用这 8 张纹理，就都能合并为 1 个批次。 -这种做法要求设备需要支持采样多个纹理，而在现代绝大多数设备中这不是问题，至少都支持采样 8 张纹理。 +这要求设备支持采样多个纹理，而在现代绝大多数设备中都至少支持采样 8 张纹理，所以这不是问题。 -当然除了这种方法，还有另外几种进行多纹理合批的方法，例如 "Texture Array"、"Bindless"，但都有实用性与兼容性的问题。 +当然除了这种方法，还有另外几种进行多纹理合批的方法，例如 "Texture Array" 和 "Bindless"，但都有实用性与兼容性的问题。 :::info 提示 @@ -32,48 +34,48 @@ description: "在游戏开发中享受不用关注 Draw Call 的快乐。" 所以我们建议在多个档次设备中实际测试项目是否使用多纹理渲染的性能差距。 -如果你还有所担心，就像我们在实现这个功能之前一样，可以看看这些： +如果你对这种技术有所担心，可以看看这些： -**PixiJS 引擎在 2016 年发布的 v4 版本就已经正式实装了多纹理渲染机制！**[资料出处](https://medium.com/goodboy-digital/gpu-multi-texture-sprite-batching-21c90ae8f89b)。 +**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)。 ::: --- -## 为你的项目启用动态合图 +## 启用动态合图 -在项目之前的开发中，我们通常会关闭动态图集，更倾向于靠静态图集或者自动图集达到降低 Draw Call 的目的。 +在之前的开发中我们通常会关闭动态图集，更倾向于靠静态图集或者自动图集达到降低 Draw Call 的目的。 -导致这个情况最重要的问题是不能复用图集的废弃区域，随着游戏的运行图集会完全用完，引擎只提供了在切换场景（Scene）后重置所有图集的机制来解决这个问题。 +不使用动态图集最重要的原因是其不能复用图集的废弃区域，随着游戏的运行动态图集会完全用完。 -但对于大部分项目来说，这种治标不治本的机制基本等于没有解决这个问题。 +引擎只提供了在切换场景（Scene）后重置所有图集的机制来解决这个问题，但对于大部分项目来说，这种治标不治本的机制基本等于没有解决。 -现在，服务包几乎重构了整个动态合图系统，你可以考虑启用它了。 +现在，服务包几乎重构了整个动态合图系统，你可以考虑重新启用动态合图了。 :::note 提示 开启动态图集常见的反对意见是： -在部分小游戏平台里，启用动态图集会有保留 Image 对象所占用的内存空间很大的问题。 +在部分小游戏平台里，启用动态图集会有保留 Image 对象导致内存占用大的问题。 -我们建议： +建议： -- 请实际测试是否启用动态图集的内存占用差距。 -- 有没有一种可能，只是说可能，出现不能接受的内存占用大小是因为你的项目根本就不做任何资源的释放呢？ +- 实际测试是否启用动态图集的内存占用差距。 +- 有没有一种可能，只是说可能，内存占用大更多是因为你的项目根本没做任何资源释放呢？ ::: --- ## 充分利用动态合图 -下面几个建议能让你发挥出动态合图的潜力： +一般情况下只需要保持动态图集的默认设置即可，如果出现动态图集很多纹理不会打入或者图集很快用完的情况，可以参考以下建议调整。 ### 放宽能参与合图的纹理尺寸限制 **动态图集会自动进行多纹理合批，你可以放心地使用多达 7 张图集而不用担心交叉渲染导致的打断批次！** -有了这个新特性，你可以根据项目的具体情况来放宽能参与合图的纹理尺寸限制。 +你可以根据项目的具体情况来放宽能参与合图的纹理尺寸限制。 ```js cc.dynamicAtlasManager.maxFrameSize = 1024; // 推荐 512、1024 甚至 2048 @@ -89,36 +91,34 @@ cc.dynamicAtlasManager.maxFrameSize = 1024; // 推荐 512、1024 甚至 2048 **动态合图会在纹理被释放的同时释放其在动态图集使用的空间。** -有了这个新特性，你不需要关心动态图集，只需要做好应有的资源释放，就能保持动态图集的长期有效。 +如果动态图集的使用量一直在增长，请检查是否做了资源释放，因为你不需要关心动态图集的使用情况，只需要做好应有的资源释放就能保持动态图集的长期有效。 ### 更加细致地优化图集的使用效率 -除了通过调整纹理的 `packable` 属性可以控制纹理是否会参与动态合图之外。 - -**还可以控制组件是否默认参与动态合图，也可以控制单个组件是否参与动态合图。** +除了通过调整纹理的 `packable` 属性可以控制纹理是否会参与动态合图之外，服务包提供了**控制组件是否默认参与动态合图，控制单个组件是否参与动态合图**的新特性。 可前往 [动态合图](../user-guide/dynamic-batcher/dynamic-batcher-intro.mdx) 的文档了解详情。 -在上面我们推荐可以将纹理尺寸限制放宽到 `2048`，这听起来貌似有点离谱，但只要规划得当确实可行，比如： +你可以考虑将纹理尺寸限制放宽到 `2048`，这听起来貌似有点离谱，但只要规划得当确实可行，比如： - 禁止优化程度有限但尺寸巨大的纹理参与动态合图 - 分模块存放资源，禁止冷门（如活动界面）的纹理参与动态合图或尽早地释放掉 -- 在资源已经一团糟的项目中，可通过代码禁止某个界面下所有的渲染组件参与动态合图 +- 在资源太多的项目中，可考虑控制界面的渲染组件是否参与动态合图 完成上面几点这可能需要一些工作量，但能将动态图集用在刀刃上，发挥更大的作用。 --- ## Label 不再是合批噩梦 -在项目之前的开发中，我们可能会使用字体图集、调整节点顺序，甚至修改渲染流程来解决 Label 的性能问题。 +在之前的开发中我们可能会使用字体图集、调整节点顺序、甚至修改渲染流程来解决 Label 的性能问题。 -引擎提供的 Bitmap 和 Char 两种缓存模式在稍大一点的项目上就显得力所不及了： +也是因为引擎提供的 Bitmap 和 Char 两种缓存模式在稍大一点的项目上显得力所不及： - Bitmap 缓存模式：字体纹理会打入动态图集，但动态图集却无法复用，随着游戏的进行，图集用完则直接失去作用。 - Char 缓存模式的缺点：还是无法复用，并且只有一张图集，图集用完则直接无法渲染，应该没人能接受游戏可能跑着跑着字就全部消失了的情况。 -但，**服务包重构了 Char 缓存模式，除了解决不能复用的问题之外，由于支持了多纹理渲染，所以既能与动态图集合批，还有最多 8 张字体图集可以使用！** +但现在你可以使用这两种缓存模式了，服务包重构了 Char 缓存模式，除了解决了不能复用的问题之外，还支持了多纹理渲染，所以既能与动态图集合批，还有最多 8 张字符图集可以使用。 ### 脱胎换骨的 Char 缓存模式 @@ -171,7 +171,7 @@ cc.dynamicAtlasManager.maxFrameSize = 1024; // 推荐 512、1024 甚至 2048 以上就是新合批指南的全部内容了，稍微总结一下渲染批次合并的几个要点： - 启用动态合图，只需要合理地释放资源即可保持动态合图的一直有效 -- 优先使用 Char 缓存模式，不适合则使用 Bitmap 缓存模式，都不适合则采用老方法 +- Label 优先使用 Char 缓存模式，不适合则使用 Bitmap 缓存模式 - 不要优先考虑修改节点顺序这种需要维护成本的优化方式 如果你对批次合并还有着更高的需求，可以阅读 [进阶合批指南](./advance-batcher-guide.md)。 diff --git a/docs/docs/start-guide/breaking-change.md b/docs/docs/start-guide/breaking-change.md index a87fbc00..c6fc5eb1 100644 --- a/docs/docs/start-guide/breaking-change.md +++ b/docs/docs/start-guide/breaking-change.md @@ -5,9 +5,7 @@ description: "一般情况下都不需要了解。" # 破坏性变更 -在贡献指南中我们提到过会尽量不引入破坏性变更，或任何与原版引擎有不同的地方。 - -但有些变化难以避免，在这里你可以对变更进行评估是否会对项目造成巨大的影响。 +在添加新特性的过程中，就像引擎升级一样，有些变化在所难免，在这里你可以对变更进行评估是否会对项目造成巨大的影响。 --- ### 默认禁用原生 TTF 渲染器 @@ -16,7 +14,7 @@ description: "一般情况下都不需要了解。" 这个渲染器理论上能提升原生平台的 Label 性能，但仅在 Char 缓存模式并且还要使用 TTF 字体时才生效，这也导致了在原生平台上字体样式可能与其它平台不一致的问题。 -在重构 CHAR 缓存模式时考虑到这些因素和人力有限的原因，我们暂时不打算适配这个原生 TTF 渲染器，这个禁用是官方提供的接口，不会造成其它问题。 +在重构 CHAR 缓存模式时考虑到这些因素和人力有限的原因，我们暂时不打算适配这个原生 TTF 渲染器，所以直接默认禁用了原生 TTF 渲染器，这个禁用是官方提供的接口，不会造成其它问题。 **大部分项目可以不用关心**。 @@ -27,7 +25,7 @@ cc.macro.ENABLE_NATIVE_TTF_RENDERER = false; --- ### 动态图集的一些变化 -对动态图集的重构虽然保持了所有原有接口不变，但有些细节和以前不同了。 +对动态图集的重构虽然保留了所有原有的公开接口，但实现细节与以前不同了。 如果你的项目有在细致地管理动态图集，请注意以下几点： diff --git a/docs/docs/start-guide/new-features.md b/docs/docs/start-guide/new-features.md index 17d0b560..bd79d56f 100644 --- a/docs/docs/start-guide/new-features.md +++ b/docs/docs/start-guide/new-features.md @@ -5,7 +5,7 @@ description: "了解并上手服务包提供的所有其他新特性。" # 上手其它新特性 -除了前面提到的多纹理渲染、新动态图集、新 Label Char 缓存模式等特性之外，还有一些其它也很实用的新特性。 +除了前面提到的多纹理渲染、新动态图集、新 Label Char 缓存模式等特性之外，还有一些其它的也很实用的新特性。 --- ## 高 DPI 文本渲染 @@ -54,6 +54,6 @@ this.skel.setRegion('head', 'head', sp.SkeletonData.createRegion(spriteFrame)); --- ## 给 RichText 使用自定义材质 -这可能是很少用得到的功能，虽然加上去也简单，但主要还是我们看到几乎所有渲染组件可以自定义材质，这个组件却不可以。 +虽然加上去也简单，但这可能是很少用得到的功能，主要还是我们看到几乎所有渲染组件都可以自定义材质，这个组件却不可以。 可前往 [RichText 自定义材质](../user-guide/text-render/text-richtext.md) 文档了解更多详情。 diff --git a/docs/docs/start-guide/start-guide-intro.mdx b/docs/docs/start-guide/start-guide-intro.mdx index 78cd7cf6..d0c750ff 100644 --- a/docs/docs/start-guide/start-guide-intro.mdx +++ b/docs/docs/start-guide/start-guide-intro.mdx @@ -3,8 +3,6 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; # 入门指南 -在前面的介绍中，你虽然可以了解到服务包新增的一些重要特性的名称，但可能还是比较茫然。 - -这个教程会简单地介绍安装服务包后该如何更好地使用 Cocos Creator 引擎，帮助你发挥出所有的潜力： +这个教程会简单地介绍如何利用服务包提供的新特性来更好地使用 Cocos Creator 引擎： diff --git a/docs/docs/uninstall-guide.md b/docs/docs/uninstall-guide.md index 20ad6b8e..a5583e14 100644 --- a/docs/docs/uninstall-guide.md +++ b/docs/docs/uninstall-guide.md @@ -4,13 +4,11 @@ sidebar_position: 6 # 卸载指南 -虽然服务包没有对项目有侵入性修改，但这种操作还是有风险的，毕竟这就像要将引擎降级一样。 - -所以我们提供两种卸载方式以供参考： +服务包不会对项目进行修改，但就像要将引擎降级一样，这种操作还是有风险的，所以我们提供两种卸载方式以供参考： :::tip 提示 -即使是手动安装的服务包，依然可以通过引擎扩展进行卸载，反之亦然。 +因为原理是一样的，即使是手动安装的服务包，依然可以通过引擎扩展进行卸载，反之亦然。 ::: @@ -30,11 +28,11 @@ sidebar_position: 6 如果你的是 TypeScript 项目，则可以先删除 `creator-sp.d.ts` 文件，让 TypeScript 对使用了服务包接口的代码发出报错。 -这一步我们要确保所有代码都不再依赖服务包的特性。 +之后我们要确保所有代码都不再依赖服务包的特性。 ### 2.资源依赖 -服务包提供了一些内置资源，像是多纹理 Effect 着色器资源，你可以通过查找引用将资源的引用全部移除。 +服务包提供了一些内置资源，像是多纹理 Effect 着色器资源，你可以通过查找 UUID 引用将对服务包内置资源的引用全部移除。 ### 3.恢复自定义引擎与删除扩展 @@ -42,6 +40,4 @@ sidebar_position: 6 点击 Cocos Creator 主界面右上角的 **编辑器** 按钮，进入到编辑器的资源目录。 -接着使用未修改过的 `jsb-adapter` 替换掉编辑器的 `Resources/builtin/jsb-adapter` 目录。 - -将服务包相关的扩展（比如 `service-pack-support` 目录）删除。 +然后使用未修改过的 `jsb-adapter` 替换掉编辑器的 `Resources/builtin/jsb-adapter` 目录，最后将服务包的引擎扩展（比如 `service-pack-support` 目录）删除。 diff --git a/docs/docs/user-guide/user-guide-intro.mdx b/docs/docs/user-guide/user-guide-intro.mdx index 49f89c07..0047e7d5 100644 --- a/docs/docs/user-guide/user-guide-intro.mdx +++ b/docs/docs/user-guide/user-guide-intro.mdx @@ -5,7 +5,7 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; 在 [入门教程](../start-guide/start-guide-intro.mdx) 里，你应该对如何更好地使用安装服务包后的引擎已经有所了解了。 -通过使用指南你能更详细地了解服务包为引擎添加的每个特性与改动： +通过该指南你可以更详细地了解服务包为引擎添加的每个特性与改动：