完善 docs

README.md

@@ -6,6 +6,8 @@
 
 该项目尽量以最符合原始架构设计的方式为引擎加入新的特性、修复已知问题以及优化性能。
 
+正因为如此，大部分项目使用这个服务包就像升级引擎版本一样简单。
+
 > 项目的起源
 > 
 >2021 年 2 月，Cocos 发布 Cocos Creator 3.0，并在 3.x 发布之后不会再继续开发 2.x 版本的新特性，所有维护工作也会在 2023 年完全停止。
@@ -47,7 +49,7 @@
 
 ## 功能演示
 
-待补充。
+TODO
 
 ## 使用方法
 
@@ -60,8 +62,17 @@
 
 ## 更新日志
 
-### v1.0
+### Service Pack v1.0
-- 待补充
+
+- **[新特性] 支持多纹理渲染**
+- **[新特性] 重构动态图集，支持多个新特性**
+- **[新特性] 重构 cc.Label 的 Char 缓存模式，支持多个新特性**
+- **[新特性] 支持高 DPI 文本渲染**
+- **[新特性] cc.Spine 组件支持参与动态图集、与其它组件合批、使用 SpriteFrame 换装**
+- [新特性] cc.Label、cc.RichText、cc.Sprite、cc.MotionStreak、cc.Spine 组件支持使用多纹理材质，并支持自动切换材质机制
+- [新特性] cc.RichText 支持使用自定义材质
+- [修复] 直接修改 Effect 的属性不回导致其变体的 hash 值刷新
+- [调整] 默认禁用 Label 原生 TTF 渲染器
 
 所有更新日志请移步 [此处](https://smallmain.github.io/cocos-service-pack/docs/update-log)。
 

docs/docs/installation-guide/installation-engine-plugin.md

@@ -1,7 +1,8 @@
 ---
 sidebar_position: 1
 description: "推荐使用此方式进行一键安装。"
-icon: "😀"
 ---
 
 # 使用引擎扩展安装
+
+TODO

docs/docs/installation-guide/installation-manual.md

@@ -5,18 +5,7 @@ description: "需掌握一定的自定义引擎知识。"
 
 # 手动安装
 
-:::tip 提示
+## Service Pack v1.0
-
-建议升级到最新的引擎版本，官方只会对 2.x 版本只会进行维护性更新，所以不用担心其稳定性问题。
-
-如果你的项目引擎版本较低，可以看一看 [使用引擎扩展安装](./installation-engine-plugin) ，支持对多个引擎版本进行一键安装。
-
-:::
-
----
-## 服务包下载
-
-### Service Pack v1.0
 
 适配 Cocos Creator v2.4.9 版本，[点此下载服务包](http://www.baidu.com)
 
@@ -28,6 +17,14 @@ description: "需掌握一定的自定义引擎知识。"
 - **项目所使用的引擎版本与服务包适配的引擎版本一致**
 - **项目未使用自定义引擎**
 
+:::tip 提示
+
+建议升级到最新的引擎版本，官方只会对 2.x 版本只会进行维护性更新，所以不用担心其稳定性问题。
+
+如果你的项目引擎版本较低，可以看一看 [使用引擎扩展安装](./installation-engine-plugin) ，支持对多个引擎版本进行一键安装。
+
+:::
+
 ### 1.替换自定义引擎
 
 下载服务包后，解压压缩包可以看到压缩包内的 `engine` `cocos2d-x` `jsb-adapter` 这三个目录分别是已经整理好的 **JavaScript 引擎**、**Cocos2d-x 引擎** 和 **jsb-adpater**。
@@ -57,7 +54,7 @@ description: "需掌握一定的自定义引擎知识。"
 
 :::caution 注意
 
-**请勿将此扩展与 “使用引擎扩展安装” 中所安装的引擎扩展混淆！**
+**请勿将此引擎扩展与 “使用引擎扩展安装” 中所安装的引擎扩展混淆！**
 
 **该扩展只解决自定义引擎无法为引擎新增内置资源和扩展组件 inspector 的问题，是服务包开源的一部分**。
 
@@ -65,15 +62,11 @@ description: "需掌握一定的自定义引擎知识。"
 
 压缩包内 `service-pack-support` 目录即是扩展本身，将其放到项目的 `packages` 目录即可。
 
-更多详情可阅读官方的 [安装扩展](https://docs.cocos.com/creator/2.4/manual/zh/extension/install-and-share.html) 文档。
+服务包需要使用名为 `sp` 的 AssetBundle 存放资源，如果你的项目有使用 AssetBundle，请**确保该名称未被占用**。
-
-:::caution 注意
-
-服务包会使用名为 `sp` 的 AssetBundle 存放资源，如果你的项目有使用 AssetBundle，请确保该名称未被占用。
 
 没有必要将这个 Asset Bundle 设为远程包或者 Zip 压缩，里面只是一个多纹理 Effect 着色器资源。
 
-:::
+更多详情可阅读官方的 [安装扩展](https://docs.cocos.com/creator/2.4/manual/zh/extension/install-and-share.html) 文档。
 
 ### 3.TypeScript 类型提示（可选）
 
@@ -87,10 +80,12 @@ description: "需掌握一定的自定义引擎知识。"
 
 完成以上的步骤后重启 Cocos Creator。
 
-可在项目预览时检查 Devtools Console 打印的是否为 `Cocos Creator SP v2.4.x`，是的话则成功安装。
+可在项目预览时检查 Devtools Console 打印的是否为 `Cocos Creator SP v2.4.x`，是的话则已经成功安装。
 
 ![](./assets/installed-console.png)
 
+接下来推荐你从 [入门教程](../start-guide/start-guide-intro) 开始了解服务包为你的开发都带来了哪些新特性！
+
 ---
 ## 补丁安装
 

docs/docs/intro.md

@@ -10,6 +10,8 @@ hide_title: true
 
 该项目尽量以最符合原始架构设计的方式为引擎加入新的特性、修复已知问题以及优化性能。
 
+正因为如此，大部分项目使用这个服务包就像升级引擎版本一样简单。
+
 :::info 项目的起源
 2021 年 2 月，Cocos 发布 Cocos Creator 3.0，并在 3.x 发布之后不会再继续开发 2.x 版本的新特性，所有维护工作也会在 2023 年完全停止。
 
@@ -38,7 +40,7 @@ Service Pack 暂时只适配 Cocos Creator 2.x 版本，Cocos Creator 3.x 正在
 
 ## 功能演示
 
-待补充。
+TODO
 
 ## 使用方法
 
@@ -51,8 +53,17 @@ Service Pack 暂时只适配 Cocos Creator 2.x 版本，Cocos Creator 3.x 正在
 
 ## 更新日志
 
-### v1.0
+### Service Pack v1.0
-- 待补充
+
+- **[新特性] 支持多纹理渲染**
+- **[新特性] 重构动态图集，支持多个新特性**
+- **[新特性] 重构 cc.Label 的 Char 缓存模式，支持多个新特性**
+- **[新特性] 支持高 DPI 文本渲染**
+- **[新特性] cc.Spine 组件支持参与动态图集、与其它组件合批、使用 SpriteFrame 换装**
+- [新特性] cc.Label、cc.RichText、cc.Sprite、cc.MotionStreak、cc.Spine 组件支持使用多纹理材质，并支持自动切换材质机制
+- [新特性] cc.RichText 支持使用自定义材质
+- [修复] 直接修改 Effect 的属性不回导致其变体的 hash 值刷新
+- [调整] 默认禁用 Label 原生 TTF 渲染器
 
 所有更新日志请移步 [此处](./update-log)。
 

docs/docs/start-guide/advance-batcher-guide.md

@@ -0,0 +1,8 @@
+---
+sidebar_position: 2
+description: "极致地减少游戏 Draw Call。"
+---
+
+# 进阶合批指南
+
+TODO

docs/docs/start-guide/batcher-guide.md

@@ -1,6 +1,6 @@
 ---
 sidebar_position: 1
-description: "在大部分游戏的开发中享受不用担心 Draw Call 的快乐。"
+description: "在游戏开发中享受不用关注 Draw Call 的快乐。"
 ---
 
 # 新 UI 渲染批次合并指南
@@ -43,7 +43,7 @@ description: "在大部分游戏的开发中享受不用担心 Draw Call 的快
 ---
 ## 为你的项目启用动态合图
 
-在项目原来的开发中，我们可能会关闭动态图集，更倾向于靠静态图集或者自动图集达到降低 Draw Call 的目的。
+在项目之前的开发中，我们可能会关闭动态图集，更倾向于靠静态图集或者自动图集达到降低 Draw Call 的目的。
 
 这种选择除了与动态合图存在会占用更多内存的缺点有关之外，更多的是在引擎原来的动态合图中，并不能复用图集的废弃区域，这个重要特性的缺失只能靠在切换场景（Scene）后重置所有图集来解决。
 
@@ -79,7 +79,7 @@ description: "在大部分游戏的开发中享受不用担心 Draw Call 的快
 
 :::tip 
 
-服务包会将动态图集默认的最大数量自动调整至与设备能同时采样的纹理数一致，这个值一般为 `8`。
+服务包会自动将图集最大数量调整至（设备能同时采样纹理数 - Char 缓存模式自动合批图集数），这个值默认为 `7`。
 
 :::
 
@@ -99,8 +99,90 @@ description: "在大部分游戏的开发中享受不用担心 Draw Call 的快
 
 在上面我们推荐可以将纹理尺寸限制放宽到 `2048`，这听起来貌似有点离谱，但只要规划好项目的资源确实可行，比如：
 
-- **将优化程度有限但尺寸具大的纹理禁止参与动态合图**
+- 将优化程度有限但尺寸具大的纹理禁止参与动态合图
-- **分模块存放资源，将冷门界面（如活动）的纹理禁止参与动态合图，或尽早释放掉**
+- 分模块存放资源，将冷门界面（如活动）的纹理禁止参与动态合图，或尽早释放掉
-- **在资源已经一团糟的项目中，可以直接禁止渲染组件参与动态合图**
+- 在资源已经一团糟的项目中，可以直接禁止渲染组件参与动态合图
 
-## Label 不再是合批的噩梦
+---
+## Label 不再是合批噩梦
+
+在项目之前的开发中，我们可能会使用字体图集、调整节点顺序，甚至修改渲染流程来解决 Label 的性能问题。
+
+但是引擎不是提供了 Bitmap 和 Char 两种缓存模式吗？
+
+是的，但是这两个解决方案与旧的动态合图一样在生产环境中使用太过 "玩具" 了：
+
+- Bitmap 缓存模式的缺点：字体纹理会打入动态图集，而动态图集无法复用，随着游戏的进行，图集用完则直接失去作用。
+
+- Char 缓存模式的缺点：还是无法复用，并且只有一张图集，用完则直接无法渲染，试问谁能接受游戏可能跑着跑着字就全部消失了的情况。
+
+所以，**服务包几乎重构了 Char 缓存模式，除了解决不能复用的问题之外，由于支持了多纹理渲染，所以既可以与动态图集一起合批，还拥有高达最多 8 张字体图集可以使用！**
+
+接下来我们有几个小提示能让你知道如何选择合适的缓存模式：
+
+### 委以重任一把梭 —— Char
+
+遇事不决，先选 Char 缓存模式。
+
+虽然 Char 模式也有一些缺点，但能够应付大多数的场景，由于它既能与动态图集一起合批，还是是按字符进行复用的，所以相比 Bitmap 模式它有着更高的性能优势。
+
+而且不用担心这 8 张字符图集会被用完，内部会用引用计数自动释放废弃字符所占用的空间，可以试着想一下你的游戏最多在同一帧会显示几个字符。
+
+但 Char 缓存模式不适合下面的场景：
+
+- 无法显示带有像 emoji 的字素簇的字符串，这种字符串现在不能被完美地分割成单个字符，所以 Char 缓存模式也就不能正常显示了。
+- 接上条，像聊天消息、输入框这类不可控的内容文本都不建议用 Char 缓存模式。
+- Char 缓存模式不支持一些字体样式，可以在官方文档中了解详情。
+- 巨大的字体大小（比如几百的）可能会瞬间占满整张字符图集，字符图集虽然有 8 张但也不能这么霍霍。
+
+### 最后的合批守护者 —— Bitmap
+
+即使不能选择 Char 缓存模式，Bitmap 缓存模式也能成为批次的最后一道防线。
+
+在解决了动态图集的复用问题后，Bitmap 缓存模式的纹理也会使用引用计数自动释放，并且不会有 Char 缓存模式无法显示字素簇的问题。
+
+但当然，Bitmap 缓存模式也不是万能的，如果遇到了下面这种情况就再考虑调整节点顺序等方法来解决吧：
+
+- 巨大的字体大小也会瞬间占满整张动态图集
+- 在非常大量的 Label 需频繁改变文本的情况下，请使用性能分析工具检查动态图集的性能消耗，避免合批的弊大于利。
+
+### 关于字符图集与动态图集
+
+常见的误区：
+
+#### 1.Char 缓存模式所使用的字符图集与动态图集是一样的东西，只是叫法不同
+
+由于多种原因，没有设计让 Char 缓存模式直接使用动态图集，这当然可以做到，但是权衡之下选择了分开实现，在使用指南中有详细解释。
+
+多纹理材质只有 8 个纹理插槽，所以默认情况下动态图集最大数量为 7，字符图集自动多纹理合批的数量为 1。（注意不是最大数量）
+
+你可以自己调整这个分配值，而服务包使用这个默认值有以下几点原因：
+
+- 引擎原本就只有 1 张 Char 字符图集
+- 大多数项目因为 Char 缓存模式加入了可复用的特性后，1 张 Char 字符图集是足够的
+
+如果你直觉认为 1 张太少，我们建议你合理搭配使用 Bitmap 和 Char 两种缓存模式后，实际测试发现不够再调整该值。
+
+**请注意上面的 1 并非是字符图集的最大数量，而是字符图集进行自动多纹理合批的最大数量！**
+
+所以这并不意味着字符图集只能有 1 张，而是最大能有 8 张，并且这个数量不能调整。
+
+如果你还是对为什么会出现一个 “字符图集进行自动多纹理合批的最大数量” 而一头雾水，建议详细阅读使用指南。
+
+#### 2.Char 缓存模式能在图集满了的情况下依然能正常显示
+
+现在如果字符图集满了，依旧不能正常显示，这样的原因有以下几点：
+
+- 我们认为 8 张数量已经够多了，8 张都用完的情况大部分是没有合理搭配使用两种缓存模式
+- 8 张是多纹理渲染的上限，这意味着如果超过 8 张，1 个 Label 有 100 个字，就可能有 100 个 Draw Call
+
+---
+## 总结
+
+以上就是新合批指南的全部内容了，稍微总结一下渲染批次合并的几个要点：
+
+- 启用动态合图，只需要合理地释放资源即可保持动态合图的一直有效
+- 能就优先用 Char 缓存模式，不能则换为 Bitmap 缓存模式，字数太多字体太大的则放弃挣扎使用 None 模式
+- 不要优先考虑打图集，修改节点顺序等需要维护成本的优化方式
+
+如果你对批次合并还有着更高的需求，可以阅读 [进阶合批指南](./advance-batcher-guide)。

docs/docs/start-guide/breaking-change.md

@@ -1,16 +1,54 @@
 ---
-sidebar_position: 1
+sidebar_position: 3
-description: "在大部分的情况下都不需要了解。"
+description: "一般情况下都不需要了解。"
 ---
 
 # 破坏性变更
 
-:::note 提示
+在贡献指南中我们提到过会尽量不引入破坏性变更，或任何与原版引擎有不同的地方。
 
-在贡献指南中我们提到过尽量不会引入破坏性变更或者任何与原版引擎有不同的地方。
+但有些变化难以避免，在这里你可以检查所有变更，评估是否会造成巨大的影响。
 
-但是有一些情况难以避免，我们会尽量减少其带来的不便。
+### 默认禁用原生 TTF 渲染器
 
-:::
+引擎的 Label 在使用 Char 缓存模式并且使用 TTF 字体时，会使用一个原生 TTF 渲染器。
 
-## 仅支持 WebGL 渲染模式
+这个渲染器理论上能提升原生平台的 Label 性能，但仅在 Char 缓存模式并且还要使用 TTF 字体时才生效，这也导致了在原生平台上字体样式可能与其它平台不一致的问题。
+
+在重构 CHAR 缓存模式时考虑到这些因素和人力有限的原因，我们暂时不打算适配这个原生 TTF 渲染器，这个禁用是官方提供的接口，不会造成其它问题。
+
+**大部分项目可以不用关心**。
+
+```
+cc.macro.ENABLE_NATIVE_TTF_RENDERER = false;
+```
+
+### 动态图集的一些变化
+
+对动态图集的重构虽然保持了所有原有接口不变，但有些细节和以前不同了。
+
+如果你的项目有在细致地管理动态图集，请注意以下几点：
+
+- **如果你有手动修改 `cc.dynamicAtlasManager.maxAtlasCount` 属性，请考虑删除**
+
+服务包会根据设备最大纹理数和 Char 缓存模式字符图集的相关设置自动调整动态合图的最大图集数量。
+
+这不意味着你不能手动调整了，而是建议你阅读新动态图集和新 Char 缓存模式相关的文档后再考虑是否有必要进行调整。
+
+关于这个你可以从 [新 UI 渲染批次合并指南](./batcher-guide) 进行了解。
+
+- **动态图集重复纹理的判断从 `texture._id` 改为使用 `texture._uuid`**
+
+具体的设计原因和原理可前往 [动态图集](TODO) 文档进行了解。
+
+- **`cc.dynamicAtlasManager.insertSpriteFrame(spriteFrame)` 不再检查纹理的 `packable` 属性**
+
+并不是说 `packable` 属性无效了，而是 `insertSpriteFrame` 现在作为将纹理强制加入动态图集的接口使用。
+
+- **如果你的项目依赖动态图集的内部实现细节，请重新检查相关代码**
+
+这个就是因为动态图集被重构了，如果你的项目依赖一些未公开的类或者接口（引擎在 `creator.d.ts` 声明了的则是已经公开的），则可能需要重新编写。
+
+### 使用 Char 缓存模式的 Label 暂不支持在编辑器中设置材质
+
+如果项目中有 Label 使用了 Char 缓存模式并且设置了自定义材质，可能会失效，具体原因可前往 [Char 缓存模式](TODO) 文档进行了解。

docs/docs/start-guide/start-guide-intro.mdx

@@ -5,8 +5,6 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
 
 在前面的介绍中，你虽然可以了解到服务包新增的一些重要特性的名称，但可能还是比较茫然。
 
-这个教程会简单地介绍安装服务包后该如何更好地使用 Cocos Creator 引擎，帮助你发挥出所有的潜力。
+这个教程会简单地介绍安装服务包后该如何更好地使用 Cocos Creator 引擎，帮助你发挥出所有的潜力：
-
-这包括一个**新 UI 渲染批次合并指南**，和安装服务包后你可能需要注意的**破坏性变更**：
 
 <DocCardList items={useCurrentSidebarCategory().items}/>

docs/docs/uninstall-guide.md

@@ -0,0 +1,37 @@
+---
+sidebar_position: 5
+---
+
+# 卸载指南
+
+虽然服务包没有对项目有侵入性修改，但这种操作还是有风险的，毕竟这就像要将引擎降级一样。
+
+所以我们提供两种卸载方式仅供参考：
+
+:::tip 提示
+
+即使是手动安装的服务包，依然可以通过引擎扩展进行卸载，反之亦然。
+
+:::
+
+## 使用引擎扩展卸载 
+
+TODO
+
+## 手动卸载
+
+### 1.代码依赖
+
+如果你的是 TypeScript 项目，则可以先删除 `creator-sp.d.ts` 文件，让 TypeScript 对使用了服务包接口的代码发出报错。
+
+这一步我们要确保所有代码都不再依赖服务包的特性。
+
+### 2.资源依赖
+
+服务包提供了一些内置资源，像是多纹理 Effect 着色器资源，你可以通过查找引用将资源的引用全部移除。
+
+### 3.恢复自定义引擎与删除扩展
+
+打开 Cocos Creator 菜单的项目 - 项目设置 - 自定义引擎，勾选使用内置引擎。
+
+将服务包相关的扩展（比如 `service-pack-support` 目录）删除。

docs/docs/update-log.md

@@ -1,6 +1,20 @@
 ---
-sidebar_position: 5
+sidebar_position: 6
-title: 更新日志
 ---
 
-## v1.0
+# 更新日志
+
+## Service Pack v1.0
+
+适配 Cocos Creator v2.4.9 版本，[点此下载服务包](http://www.baidu.com)
+
+- **[新特性] 支持多纹理渲染**
+- **[新特性] 重构动态图集，支持多个新特性**
+- **[新特性] 重构 cc.Label 的 Char 缓存模式，支持多个新特性**
+- **[新特性] 支持高 DPI 文本渲染**
+- **[新特性] cc.Spine 组件支持参与动态图集、与其它组件合批、使用 SpriteFrame 换装**
+- [新特性] cc.Label、cc.RichText、cc.Sprite、cc.MotionStreak、cc.Spine 组件支持使用多纹理材质，并支持自动切换材质机制
+- [新特性] cc.RichText 支持使用自定义材质
+- [修复] 直接修改 Effect 的属性不回导致其变体的 hash 值刷新
+- [调整] 默认禁用 Label 原生 TTF 渲染器
+

docs/docs/user-guide/user-guide-intro.mdx

@@ -3,14 +3,14 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
 
 # 使用指南
 
+在 [入门教程](../start-guide/start-guide-intro) 里，你应该对如何更好地使用安装服务包后的引擎已经有所了解了。
+
+而在这里你能了解到服务包为引擎添加的每个特性、改动与原理：
+
+<DocCardList items={useCurrentSidebarCategory().items}/>
+
 :::caution 注意
 
 在几乎所有平台上引擎都是使用 WebGL 渲染模式，所以服务包的大部分特性都未支持引擎的 Canvas 渲染模式，部分特性在 3D 节点下不生效。
 
 :::
-
-在 [入门教程](../start-guide/start-guide-intro) 里，你应该对如何更好地使用安装服务包后的引擎已经有所了解了。
-
-而在这里会更进一步，你能了解到服务包为引擎添加的所有特性：
-
-<DocCardList items={useCurrentSidebarCategory().items}/>

docs/src/css/custom.css

@@ -65,7 +65,7 @@
 
 @media screen and (min-width: 997px) {
   :root {
-    --ifm-font-size-base: 18px;
+    --ifm-font-size-base: 16px;
   }
 
   .hero__subtitle {
@@ -97,11 +97,6 @@
     margin-bottom: calc(var(--ifm-heading-vertical-rhythm-bottom) * var(--ifm-leading) * 1.5);
   }
 
-  .markdown>h3 {
-    --ifm-h3-font-size: 1.3rem;
-  }
-
-
 }
 
 .menu__caret:before {