润色和更新 2.0.0 版本文档

This commit is contained in:
SmallMain 2024-10-25 13:34:46 +08:00
parent 702fe8c43b
commit 7fc44107c7
No known key found for this signature in database
24 changed files with 206 additions and 300 deletions

View File

@ -151,7 +151,7 @@ Label 一直是项目优化的最难点,因为它完全不能和其它的渲
2. 需要进行释放的 spine 资源,不让其参与动态合图(通过控制 Spine 组件的合图开关)。
3. 不释放需要参与动态合图的 spine 资源。
该问题已在 v2.4.13 版本修复,请升级社区版版本至 v2.0.0 以上。
该问题已在 v2.4.13 版本修复,请升级社区版至 v2.0.0 以上。
## 支持我们

View File

@ -1,144 +0,0 @@
---
sidebar_position: 1
description: "在游戏开发中享受不用关注 Draw Call 的快乐。"
---
# 提升项目性能
在官方文档的进阶主题中有一个 [UI 渲染批次合并指南](https://docs.cocos.com/creator/2.4/manual/zh/advanced-topics/ui-auto-batch.html),批次合并一直是游戏开发中重要的优化手段,如果你未阅读过官方的指南,可以先阅读一遍。
**多纹理渲染**、**新动态图集** 等特性出现后,在进行批次合并时可以变得更加简单且自动化。
---
## 启用动态合图
在之前的开发中我们通常会关闭动态图集,更倾向于靠静态图集或者自动图集达到降低 Draw Call 的目的。
不使用动态图集最重要的原因是其不能复用图集的废弃区域,随着游戏的运行动态图集会完全用完。
引擎只提供了在切换场景Scene后重置所有图集的机制来解决这个问题但对于大部分项目来说这种治标不治本的机制基本等于没有解决。
现在,增强包几乎重构了整个动态合图系统,你可以考虑重新启用动态合图了。
:::note 提示
开启动态图集常见的反对意见是:
在部分小游戏平台里,启用动态图集会有保留 Image 对象导致内存占用大的问题。
建议:
- 实际测试是否启用动态图集的内存占用差距。
- 有没有一种可能,只是说可能,内存占用大更多是因为你的项目根本没做任何资源释放呢?
:::
---
## 充分利用动态合图
一般情况下只需要保持动态图集的默认设置即可,如果出现动态图集很多纹理不会打入或者图集很快用完的情况,可以参考以下建议调整。
### 放宽能参与合图的纹理尺寸限制
**动态图集会自动进行多纹理合批,你可以放心地使用多达 7 张图集而不用担心交叉渲染导致的打断批次!**
你可以根据项目的具体情况来放宽能参与合图的纹理尺寸限制。
```js
cc.dynamicAtlasManager.maxFrameSize = 1024; // 推荐 512、1024 甚至 2048
```
:::tip
增强包会自动将图集的最大数量调整至(设备能同时采样纹理数 - Char 缓存模式自动合批图集数),这个值默认为 `7`
:::
### 无需管理动态图集,只需要释放资源
**动态合图会在纹理被释放的同时释放其在动态图集使用的空间。**
如果动态图集的使用量一直在增长,请检查是否做了资源释放,因为你不需要关心动态图集的使用情况,只需要做好应有的资源释放就能保持动态图集的长期有效。
### 更加细致地优化图集的使用效率
除了通过调整纹理的 `packable` 属性可以控制纹理是否会参与动态合图之外,增强包提供了**控制组件是否默认参与动态合图,控制单个组件是否参与动态合图**的新特性。
可前往 [动态合图](../user-guide/dynamic-batcher/dynamic-batcher-intro.mdx) 的文档了解详情。
你可以考虑将纹理尺寸限制放宽到 `2048`,这听起来貌似有点离谱,但只要规划得当确实可行,比如:
- 禁止优化程度有限但尺寸巨大的纹理参与动态合图
- 分模块存放资源,禁止冷门(如活动界面)的纹理参与动态合图或尽早地释放掉
- 在资源太多的项目中,可考虑控制界面的渲染组件是否参与动态合图
完成上面几点这可能需要一些工作量,但能将动态图集用在刀刃上,发挥更大的作用。
---
## Label 不再是合批噩梦
在之前的开发中我们可能会使用字体图集、调整节点顺序、甚至修改渲染流程来解决 Label 的性能问题。
也是因为引擎提供的 Bitmap 和 Char 两种缓存模式在稍大一点的项目上显得力所不及:
- Bitmap 缓存模式:字体纹理会打入动态图集,但动态图集却无法复用,随着游戏的进行,图集用完则直接失去作用。
- Char 缓存模式的缺点:还是无法复用,并且只有一张图集,图集用完则直接无法渲染,应该没人能接受游戏可能跑着跑着字就全部消失了的情况。
但现在你可以使用这两种缓存模式了,增强包重构了 Char 缓存模式,除了解决了不能复用的问题之外,还支持了多纹理渲染,所以既能与动态图集合批,还有最多 8 张字符图集可以使用。
### 脱胎换骨的 Char 缓存模式
**如果你不知道该选择什么缓存模式,那就遇事不决,先选 Char 缓存模式。**
虽然 Char 模式也有一些缺点,但由于它既能与动态图集一起合批,还是是按字符进行复用的,所以相比 Bitmap 模式它有着更高的性能优势。
不用担心字符图集会被用完,内部会用引用计数自动释放废弃字符所占用的空间。
但 Char 缓存模式不适合下面的场景:
- 无法显示带有像 emoji 的字素簇的字符串,这种字符串现在不能被完美地分割成单个字符,所以 Char 缓存模式也就不能正常显示了。
- 接上条,像聊天消息、输入框这类不可控的内容文本都不建议用 Char 缓存模式。
- Char 缓存模式不支持一些字体样式,可以在官方文档中了解详情。
- 巨大的字体大小(比如几百的)可能会瞬间占满整张字符图集,字符图集虽然有 8 张但也不能这么霍霍。
### 兜底的 Bitmap 缓存模式
即使不能选择 Char 缓存模式Bitmap 缓存模式也能成为批次的最后一道防线。
在解决了动态图集的复用问题后Bitmap 缓存模式的纹理也会使用引用计数自动释放,并且不会有 Char 缓存模式无法显示字素簇的问题。
但当然Bitmap 缓存模式也不是万能的,如果遇到了下面这种情况,就需要考虑使用调整节点顺序这样的老办法来解决了:
- 巨大的字体大小也会瞬间占满整张动态图集,动态图集也不能这么霍霍。
- 在大量的 Label 需频繁改变文本的情况下,请使用性能分析工具检查动态图集的性能消耗,避免合批的弊大于利。
:::caution 注意
无论使用哪种缓存模式,在做缩放动画时不要对 `fontSize` 属性进行缓动,这会导致每帧都需要重新生成文字纹理,造成巨大的性能负担,可以使用节点的 `scale` 来代替。
:::
### 注意事项
- **Char 缓存模式所使用的字符图集与动态图集不是一个东西**
有多种因素导致没有让 Char 缓存模式直接使用动态图集来实现,这个原因在 Char 缓存模式的原理文档中有详细解释。
- **Char 缓存模式依然不能在图集用完的情况下正常渲染**
原因有以下几点:
- 我们认为 8 张数量已经够多了8 张都用完的情况大部分是没有合理搭配使用两种缓存模式
- 8 张是多纹理渲染的上限,这意味着如果超过 8 张1 个 Label 有 100 个字,就可能有 100 个 Draw Call
---
## 总结
以上就是新合批指南的全部内容了,稍微总结一下渲染批次合并的几个要点:
- 启用动态合图,只需要合理地释放资源即可保持动态合图的一直有效
- Label 优先使用 Char 缓存模式,不适合则使用 Bitmap 缓存模式
- 不要优先考虑修改节点顺序这种需要维护成本的优化方式
如果你对批次合并还有着更高的需求,可以阅读 [进阶合批指南](./advance-batcher-guide.md)。

View File

@ -1,37 +1,17 @@
---
sidebar_position: 3
description: "了解并上手增强包提供的所有其他新特性。"
description: "了解并上手社区版提供的新特性。"
---
# 上手其它新特性
# 新引擎特性
除了前面提到的多纹理渲染、新动态图集、新 Label Char 缓存模式等特性之外,还有一些其它的也很实用的新特性
社区版添加了一些实用的新特性,帮助你更好地开发游戏
---
## 高 DPI 文本渲染
以前我们会使用将 Label 字号放大一倍Label 节点缩小一倍的方式去解决字体模糊的问题。
而现在不需要了,你可以通过一句代码调整渲染比例:
```js
cc.sp.labelRetinaScale = 2; // 渲染文本时纹理的缩放倍数,默认值为 1.
```
![labelscaledemo](./assets/labelscaledemo.png)
> 图片中,上方的是开启后效果,下面是未开启效果。
**推荐你根据设备像素比devicePixelRatio来动态设置该值并且该值不要大于 `2`,这不会带来更好的效果,但却将字体纹理放大了数倍,会影响到游戏整体性能,影响动态图集的效率。**
可前往 [高 DPI 支持](../user-guide/text-render/text-high-dpi.md) 文档了解更多详情。
---
## 使用 SpriteFrame 进行 Spine 换装
## 支持 SpriteFrame 给 Spine 换装
官方文档中介绍了替换 attachment 对象进行换装的方法,但如果动画中有切换 attachment 的关键帧,这种方法就失效了。
还有一种方法是修改 attachment 的 region 对象来进行换装,但这种方法引擎没有直接支持,所以增强包对其进行了支持。
还有一种方法是修改 attachment 的 region 对象来进行换装,但这种方法引擎没有直接支持,所以社区版对其进行了支持。
只需要一句代码即可使用 cc.SpriteFrame 的数据修改 attachment 的 region 对象数据:
@ -45,22 +25,6 @@ skeletonComponent.setRegionData('Head', 'Head', new sp.RegionData(spriteFrame));
这样做是直接修改了 SkeletonData 的数据,所有使用该数据的 Spine 组件都会受到影响(被换头),但我们提供了克隆 SkeletonData 数据的接口,可前往 [Spine](../user-guide/spine/spine-intro.mdx) 文档了解更多详情。
:::tip 提示
还有一个小特性Spine 组件也支持了自动参与动态图集,并且也支持了和其它组件合批。
:::
---
## 给 RichText 使用自定义材质
虽然加上去也简单,但这可能是很少用得到的功能,主要还是我们看到几乎所有渲染组件都可以自定义材质,这个组件却不可以。
## 支持 RichText 自定义材质
可前往 [RichText 自定义材质](../user-guide/text-render/text-richtext.md) 文档了解更多详情。
---
## 复用 TiledMap 的 Culling 数据
一个 TiledMap 可能会有很多 TiledLayer如果开启了 Culling那这些 Layer 都需要单独计算 Culling 数据,增强包新增了在满足一定条件的情况下可以复用 Culling 数据的特性,以减少 CPU 的性能消耗。
可前往 [复用 Culling 数据](../user-guide/tiledmap/tiledmap-culling.md) 文档了解更多详情。

View File

@ -0,0 +1,99 @@
---
sidebar_position: 1
description: "在游戏开发中享受不用关注 Draw Call 的快乐。"
---
# 提升游戏性能
建议先阅读官方文档的 [UI 渲染批次合并指南](https://docs.cocos.com/creator/2.4/manual/zh/advanced-topics/ui-auto-batch.html) 了解一些基础知识。
社区版对动态合图、文本渲染等功能进行了大量的改进,现在,你只需要确保以下几点就可以大幅提升游戏的性能。
## 使用动态合图
在之前,动态合图不支持复用图集的废弃区域,所以我们通常会关闭该特性,倾向于靠静态图集或者自动图集达到降低 Draw Call 的目的。
现在,社区版几乎重构了整个动态合图系统,实用性得到大幅提升:
- 支持复用废弃区域
- 自动参与多纹理渲染
- 支持 Spine 参与动态合图
你只需要重新启用动态合图,并尽量让更多的纹理都参与合图,即可大幅降低 DrawCall 的数量。
我们还建议做以下调整:
**放宽能参与合图的纹理尺寸限制**
```js
cc.dynamicAtlasManager.maxFrameSize = 1024; // 推荐 512、1024 甚至 2048
```
你可以根据游戏运行过程中所使用的动态图集数量,来逐步放宽限制,取得一个平衡点。
**优化动态图集的使用率**
当游戏使用的动态图集数量太多,你可以控制某个组件或纹理不参与动态合图:
- 调整纹理的 `packable` 属性
- 调整组件的 `allowDynamicAtlas` 属性
通过让某些优化性价比较低的纹理不参与合图,例如:
- 大尺寸、单独出现的纹理:比如背景图,尺寸较大使得占用图集的空间大,并且一个场景内可能只有单个节点会显示,不存在需要大量合批的情况。
来优化图集的使用。
**及时释放无用资源**
由于社区版支持了图集空间的复用,所以释放资源的同时也会将其占用的图集空间释放,以提供给其它纹理使用。
建议在不用的时候及时释放一些冷门资源,常用的资源则不进行释放,避免频繁释放后加载导致的性能消耗。
## 使用 Label 缓存模式
在之前,引擎提供的缓存模式都各有问题,无法在实际项目中使用:
- Bitmap 模式:虽然能够参与动态合图,但无法复用废弃空间,随着游戏的运行,废弃字符的纹理占满图集后就失去了优化效果。
- Char 模式:依然是无法复用的问题,仅有一张字符纹理,当纹理被填满后甚至无法渲染出文本。
现在,由于社区版使动态合图支持了复用,并且还重构了 Char 模式的实现,使得 你只需要合理运用这两种缓存模式即可完成对 Label 的优化工作。
**首选 Char 缓存模式**
我们建议 Label 默认使用 Char 缓存模式,相比 Bitmap 模式Char 模式是按字符进行复用的,有着更高的性能优势。
**备选 Bitmap 缓存模式**
如果遇到以下场景,则不适合使用 Char 模式进行渲染:
- 显示像 Emoji 这种字素簇的字符串,由于内部实现无法分割为单个字符,所以不能正常显示。
- 超大字体,可能瞬间占满字符纹理。
- 显示聊天消息、输入框、玩家名称这类不可控的内容,由于第一条限制,所以为了保证 Label 能正常显示,则不建议使用。
这时候就可以改用 Bitmap 模式进行渲染,依然能参与动态合图进行合批。
### 注意事项
- **勿对 `fontSize` 属性进行动画或者缓动**
无论是否使用缓存模式,也不建议频繁修改 `fontSize` 属性,这会导致每帧都需要重新生成文字纹理,造成大量的性能消耗,可以转为使用节点的 `scale` 来代替。
- **Char 缓存模式依旧不能在内部字符纹理填满时正常渲染**
这是引擎原本的限制,我们未对其进行修复,原因是我们认为 8 张数量已经够多了8 张都用完的情况大部分是没有合理搭配使用两种缓存模式。
## 启用 Spine 合批
Spine 组件现在不仅可以参与动态合图,还能与其他渲染组件进行合批。
只需启用组件上的 `Enable Batch` 属性即可。
## 提升 TiledMap 性能
一个 TiledMap 可能会有很多个 TiledLayer如果开启了 TiledMap 的 Culling 特性,则需要每个 Layer 都单独计算 Culling 数据。
社区版新增了在满足一定条件的情况下可以复用 Culling 数据的特性,以减少 CPU 的性能消耗。
可前往 [复用 Culling 数据](../user-guide/tiledmap/tiledmap-culling.md) 文档了解更多详情。

View File

@ -0,0 +1,26 @@
---
sidebar_position: 2
description: "提升游戏的质量。"
---
# 提升游戏质量
社区版加入了一些新特性,使得你能提升游戏各方面的质量。
## 高 DPI 文本渲染
以前我们会使用将 Label 字号放大一倍Label 节点缩小一倍的方式去解决字体模糊的问题。
而现在不需要了,你可以通过一句代码调整渲染比例:
```js
cc.sp.labelRetinaScale = 2; // 渲染文本时纹理的缩放倍数,默认值为 1.
```
![labelscaledemo](./assets/labelscaledemo.png)
> 图片中,上方的是开启后效果,下面是未开启效果。
**推荐你根据设备像素比devicePixelRatio来动态设置该值并且该值不要大于 `2`,这不会带来更好的效果,但却将字体纹理放大了数倍,会影响到游戏整体性能。**
可前往 [高 DPI 支持](../user-guide/text-render/text-high-dpi.md) 文档了解更多详情。

View File

@ -5,7 +5,7 @@ description: "一般情况下都不需要了解。"
# 破坏性变更
在添加新特性的过程中,就像引擎升级一样,有些变化在所难免,在这里你可以对变更进行评估是否会对项目造成巨大的影响。
在添加新特性的过程中,有些变化在所难免,你可以浏览本文档以进行评估是否会对项目造成影响。
---
### 默认禁用原生 TTF 渲染器
@ -31,11 +31,11 @@ cc.macro.ENABLE_NATIVE_TTF_RENDERER = false;
- **如果你有手动修改 `cc.dynamicAtlasManager.maxAtlasCount` 属性,请考虑删除**
增强包会根据设备最大纹理数和 Char 缓存模式字符图集的相关设置自动调整动态合图的最大图集数量。
社区版会根据设备最大纹理数和 Char 缓存模式字符图集的相关设置自动调整动态合图的最大图集数量。
这不意味着你不能手动调整了,而是建议你阅读新动态图集和新 Char 缓存模式相关的文档后再考虑是否有必要进行调整。
关于这个你可以查看 [提升项目性能](./best-practices/batcher-guide.md) 了解。
关于这个你可以查看 [提升项目性能](./best-practices/performance-guide.md) 了解。
- **动态图集重复纹理的判断从 `texture._id` 改为使用 `texture._uuid`**
@ -65,12 +65,12 @@ cc.macro.ENABLE_NATIVE_TTF_RENDERER = false;
---
### 材质 Hash 计算的变化
解决材质本身 Hash 变化不会更新材质变体的 Hash 的问题时,为了兼顾原生平台与 Web 平台,我们采取了使材质本身的 Hash 值不变并且修改变体 Hash 计算方式的方法来解决这个问题
之前,材质的 Hash 发生变化时不会同时更新现有的材质变体 Hash这导致在修改前创建的变体不能与修改后创建的变体合批因为 Hash 不同)
解决这个问题后,在两个材质变体一样的情况下,无论怎么修改材质,都不会影响该材质的变体进行合批(在这之前,修改材质后生成的变体无法和之前的变体合批,因为 Hash 值问题)
为了兼顾原生平台与 Web 平台,我们通过使材质本身的 Hash 值不变,并且改变变体的 Hash 计算方式来解决这个问题
但这引入了新的问题,这会导致完全相同的两个材质不能合批,比如你复制了一个 `multi-2d-sprite` 材质,分别使用这两个材质的组件不再会进行合批。
但这引入了新的问题:完全相同的两个材质不能合批。
我们考虑了性能、影响程度等多方面因素之后采取了这个实现,因为后者比较少见,并且可以手动解决:
比如你复制了一个 `multi-2d-sprite` 材质,分别使用这两个材质的组件不再会进行合批。
你只需要手动设置该材质的 Hash 值为 `multi-2d-sprite` 材质的 Hash 值即可使两个材质合批。
这种情况比较少见,如果你的项目发生了这种情况,可以手动将新材质的 Hash 值设置为旧材质的 Hash 值,即可让这两个材质合批。

View File

@ -5,7 +5,7 @@ description: "推荐使用此方式进行一键安装。"
# 一键安装
我们提供了一个**付费扩展**,该扩展**唯一的作用是帮助你一键安装和管理社区版的版本**。
我们提供了一个**付费扩展**,该扩展**唯一的作用是帮助你一键安装和管理社区版的版本**。
它也作为对我们给予肯定和支持的**赞助通道**。
@ -25,7 +25,7 @@ description: "推荐使用此方式进行一键安装。"
## 一键安装
依次点击 Cocos Creator 的菜单栏 **扩展 - 增强包管理 - 安装增强包 - 安装最新版本**,会自动开始安装社区版。
依次点击 Cocos Creator 的菜单栏 **扩展 - 社区版管理 - 安装社区版 - 安装最新版本**,会自动开始安装社区版。
![plugin-install](./assets/plugin-install.png)
@ -44,7 +44,7 @@ description: "推荐使用此方式进行一键安装。"
### 安装其它版本
依次点击 Cocos Creator 的菜单栏 **扩展 - 增强包管理 - 安装增强包 - 安装其它版本** 可以安装当前引擎支持安装的所有版本。
依次点击 Cocos Creator 的菜单栏 **扩展 - 社区版管理 - 安装社区版 - 安装其它版本** 可以安装当前引擎支持安装的所有版本。
可以重复执行安装操作,扩展会自动进行覆盖。
@ -58,7 +58,7 @@ description: "推荐使用此方式进行一键安装。"
## 查看信息
依次点击 Cocos Creator 的菜单栏 **扩展 - 增强包管理 - 查看信息**,会打印当前环境信息。
依次点击 Cocos Creator 的菜单栏 **扩展 - 社区版管理 - 查看信息**,会打印当前环境信息。
![plugin-info](./assets/plugin-info.png)

View File

@ -46,6 +46,8 @@ description: "需掌握一定的自定义引擎知识。"
按照官方的 [扩展安装](https://docs.cocos.com/creator/2.4/manual/zh/extension/install-and-share.html) 文档将压缩包内的 `extension` 目录放到项目的 `packages` 目录即可。
建议将 `extension` 目录重命名成一个更有意义的名字,比如 `enhance-kit`
:::caution 注意
- 请勿将此引擎扩展与 [一键安装](./installation-auto) 中的付费引擎扩展混淆!

View File

@ -115,7 +115,7 @@ Label 一直是项目优化的最难点,因为它完全不能和其它的渲
**启动 Cocos Creator 报 Error: Can not parse this input:undefined 错误**
你可能忘记安装配套的引擎扩展,所以没有找到增强包的内置资源,导致报错,请仔细阅读文档。
你可能忘记安装配套的引擎扩展,所以没有找到社区版的内置资源,导致报错,请仔细阅读文档。
**原生平台或模拟器报错Assertion failed: (_type == Type::String), function toString, file Value.cpp, line 496.**
@ -139,7 +139,7 @@ Label 一直是项目优化的最难点,因为它完全不能和其它的渲
2. 需要进行释放的 spine 资源,不让其参与动态合图(通过控制 Spine 组件的合图开关)。
3. 不释放需要参与动态合图的 spine 资源。
该问题已在 v2.4.13 版本修复,请升级增强包版本至 v2.0.0 以上。
该问题已在 v2.4.13 版本修复,请升级社区版至 v2.0.0 以上。
## 支持我们

View File

@ -4,20 +4,22 @@ sidebar_position: 6
# 卸载
增强包不会对项目进行修改,但如果你的项目已经使用了就像要将引擎降级一样,这种操作还是有风险的,所以我们提供两种卸载方式以供参考:
:::tip 提示
因为原理是一样的,即使是手动安装的增强包,依然可以通过引擎扩展进行卸载,反之亦然。
卸载的原理相同,手动安装后不一定必须手动卸载,也可以使用付费扩展进行卸载,反之亦然。
:::
---
## 使用引擎扩展卸载
## 卸载前检查
请参考 [手动卸载](#手动卸载) 中提到的 **解除代码依赖与资源依赖**,确保项目不再依赖任何增强包的特性之后再卸载。
- 检查项目代码不再依赖社区版提供的特性。
- 检查项目没有对社区版扩展内提供的内置资源的引用。
在 Cocos Creator 的菜单栏依次点击 **扩展 - 增强包管理 - 卸载增强包** 即可。
## 一键卸载
以下内容仅针对付费引擎扩展编写,可查看 [一键安装](./installation/installation-auto.md) 了解详情。
依次点击编辑器菜单栏 **扩展 - 社区版管理 - 卸载社区版** 即可。
![plugin-uninstall](./assets/plugin-uninstall.png)
@ -26,20 +28,14 @@ sidebar_position: 6
---
## 手动卸载
### 1.代码依赖
如果你的是 TypeScript 项目,则可以先删除 `creator-sp.d.ts` 文件,让 TypeScript 对使用了增强包接口的代码发出报错。
之后我们要确保所有代码都不再依赖增强包的特性。
### 2.资源依赖
增强包提供了一些内置资源,像是多纹理 Effect 着色器资源,你可以通过查找 UUID 引用将对增强包内置资源的引用全部移除。
### 3.恢复自定义引擎与删除扩展
打开 Cocos Creator 菜单的项目 - 项目设置 - 自定义引擎,勾选使用内置引擎。
依次点击编辑器菜单 **项目 - 项目设置 - 自定义引擎**,勾选使用内置引擎。
点击 Cocos Creator 主界面右上角的 **编辑器** 按钮,进入到编辑器的资源目录。
然后使用未修改过的 `jsb-adapter` 替换掉编辑器的 `Resources/builtin/jsb-adapter` 目录,最后将增强包的引擎扩展(比如 `extension` 目录)删除。
使用引擎原版的 `jsb-adapter` 替换 `Resources/builtin/jsb-adapter`
使用引擎原版的 `adapters` 替换 `Resources/builtin/adapters`
删除项目内安装的社区版扩展和 `creator-sp.d.ts` 文件。
重启编辑器生效。

View File

@ -13,11 +13,7 @@ description: "了解调校动态合图的方式。"
这样就只需要使用 1 个材质,也就是能在 1 Draw Call 里完成所有参与动态合图的纹理(包括 Bitmap 缓存模式 Label与 Char 缓存模式 Label 的渲染。
一般情况下不推荐直接修改 `maxAtlasCount`,请参考 [新的 Char 缓存模式](../text-render/text-char-mode.md#与动态图集合批的注意事项) 文档。
> 难道真正的原因是...
>
> ![7的意志](./assets/7.png)
一般情况下不推荐直接修改 `maxAtlasCount`,请参考 [Char 缓存模式](../text-render/text-char-mode.md#与动态图集合批的注意事项) 文档。
---
## 控制纹理是否参与动态合图

View File

@ -3,7 +3,7 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
# 动态合图
动态合图是一个非常好的合批手段,但是在之前引擎实现的比较简陋,所以增强包重构了动态合图系统,在原有功能基础上增加了许多重要特性。
动态合图是一个非常好的合批手段,但是在之前引擎实现的比较简陋,所以社区版重构了动态合图系统,在原有功能基础上增加了许多重要特性。
比如支持复用废弃碎图空间,优化了图集装箱算法,所有图集作为一个整体进行管理等等,你可以阅读下面的文档了解详情:

View File

@ -5,7 +5,7 @@ description: "随心所欲地控制动态合图的使用。"
# 手动管理合图
有时候你可能需要更细致地去控制哪些纹理加入动态图集,考虑到这一点,增强包在保留原来所有接口的基础上完全开放了动态图集相关的所有接口。
有时候你可能需要更细致地去控制哪些纹理加入动态图集,考虑到这一点,社区版在保留原来所有接口的基础上完全开放了动态图集相关的所有接口。
---
## 访问图集数组与已用空间集合
@ -31,7 +31,7 @@ cc.dynamicAtlasManager.rects
cc.dynamicAtlasManager.insertSpriteFrame(spriteFrame);
```
可以将 SpriteFrame 所使用的纹理添加到动态图集,这是引擎原有接口,但增强包对其做了一点修改,这个接口不再会检查纹理的 `packable` 属性,也就是变成了一个强制添加的接口。
可以将 SpriteFrame 所使用的纹理添加到动态图集,这是引擎原有接口,但社区版对其做了一点修改,这个接口不再会检查纹理的 `packable` 属性,也就是变成了一个强制添加的接口。
这样设计的原因是你可以将所有纹理的 `packable` 都设为 `false`,或者直接将 `maxFrameSize` 设为 `0`,然后完全手动地进行动态合图。

View File

@ -5,24 +5,15 @@ description: "了解如何手动进行多纹理合批。"
# 多纹理合批
在 [提升项目性能](../../best-practices/batcher-guide.md) 中提到了动态合图与多纹理渲染结合后,能让多张图集纹理在同一批次渲染
使用 [多纹理材质](./multi-material.md) 文档中提到的 `MultiHandler` 的接口来动态设置材质的纹理插槽可能会比较麻烦,比如你需要使用一个纹理时,还得找到该纹理所在的材质并设置到渲染组件上
如果你阅读过 [多纹理材质](./multi-material.md) 文档的话,肯定知道能使用 `MultiHandler` 的接口来动态设置材质的纹理插槽来实现
为了能更方便地进行多纹理合批,社区版为组件增加了自动切换多纹理材质的机制,并且封装了一个多纹理合批管理类 `cc.sp.MultiBatcher`
但是这种完全手动的方式实现起来比较麻烦,比如你需要使用一个纹理时,还得找到该纹理所在的材质并设置到渲染组件上
动态图集与字符图集使用的是全局多纹理合批管理器实例,可以通过 `cc.sp.multiBatcher` 访问
为了能更方便地进行多纹理合批,增强包封装了一个自动切换多纹理材质的机制与多纹理合批管理类 `cc.sp.MultiBatcher`
动态图集与字符图集使用的是一个全局的多纹理合批管理器实例,可以通过 `cc.sp.multiBatcher` 访问。
---
## 开关自动切换多纹理材质
要让动态合图自动进行多纹理合批,首先要解决设置材质的问题,当切换成动态图集的纹理时,需要自动将组件的材质设置为有动态图集纹理的材质。
所以我们增加了一个机制,在支持的组件内使用开启了该机制的纹理进行渲染时,会提前切换为该纹理关联的材质(只要支持多纹理渲染就支持自动切换材质)。
这个机制默认是开启的,可以通过全局开关来控制默认值:
可以通过全局开关来控制所有组件的默认值:
```js
cc.sp.autoSwitchMaterial = false;
@ -54,9 +45,10 @@ sprite.autoSwitchMaterial = cc.RenderComponent.EnableType.ENABLE;
:::
---
## 设置纹理的关联材质
我们为纹理增加了一个关联材质的概念,在支持的组件内对纹理进行渲染时,会提前切换为该纹理关联的材质。
:::info
每个纹理只能关联一个材质,如果同一个纹理,不同的渲染组件需要使用不同材质就需要手动设置。
@ -86,7 +78,6 @@ texture.unlinkMaterial();
const material = texture.getLinkedMaterial();
```
---
## 多纹理合批管理器
手动关联材质就意味着你需要手动创建并管理创建的所有材质,如果是大量纹理需要关联材质就会比较麻烦。
@ -119,7 +110,3 @@ const material = batcher.requsetMaterial(texture);
```js
batcher.reset();
```
### 它的用途
在 [进阶合批指南](../../best-practices/advance-batcher-guide.md) 中有提供一些常见的使用案例。

View File

@ -6,12 +6,12 @@ toc_max_heading_level: 5
# 多纹理材质
增强包在引擎内置了可以直接使用的多纹理 Effect 着色器资源,并且你可以直接使用多纹理材质而不需要编写任何代码
社区版新增了一个用于多纹理渲染的内置着色器资源,你可以直接使用该材质
---
## 创建多纹理材质
你可以正常创建一个材质文件Effect 选择内置的多纹理 Effect 着色器 `multi-2d-universal` 即可
创建一个材质Effect 选择内置的多纹理 Effect 着色器 `multi-2d-universal`
![material-settings](./assets/material-settings.png)
@ -32,7 +32,7 @@ toc_max_heading_level: 5
:::caution 警告
如果组件使用的纹理在材质中找不到,为了保证渲染的正常(毕竟性能只是锦上添花)会在组件的材质变体中将纹理设置到 `texture` 插槽中。
如果组件使用的纹理在材质中找不到,为了保证正常渲染,会在组件的材质变体中将纹理设置到 `texture` 插槽中。
这会导致这个组件的多纹理材质变体之后都不能按预期进行合批,就像 “退化” 成了普通材质。
@ -70,7 +70,7 @@ Spine 组件使用多纹理材质时会强制勾选 `enableBatch`,因为不开
---
## 通过代码设置纹理插槽
每个多纹理材质都对应着一个多纹理材质管理器,这是增强包新增的一个工具类,其主要用处是便捷、高性能地管理多纹理材质上面的纹理插槽。
每个多纹理材质都对应着一个多纹理材质管理器,这是社区版新增的一个工具类,其主要用处是便捷、高性能地管理多纹理材质上面的纹理插槽。
通过 `material.getMultiHandler()` 可以获取到管理器实例,请使用这个实例来操作多纹理材质的纹理插槽。

View File

@ -5,7 +5,7 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
:::tip 提示
多纹理渲染属于底层设施,如果你不是准备手动使用多纹理材质或者多纹理合批管理器的话,请跳过本特性文档。
多纹理渲染属于底层设施,若你不准备手动使用多纹理材质或者多纹理合批管理器的话,请跳过本特性文档。
:::
@ -15,7 +15,7 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
其根本原因是纹理是使用 uniform 变量传给着色器的,而需要合并批次的话不允许每次渲染都拥有不同的 uniform 变量值。
增强包实现的是先设置多个 uniform 变量,比如将 8 张纹理写入到 "texture1" "texture2" "texture3"... 的 8 个 uniform 变量中,然后在着色器里再判断应该在渲染时使用哪个 uniform 变量。
社区版现在的实现是先设置多个 uniform 变量,比如将 8 张纹理写入到 "texture1" "texture2" "texture3"... 的 8 个 uniform 变量中,然后在着色器里再判断应该在渲染时使用哪个 uniform 变量。
这样的话如果所有渲染都只用这 8 张纹理,就都能合并为 1 个批次。

View File

@ -5,7 +5,7 @@ description: "像其它渲染组件一样在 Spine 组件上使用动态合图
# 动态合图
你可以像其它渲染组件一样在 Spine 组件上使用动态合图,如果想了解有关动态合图的更多详情,可以阅读 [动态合图](../dynamic-batcher/dynamic-batcher-intro.mdx) 文档。
你可以像其它渲染组件一样在 Spine 组件上使用动态合图,如果想了解有关动态合图的更多详情,可以阅读 [动态合图](../dynamic-batcher/dynamic-batcher-intro) 文档。
:::caution 注意

View File

@ -3,7 +3,7 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
# Spine
增强包解决了 Spine 在 Cocos Creator 中的三大痛点:
社区版解决了 Spine 在之前的三大痛点:
- 不参与动态合图
- 无法与其它组件合批
@ -12,11 +12,3 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
你可以阅读下面的文档了解详情:
<DocCardList items={useCurrentSidebarCategory().items}/>
:::caution 注意
由于引擎这部分的 C++ 实现与 JavaScript 实现在一些细节上不太一样,比如一些内部函数的执行时机。
所以当你在 Web 平台上测试得出的一些结论请不要想当然地以为在原生平台上也一样,具体实现差异请阅读 Spine 的原理文档。
:::

View File

@ -79,7 +79,7 @@ a.getRegion(slotName, attachmentName);
如果你只想替换其中一个组件,那么就可以克隆这个 SkeletonData 让每个组件都使用不同的 SkeletonData 实例进行渲染。
增强包提供了一个克隆数据的接口来实现这个需求:
社区版提供了一个克隆数据的接口来实现这个需求:
```js
const clonedSkeletonData = skeletonData.clone();

View File

@ -2,49 +2,40 @@
sidebar_position: 1
description: "详细了解该缓存模式重构后的所有新特性。"
---
# 新的 Char 缓存模式
# Char 缓存模式
在 [提升项目性能](../../best-practices/batcher-guide.md) 中提到 Bitmap 与 Char 缓存模式都支持了废弃字符空间复用的特性,但 Char 缓存模式的内部变化比较大,并且提供了一些可调整的设置项,使用上依旧只需要设置缓存模式即可。
在 [提升游戏性能](../../best-practices/performance-guide) 中,我们提到了社区版使 Bitmap 与 Char 缓存模式都支持了废弃字符空间复用的特性。
除此之外Char 缓存模式还提供了一些可调整的设置。
---
## 在场景切换时清空所有字符图集
控制在场景切换时是否会清空所有的字符图集,默认为开启状态。
控制在场景切换时是否会清空所有的字符图集,考虑到旧项目兼容,默认为开启状态。
```js
cc.sp.charAtlasAutoResetBeforeSceneLoad = false;
```
:::tip 提示
在引擎原来的设计中,该机制不可被关闭,现在推荐关闭该机制。
在引擎原来的设计中,该机制不可被关闭,由于旧 Char 缓存模式不支持复用废弃的空间,图集终究会被用完,所以引擎加入了这个治标不治本的功能。
现在推荐关闭该机制,除非你知道你需要。
:::
---
## 字符图集的数量与内置材质
现在在内部最多会创建 8 张字符图集与多纹理材质的最大纹理插槽数一致如果合理使用缓存模式8 张应该对所有项目都是足够的。
在这种情况下,可能发生的事是 Char 缓存模式的组件使用了一个普通材质,这个材质只能使用第一张字符图集进行渲染,那么就会导致其他图集上的字就无法渲染出来了
Char 缓存模式会在内部维护一个使用内置多纹理 Effect 着色器的材质Label 在渲染时会先判断当前所使用的是否为多纹理材质,是的话则判断是否能在材质纹理插槽中找到字符图集纹理。
为了解决这个问题Char 缓存模式会在内部维护一个使用内置多纹理 Effect 着色器的材质,如果你有特殊的用途,可以通过
若任何判断不满足则会将组件的材质设为内部维护的材质。
如果你有特殊的用途,可以通过以下代码获取:
```js
const material = cc.Label._shareAtlas.material;
cc.Label._shareAtlas.material;
```
获取、修改或替换该材质
需注意 Char 字符图集是运行时才创建的,所以现在**暂时无法在 Char 缓存模式下设置组件的自定义材质**
渲染时内部会先判断当前所使用的是否为多纹理材质,是的话判断是否能在材质纹理插槽中找到字符图集纹理,如果有一个判断不满足则会将组件的材质设为内部维护的材质
要解决这个问题,你可以通过代码创建含有当前所有字符图集纹理的自定义材质来解决这个问题,但内部会不断创建新的字符图集(直到 8 张),所以需注意同步更新这个自定义材质,建议有自定义材质需求时使用 Bitmap 缓存模式
但 Char 字符图集是运行时才创建的,所以**暂时无法在使用 Char 缓存模式时直接设置自定义材质**。
你可以通过代码创建含有当前所有字符图集纹理的自定义材质来解决这个问题,但内部会不断创建新的字符图集(直到 8 张),所以需注意同步更新这个自定义材质,建议有自定义材质需求时使用 Bitmap 缓存模式。
---
## 与动态图集合批的注意事项
多纹理材质只有 8 个纹理插槽,默认情况下字符图集自动多纹理合批的数量为 1也就是说会将第 1 张字符图集纹理放入材质。
@ -69,13 +60,13 @@ class Example extends cc.Component {
一般情况下,代码位置 2 是当用户脚本被加载时就会被执行,而代码位置 1 可能需要等到引擎首场景加载后的某个时间执行。
增强包会自动调整动态图集的最大数量,这个调整的时机是在代码位置 2 之后的,所以比如你的项目对 Char 缓存模式使用量比较大时,想尝试将动态图集最大数量调整为 6自动合批的字符图集数量调整为 2那么你只需要在代码位置 2 修改字符图集自动多纹理合批的数量:
社区版会自动调整动态图集的最大数量,这个调整的时机是在代码位置 2 之后的,所以比如你的项目对 Char 缓存模式使用量比较大时,想尝试将动态图集最大数量调整为 6自动合批的字符图集数量调整为 2那么你只需要在代码位置 2 修改字符图集自动多纹理合批的数量:
```js
cc.sp.charAtlasAutoBatchCount = 2;
```
之后增强包会自动将动态图集的最大数量调整为 `8 - 2`,即 6。
之后社区版会自动将动态图集的最大数量调整为 `8 - 2`,即 6。
这个自动调整的时机并不意味着你在代码位置 2 修改动态图集的最大数量是无效的,因为一开始动态图集的最大数量为 `-1`,你打印一下可以看到
@ -83,7 +74,7 @@ cc.sp.charAtlasAutoBatchCount = 2;
console.log(cc.dynamicAtlasManager.maxAtlasCount); // -1
```
如果你在代码位置 2 修改了动态图集的最大数量,增强包就不会调整该值了。
如果你在代码位置 2 修改了动态图集的最大数量,社区版就不会调整该值了。
```js
cc.dynamicAtlasManager.maxAtlasCount = 5;
@ -100,7 +91,7 @@ cc.sp.charAtlasAutoBatchCount = 3;
比如上面这个设置,这会使得引擎需要用 2 个材质进行渲染,但是可用的动态图集扩充到了 13 张Char 能自动合批的图集数量扩充到了 3 张,对于某些项目来说可能并不是一件坏事。
增强包使用这个 “7 + 1” 的默认值有以下几点原因:
社区版使用这个 “7 + 1” 的默认值有以下几点原因:
- 引擎原本就只有 1 张 Char 字符图集
- 大多数项目使用 1 张 Char 字符图集是足够的

View File

@ -4,18 +4,16 @@ description: "一行代码开启高清文本渲染。"
---
# 高 DPI 支持
可阅读 [上手其它新特性](../../best-practices/new-features.md#高-dpi-文本渲染) 了解基本的使用方法,除了注意性能以外,没有其它的注意事项
可阅读 [提升游戏质量](../../best-practices/quality-guide) 了解基本的使用方法
---
## 调整全局开关
使用下面的代码控制组件是否默认开启高 DPI 支持:
使用下面的代码控制所有组件是否默认开启高 DPI 支持:
```js
cc.sp.enableLabelRetina = false;
```
---
## 调整渲染缩放比例
使用下面的代码调整内部渲染的缩放倍数:
@ -24,7 +22,6 @@ cc.sp.enableLabelRetina = false;
cc.sp.labelRetinaScale = 2;
```
---
## 控制单个组件开关
![reinasettings](./assets/reina-settings.png)

View File

@ -3,6 +3,6 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
# 文本渲染
文本渲染一般是游戏性能优化需要重点关注的地方,并且其显示效果也非常重要,所以增强包提供了以下新特性:
文本渲染一般是游戏性能优化需要重点关注的地方,并且其显示效果也非常重要,所以社区版提供了以下新特性:
<DocCardList items={useCurrentSidebarCategory().items}/>

View File

@ -5,7 +5,7 @@ description: "像其它渲染组件一样在 Spine 组件上使用动态合图
# 复用 Culling 数据
一个 TiledMap 可能会有很多 TiledLayer如果开启了 Culling那这些 Layer 都需要单独计算 Culling 数据,增强包新增了在满足一定条件的情况下可以复用 Culling 数据的特性,以减少 CPU 的性能消耗。
一个 TiledMap 可能会有很多 TiledLayer如果开启了 Culling那这些 Layer 都需要单独计算 Culling 数据,社区版新增了在满足一定条件的情况下可以复用 Culling 数据的特性,以减少 CPU 的性能消耗。
## 大致原理

View File

@ -3,7 +3,7 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
# TiledMap
增强包对 TiledMap 进行了优化:
社区版对 TiledMap 进行了优化:
- 复用 TiledLayer 的 Culling 数据