完善 docs

This commit is contained in:
SmallMain 2022-06-11 17:06:47 +08:00
parent 5a7f386f0a
commit 705a99fbd8
12 changed files with 157 additions and 17 deletions

View File

@ -29,7 +29,7 @@
- [功能演示](#功能演示) - [功能演示](#功能演示)
- [使用方法](#使用方法) - [使用方法](#使用方法)
- [更新日志](#更新日志) - [更新日志](#更新日志)
- [v1.0](#v10) - [Service Pack v1.0.0](#service-pack-v100)
- [贡献指南](#贡献指南) - [贡献指南](#贡献指南)
- [常见问题](#常见问题) - [常见问题](#常见问题)
- [为什么要直接修改引擎?](#为什么要直接修改引擎) - [为什么要直接修改引擎?](#为什么要直接修改引擎)
@ -62,14 +62,14 @@ TODO
## 更新日志 ## 更新日志
### Service Pack v1.0 ### Service Pack v1.0.0
- **[新特性] 支持多纹理渲染** - **[新特性] 支持多纹理渲染**
- **[新特性] 重构动态图集,支持多个新特性** - **[新特性] 重构动态图集,支持多个新特性**
- **[新特性] 重构 cc.Label 的 Char 缓存模式,支持多个新特性** - **[新特性] 重构 cc.Label 的 Char 缓存模式,支持多个新特性**
- **[新特性] 支持高 DPI 文本渲染** - **[新特性] 支持高 DPI 文本渲染**
- **[新特性] cc.Spine 组件支持参与动态图集、与其它组件合批、使用 SpriteFrame 换装** - **[新特性] Spine 组件支持参与动态图集、与其它组件合批、使用 SpriteFrame 换装**
- [新特性] cc.Label、cc.RichText、cc.Sprite、cc.MotionStreak、cc.Spine 组件支持使用多纹理材质,并支持自动切换材质机制 - [新特性] cc.Label、cc.RichText、cc.Sprite、cc.MotionStreak、Spine 组件支持使用多纹理材质,并支持自动切换材质机制
- [新特性] cc.RichText 支持使用自定义材质 - [新特性] cc.RichText 支持使用自定义材质
- [修复] 直接修改 Effect 的属性不回导致其变体的 hash 值刷新 - [修复] 直接修改 Effect 的属性不回导致其变体的 hash 值刷新
- [调整] 默认禁用 Label 原生 TTF 渲染器 - [调整] 默认禁用 Label 原生 TTF 渲染器

Binary file not shown.

After

Width:  |  Height:  |  Size: 258 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 234 KiB

View File

@ -5,4 +5,69 @@ description: "推荐使用此方式进行一键安装。"
# 使用引擎扩展安装 # 使用引擎扩展安装
TODO ---
## 前往 Cocos Store 下载
项目的发起者 SmallMain 在 Cocos Store 发布了一个叫做 **Cocos Service Pack** 的引擎扩展。
**这个扩展唯一的作用就是帮助你管理服务包的版本(查看已安装版本、安装、卸载)。**
你可以在 [Cocos Store](TODO) 花费 ¥13.14 下载并安装这个扩展。
:::tip 常见问题
- **Service Pack 不是开源项目吗???**
Service Pack 是完全开源的项目,涉及到引擎的每个修改我们都开放源码并提供原理文档。
这个引擎扩展只会为你提供自动化的安装方式,即使以后也只会添加版本管理方面的功能。
你可以选择 [手动安装](./installation-manual) 服务包,只需要几分钟即可完成。
:::
---
## 一键安装
:::info 注意
如果遇到与这个扩展相关的问题或者建议,请不要在 Github 反馈,而是请在扩展的 **商店评论区** 进行反馈。
因为这个扩展的收益是个人的,所以也只由个人维护。
:::
在 Cocos Creator 的菜单栏依次点击 **扩展 - 服务包管理**,会弹出服务包管理界面。
![plugin-ui](./assets/plugin-ui.png)
如果是扩展支持的引擎版本,**安装服务包** 的按钮会亮起,点击即可一键完成安装。
:::note 扩展做了什么事
扩展会自动修改你项目的自定义引擎配置文件,将当前引擎内的 `jsb-adapter` 替换,在项目根目录放置 `creator.d.ts` 文件。
:::
之后重启即可生效。
可在项目预览时检查 Devtools Console 打印的是否为 `Cocos Creator SP v2.4.x`,是的话则已经成功安装。
![](./assets/installed-console.png)
接下来推荐你从 [入门教程](../start-guide/start-guide-intro) 开始了解服务包为你的开发都带来了哪些新特性!
---
## 支持的引擎版本
服务包每次的版本更新都只会发布最新版本的引擎压缩包,而这个扩展会额外适配其他引擎版本并内置在扩展里。
**当前扩展会维护两个 Cocos Creator 版本,分别是 v2.4.6 与最新版本。**
选择维护这两个版本是因为在 v2.4.7 这个版本出现了破坏性变更,而 v2.4.7 也正好是官方开始暂停新特性开发,只进行维护的版本。
也就是说:
- 项目如果是使用小于 v2.4.7 版本的引擎可以完全无痛升级至 v2.4.6。
- 项目如果是使用大于等于 v2.4.7 版本的引擎可以完全无痛升级至最新版。

View File

@ -5,7 +5,7 @@ description: "需掌握一定的自定义引擎知识。"
# 手动安装 # 手动安装
## Service Pack v1.0 ## Service Pack v1.0.0
适配 Cocos Creator v2.4.9 版本,[点此下载服务包](http://www.baidu.com) 适配 Cocos Creator v2.4.9 版本,[点此下载服务包](http://www.baidu.com)
@ -54,9 +54,9 @@ description: "需掌握一定的自定义引擎知识。"
:::caution 注意 :::caution 注意
**请勿将此引擎扩展与 “使用引擎扩展安装” 中所安装的引擎扩展混淆!** **请勿将此引擎扩展与 [使用引擎扩展安装](./installation-engine-plugin) 中的引擎扩展混淆!**
**该扩展只解决自定义引擎无法为引擎新增内置资源和扩展组件 inspector 的问题,是服务包开源的一部分**。 **该扩展提供了必需的内置资源,是服务包开源的一部分,请勿同时安装两个引擎扩展,这会引起冲突!**
::: :::

View File

@ -53,14 +53,14 @@ TODO
## 更新日志 ## 更新日志
### Service Pack v1.0 ### Service Pack v1.0.0
- **[新特性] 支持多纹理渲染** - **[新特性] 支持多纹理渲染**
- **[新特性] 重构动态图集,支持多个新特性** - **[新特性] 重构动态图集,支持多个新特性**
- **[新特性] 重构 cc.Label 的 Char 缓存模式,支持多个新特性** - **[新特性] 重构 cc.Label 的 Char 缓存模式,支持多个新特性**
- **[新特性] 支持高 DPI 文本渲染** - **[新特性] 支持高 DPI 文本渲染**
- **[新特性] cc.Spine 组件支持参与动态图集、与其它组件合批、使用 SpriteFrame 换装** - **[新特性] Spine 组件支持参与动态图集、与其它组件合批、使用 SpriteFrame 换装**
- [新特性] cc.Label、cc.RichText、cc.Sprite、cc.MotionStreak、cc.Spine 组件支持使用多纹理材质,并支持自动切换材质机制 - [新特性] cc.Label、cc.RichText、cc.Sprite、cc.MotionStreak、Spine 组件支持使用多纹理材质,并支持自动切换材质机制
- [新特性] cc.RichText 支持使用自定义材质 - [新特性] cc.RichText 支持使用自定义材质
- [修复] 直接修改 Effect 的属性不回导致其变体的 hash 值刷新 - [修复] 直接修改 Effect 的属性不回导致其变体的 hash 值刷新
- [调整] 默认禁用 Label 原生 TTF 渲染器 - [调整] 默认禁用 Label 原生 TTF 渲染器

Binary file not shown.

After

Width:  |  Height:  |  Size: 230 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 760 KiB

View File

@ -1,5 +1,5 @@
--- ---
sidebar_position: 3 sidebar_position: 4
description: "一般情况下都不需要了解。" description: "一般情况下都不需要了解。"
--- ---
@ -9,6 +9,7 @@ description: "一般情况下都不需要了解。"
但有些变化难以避免,在这里你可以检查所有变更,评估是否会造成巨大的影响。 但有些变化难以避免,在这里你可以检查所有变更,评估是否会造成巨大的影响。
---
### 默认禁用原生 TTF 渲染器 ### 默认禁用原生 TTF 渲染器
引擎的 Label 在使用 Char 缓存模式并且使用 TTF 字体时,会使用一个原生 TTF 渲染器。 引擎的 Label 在使用 Char 缓存模式并且使用 TTF 字体时,会使用一个原生 TTF 渲染器。
@ -23,6 +24,7 @@ description: "一般情况下都不需要了解。"
cc.macro.ENABLE_NATIVE_TTF_RENDERER = false; cc.macro.ENABLE_NATIVE_TTF_RENDERER = false;
``` ```
---
### 动态图集的一些变化 ### 动态图集的一些变化
对动态图集的重构虽然保持了所有原有接口不变,但有些细节和以前不同了。 对动态图集的重构虽然保持了所有原有接口不变,但有些细节和以前不同了。
@ -39,7 +41,7 @@ cc.macro.ENABLE_NATIVE_TTF_RENDERER = false;
- **动态图集重复纹理的判断从 `texture._id` 改为使用 `texture._uuid`** - **动态图集重复纹理的判断从 `texture._id` 改为使用 `texture._uuid`**
具体的设计原因和原理可前往 [动态](TODO) 文档进行了解。 具体的设计原因和原理可前往 [动态图](TODO) 文档进行了解。
- **`cc.dynamicAtlasManager.insertSpriteFrame(spriteFrame)` 不再检查纹理的 `packable` 属性** - **`cc.dynamicAtlasManager.insertSpriteFrame(spriteFrame)` 不再检查纹理的 `packable` 属性**
@ -49,6 +51,7 @@ cc.macro.ENABLE_NATIVE_TTF_RENDERER = false;
这个就是因为动态图集被重构了,如果你的项目依赖一些未公开的类或者接口(引擎在 `creator.d.ts` 声明了的则是已经公开的),则可能需要重新编写。 这个就是因为动态图集被重构了,如果你的项目依赖一些未公开的类或者接口(引擎在 `creator.d.ts` 声明了的则是已经公开的),则可能需要重新编写。
---
### 使用 Char 缓存模式的 Label 暂不支持在编辑器中设置材质 ### 使用 Char 缓存模式的 Label 暂不支持在编辑器中设置材质
如果项目中有 Label 使用了 Char 缓存模式并且设置了自定义材质,可能会失效,具体原因可前往 [Char 缓存模式](TODO) 文档进行了解。 如果项目中有 Label 使用了 Char 缓存模式并且设置了自定义材质,可能会失效,具体原因可前往 [Char 缓存模式](TODO) 文档进行了解。

View File

@ -0,0 +1,61 @@
---
sidebar_position: 3
description: "了解并上手服务包提供的所有其他新特性。"
---
# 上手其它新特性
除了前面提到的多纹理渲染、新动态图集、新 Label Char 缓存模式等特性之外,还有一些其它也很实用的新特性。
---
## 高 DPI 文本渲染
以前我们会使用将 Label 字号放大一倍Label 节点缩小一倍的方式去解决字体模糊的问题。
而现在不需要了,高 DPI 文本渲染默认是关闭的,你可以通过
```
cc.sp.labelRetinaScale = 2; // 渲染文本时纹理的缩放倍数,默认值为 1.
```
来开启高 DPI 文本渲染。
![labelscaledemo](./assets/labelscaledemo.png)
> 图片中,上方的是开启后效果,下面是未开启效果。
**推荐你根据设备像素比devicePixelRatio来动态设置该值并且该值不要大于 `2`,这不会带来更好的效果,但却将字体纹理放大了数倍,会影响到游戏整体性能,影响动态图集的效率。**
可前往 [高 DPI 支持](TODO) 文档了解更多详情。
---
## 使用 SpriteFrame 进行 Spine 换装
官方文档中介绍了替换 attachment 对象进行换装的方法,但如果动画中有切换 attachment 的关键帧,这种方法就失效了。
还有一种方法是替换 attachment 的 region 对象来进行换装,但这种方法引擎没有直接支持,所以服务包对其进行了完善。
只需要一句代码即可使用 cc.SpriteFrame 替换指定 attachment 的 region 对象:
```
this.skel.setRegion('head', 'head', sp.SkeletonData.createRegion(spriteFrame));
```
![changespine](./assets/changespine.png)
> 图片中是被换头的小男孩。
这样做是直接替换了 SkeletonData 中的数据,一般情况下所有使用该数据的 Spine 组件都会受到影响,但我们提供了克隆 SkeletonData 数据的接口,可前往 [Spine](TODO) 文档了解更多详情。
:::tip 提示
还有一个小特性Spine 组件也支持了自动参与动态图集,并且也支持了和其它组件合批。
:::
---
## 给 RichText 使用自定义材质
这可能是很少用得到的功能,虽然加上去也简单,但主要还是我们看到几乎所有渲染组件可以自定义材质,这个组件却不可以。
可前往 [RichText](TODO) 了解更多详情。

View File

@ -14,10 +14,16 @@ sidebar_position: 5
::: :::
---
## 使用引擎扩展卸载 ## 使用引擎扩展卸载
TODO 请参考 [手动卸载](#手动卸载) 中提到的 **解除代码与资源依赖**,确保项目不再依赖任何服务包的特性之后,点击服务包管理界面的 **卸载服务包** 按钮,会自动帮你恢复自定义引擎,将引擎内的 `jsb-adapter` 替换为原版备份,并删除 `creator-sp.d.ts` 文件。
![extuninstall](./assets/ext-uninstall.png)
之后重启即可生效。
---
## 手动卸载 ## 手动卸载
### 1.代码依赖 ### 1.代码依赖
@ -34,4 +40,8 @@ TODO
打开 Cocos Creator 菜单的项目 - 项目设置 - 自定义引擎,勾选使用内置引擎。 打开 Cocos Creator 菜单的项目 - 项目设置 - 自定义引擎,勾选使用内置引擎。
点击 Cocos Creator 主界面右上角的 **编辑器** 按钮,进入到编辑器的资源目录。
接着使用未修改过的 `jsb-adapter` 替换掉编辑器的 `Resources/builtin/jsb-adapter` 目录。
将服务包相关的扩展(比如 `service-pack-support` 目录)删除。 将服务包相关的扩展(比如 `service-pack-support` 目录)删除。

View File

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