完善 docs

This commit is contained in:
SmallMain 2022-06-13 21:51:01 +08:00
parent 6c704a5cd3
commit 6a3fc5c5d7
46 changed files with 39416 additions and 2 deletions

54
demo/.gitignore vendored Normal file
View File

@ -0,0 +1,54 @@
#/////////////////////////////////////////////////////////////////////////////
# Fireball Projects
#/////////////////////////////////////////////////////////////////////////////
/library/
/temp/
/local/
/build/
/packages/
#/////////////////////////////////////////////////////////////////////////////
# npm files
#/////////////////////////////////////////////////////////////////////////////
npm-debug.log
node_modules/
#/////////////////////////////////////////////////////////////////////////////
# Logs and databases
#/////////////////////////////////////////////////////////////////////////////
*.log
*.sql
*.sqlite
#/////////////////////////////////////////////////////////////////////////////
# files for debugger
#/////////////////////////////////////////////////////////////////////////////
*.sln
*.pidb
*.suo
#/////////////////////////////////////////////////////////////////////////////
# OS generated files
#/////////////////////////////////////////////////////////////////////////////
.DS_Store
ehthumbs.db
Thumbs.db
#/////////////////////////////////////////////////////////////////////////////
# WebStorm files
#/////////////////////////////////////////////////////////////////////////////
.idea/
#//////////////////////////
# VS Code files
#//////////////////////////
.vscode/
creator-sp.d.ts

40
demo/README.md Executable file
View File

@ -0,0 +1,40 @@
# Cocos Service Pack Demo
这是对服务包所有特性做展示的 Cocos Creator 演示项目。
## 如何运行
1. 将项目克隆下来之后,根据文档中的 [安装指南](https://smallmain.github.io/cocos-service-pack/docs/installation-guide/installation-intro) 安装服务包。
2. 重启编辑器后运行项目的 `main.fire` 场景。
// Cocos Creator SP v2.4.x
// 提供内置的多纹理材质8、16 纹理插槽),并根据设备使用不同的材质
// 扩展 Sprite、Label、RichText、MotionSteak、Spine 组件原生支持多纹理材质
// 新增多纹理合批管理器:每个纹理都会对应一个材质,当纹理在渲染组件中使用时,会自动切换至对应的材质,支持控制全局默认是否自动切换,单个组件是否自动切换
// 重构动态合图在原有功能的基础上支持1.完全开放所有接口以手动规划图集 2.增加全局默认是否参与动态合图的开关,单个组件是否参与的开关 3.增加在场景切换时是否清空所有图集的开关(原来是必定清空) 4.支持自动加入多纹理合批 5.自动根据设备支持的最大多纹理数量调整最大图集数量 6.优化装箱算法Guillotine7.支持复用被删除的空间 8.所有子图集作为一个整体进行管理不会出现一张纹理被加入到两张图集的问题9.修复动态图集一个内存泄漏问题
// 扩展 RichText支持自定义材质
// 扩展 Spine支持使用 SpriteFrame 换装
// 扩展 Label支持高 DPI 文本渲染
// 扩展 LabelBITMAP 模式会复用同样式同文本的纹理CHAR 模式改为使用多个图集但是支持自动加入多纹理合批这样就能与动态图集一起合批增加配置默认情况下动态图集最高8-1张Char 图集为 1 张(无论如何设置,在装不完的情况下,因为需要正常渲染,都会最高使用 8 张图集,但是只有设置的数量才会加入多纹理合批,并且会创建一个专属材质,如果该材质无法完成渲染,会使用专属材质,或者可以仿照 spine flush buffer
// 扩展 Spine支持自动切换材质与动态图集
// 提醒 Spine 的材质自动切换会有缓存,修改关联的材质后,生效可以手动清除 comp._materialCache = {};,其它组件的材质生效需要 setVertsDirty
// 提醒 cc.SkeletonData.createSpriteFrame ,如果 region 的旋转角度不是 270 或 0 不能完美转换,但不影响自动合图
// 提醒 SpineData 如果同时使用多个 texture只会使用第一个 texture 的 multiMaterial 进行自动切换
// Spine 需要更多测试SkeletonData 克隆会有 ref 问题吗?
// 注意:因 MotionSteak 直接使用 texture 而不是 spriteFrame所以不支持动态图集
// 注意Spine 使用多纹理材质时只支持使用 REALTIME 模式,并且会强制关闭 useTint 与开启 enableBatch
// 注意:序列帧动画的性能下降(具体多少待测试)
// 之后:
// 查找所有 TODO
// 插件适配 Windows
// 演示项目
// 插件适配两个版本:最新版与 2.4.6 版本
// 适配原生平台
// 适配 Spine 缓存模式
// 新增静态合批:在一个节点树的根节点挂上一个组件,该组件会快照这个节点树并显示为一张图片,然后只接管渲染,不影响其它逻辑

24
demo/assets/common.meta Normal file
View File

@ -0,0 +1,24 @@
{
"ver": "1.1.2",
"uuid": "db4cffdc-d84c-4572-9dda-3d00e0d6302c",
"isBundle": true,
"bundleName": "",
"priority": 1,
"compressionType": {
"web-mobile": "merge_all_json",
"web-desktop": "merge_all_json"
},
"optimizeHotUpdate": {
"web-mobile": false,
"web-desktop": false
},
"inlineSpriteFrames": {
"web-mobile": false,
"web-desktop": false
},
"isRemoteBundle": {
"web-mobile": false,
"web-desktop": false
},
"subMetas": {}
}

View File

@ -0,0 +1,12 @@
{
"ver": "1.1.2",
"uuid": "e59a44db-4029-4fa6-96af-71fc9321ed0e",
"isBundle": false,
"bundleName": "",
"priority": 1,
"compressionType": {},
"optimizeHotUpdate": {},
"inlineSpriteFrames": {},
"isRemoteBundle": {},
"subMetas": {}
}

Binary file not shown.

After

Width:  |  Height:  |  Size: 83 KiB

View File

@ -0,0 +1,36 @@
{
"ver": "2.3.5",
"uuid": "c11dfdd2-97c6-409c-9c0f-fdfa681f16a9",
"type": "sprite",
"wrapMode": "clamp",
"filterMode": "bilinear",
"premultiplyAlpha": false,
"genMipmaps": false,
"packable": true,
"width": 402,
"height": 370,
"platformSettings": {},
"subMetas": {
"1655112479313": {
"ver": "1.0.4",
"uuid": "a766c72a-5fe2-4221-9452-d79edb33286a",
"rawTextureUuid": "c11dfdd2-97c6-409c-9c0f-fdfa681f16a9",
"trimType": "auto",
"trimThreshold": 1,
"rotated": false,
"offsetX": 0,
"offsetY": 0,
"trimX": 0,
"trimY": 0,
"width": 402,
"height": 370,
"rawWidth": 402,
"rawHeight": 370,
"borderTop": 0,
"borderBottom": 0,
"borderLeft": 0,
"borderRight": 0,
"subMetas": {}
}
}
}

Binary file not shown.

After

Width:  |  Height:  |  Size: 198 KiB

View File

@ -0,0 +1,36 @@
{
"ver": "2.3.5",
"uuid": "6231041a-75a5-4af2-a40d-f27e9498901a",
"type": "sprite",
"wrapMode": "clamp",
"filterMode": "bilinear",
"premultiplyAlpha": false,
"genMipmaps": false,
"packable": true,
"width": 556,
"height": 606,
"platformSettings": {},
"subMetas": {
"1655112514006": {
"ver": "1.0.4",
"uuid": "85c932be-f6c8-48a3-b450-7d0d530c4522",
"rawTextureUuid": "6231041a-75a5-4af2-a40d-f27e9498901a",
"trimType": "auto",
"trimThreshold": 1,
"rotated": false,
"offsetX": 0,
"offsetY": 0,
"trimX": 0,
"trimY": 0,
"width": 556,
"height": 606,
"rawWidth": 556,
"rawHeight": 606,
"borderTop": 0,
"borderBottom": 0,
"borderLeft": 0,
"borderRight": 0,
"subMetas": {}
}
}
}

Binary file not shown.

After

Width:  |  Height:  |  Size: 291 KiB

View File

@ -0,0 +1,36 @@
{
"ver": "2.3.5",
"uuid": "398d85b3-4934-44c0-8d8e-3812b99f015e",
"type": "sprite",
"wrapMode": "clamp",
"filterMode": "bilinear",
"premultiplyAlpha": false,
"genMipmaps": false,
"packable": true,
"width": 656,
"height": 992,
"platformSettings": {},
"subMetas": {
"1655112526123": {
"ver": "1.0.4",
"uuid": "09a373ff-f600-4ffd-873b-027c54059f90",
"rawTextureUuid": "398d85b3-4934-44c0-8d8e-3812b99f015e",
"trimType": "auto",
"trimThreshold": 1,
"rotated": false,
"offsetX": 0,
"offsetY": 0,
"trimX": 0,
"trimY": 0,
"width": 656,
"height": 992,
"rawWidth": 656,
"rawHeight": 992,
"borderTop": 0,
"borderBottom": 0,
"borderLeft": 0,
"borderRight": 0,
"subMetas": {}
}
}
}

Binary file not shown.

After

Width:  |  Height:  |  Size: 102 KiB

View File

@ -0,0 +1,36 @@
{
"ver": "2.3.5",
"uuid": "d06d24ff-c18a-4940-82f9-4fe3c2ab8e96",
"type": "sprite",
"wrapMode": "clamp",
"filterMode": "bilinear",
"premultiplyAlpha": false,
"genMipmaps": false,
"packable": true,
"width": 596,
"height": 672,
"platformSettings": {},
"subMetas": {
"1655112538161": {
"ver": "1.0.4",
"uuid": "705578c6-1342-4c52-a1a5-8b48e60a64c5",
"rawTextureUuid": "d06d24ff-c18a-4940-82f9-4fe3c2ab8e96",
"trimType": "auto",
"trimThreshold": 1,
"rotated": false,
"offsetX": 0,
"offsetY": 0,
"trimX": 0,
"trimY": 0,
"width": 596,
"height": 672,
"rawWidth": 596,
"rawHeight": 672,
"borderTop": 0,
"borderBottom": 0,
"borderLeft": 0,
"borderRight": 0,
"subMetas": {}
}
}
}

Binary file not shown.

After

Width:  |  Height:  |  Size: 105 KiB

View File

@ -0,0 +1,36 @@
{
"ver": "2.3.5",
"uuid": "6843f00b-0ef4-4b7c-aac0-42ee42635e55",
"type": "sprite",
"wrapMode": "clamp",
"filterMode": "bilinear",
"premultiplyAlpha": false,
"genMipmaps": false,
"packable": true,
"width": 396,
"height": 570,
"platformSettings": {},
"subMetas": {
"1655112548981": {
"ver": "1.0.4",
"uuid": "87ffc647-0445-4890-a78d-c666a5ae7f6b",
"rawTextureUuid": "6843f00b-0ef4-4b7c-aac0-42ee42635e55",
"trimType": "auto",
"trimThreshold": 1,
"rotated": false,
"offsetX": 0,
"offsetY": 0,
"trimX": 0,
"trimY": 0,
"width": 396,
"height": 570,
"rawWidth": 396,
"rawHeight": 570,
"borderTop": 0,
"borderBottom": 0,
"borderLeft": 0,
"borderRight": 0,
"subMetas": {}
}
}
}

Binary file not shown.

After

Width:  |  Height:  |  Size: 144 KiB

View File

@ -0,0 +1,36 @@
{
"ver": "2.3.5",
"uuid": "702455ac-9b92-4dd7-b143-cb02342dbe48",
"type": "sprite",
"wrapMode": "clamp",
"filterMode": "bilinear",
"premultiplyAlpha": false,
"genMipmaps": false,
"packable": true,
"width": 660,
"height": 554,
"platformSettings": {},
"subMetas": {
"1655112563832": {
"ver": "1.0.4",
"uuid": "d006ef1c-d8c0-4228-973e-98a056ce3b09",
"rawTextureUuid": "702455ac-9b92-4dd7-b143-cb02342dbe48",
"trimType": "auto",
"trimThreshold": 1,
"rotated": false,
"offsetX": 0,
"offsetY": 0,
"trimX": 0,
"trimY": 0,
"width": 660,
"height": 554,
"rawWidth": 660,
"rawHeight": 554,
"borderTop": 0,
"borderBottom": 0,
"borderLeft": 0,
"borderRight": 0,
"subMetas": {}
}
}
}

Binary file not shown.

After

Width:  |  Height:  |  Size: 53 KiB

View File

@ -0,0 +1,36 @@
{
"ver": "2.3.5",
"uuid": "1c8a3cc1-a452-4276-848d-2bdf30e6852a",
"type": "sprite",
"wrapMode": "clamp",
"filterMode": "bilinear",
"premultiplyAlpha": false,
"genMipmaps": false,
"packable": true,
"width": 564,
"height": 882,
"platformSettings": {},
"subMetas": {
"1655112624336": {
"ver": "1.0.4",
"uuid": "80dbdc44-7f81-47cb-8f5d-5a8e8d2bc73b",
"rawTextureUuid": "1c8a3cc1-a452-4276-848d-2bdf30e6852a",
"trimType": "auto",
"trimThreshold": 1,
"rotated": false,
"offsetX": 0,
"offsetY": 0,
"trimX": 0,
"trimY": 0,
"width": 564,
"height": 882,
"rawWidth": 564,
"rawHeight": 882,
"borderTop": 176,
"borderBottom": 155,
"borderLeft": 192,
"borderRight": 198,
"subMetas": {}
}
}
}

3146
demo/assets/main.fire Normal file

File diff suppressed because it is too large Load Diff

View File

@ -0,0 +1,7 @@
{
"ver": "1.2.9",
"uuid": "cab4af66-dc74-41b5-8826-79b3a30ba99a",
"asyncLoadAssets": false,
"autoReleaseAssets": false,
"subMetas": {}
}

18
demo/assets/main.ts Normal file
View File

@ -0,0 +1,18 @@
const { ccclass, property } = cc._decorator;
@ccclass
export default class Main extends cc.Component {
@property(cc.Label)
version: cc.Label = null;
protected start(): void {
this.version.string = `Version: v${cc.sp.version}\n`;
}
}
cc.sp.labelRetinaScale = 2;
cc.dynamicAtlasManager.maxFrameSize = 2048;

9
demo/assets/main.ts.meta Normal file
View File

@ -0,0 +1,9 @@
{
"ver": "1.0.8",
"uuid": "2454f641-d633-4d4d-b624-73baf25e6af5",
"isPlugin": false,
"loadPluginInWeb": true,
"loadPluginInNative": true,
"loadPluginInEditor": false,
"subMetas": {}
}

View File

@ -0,0 +1,24 @@
{
"ver": "1.1.2",
"uuid": "1f1fc03d-012f-470f-bf1d-5108b0b2d09f",
"isBundle": true,
"bundleName": "",
"priority": 1,
"compressionType": {
"web-mobile": "merge_all_json",
"web-desktop": "merge_all_json"
},
"optimizeHotUpdate": {
"web-mobile": false,
"web-desktop": false
},
"inlineSpriteFrames": {
"web-mobile": false,
"web-desktop": false
},
"isRemoteBundle": {
"web-mobile": false,
"web-desktop": false
},
"subMetas": {}
}

View File

@ -0,0 +1,12 @@
{
"ver": "1.1.2",
"uuid": "6021871d-94b0-46eb-babf-799b228ea695",
"isBundle": false,
"bundleName": "",
"priority": 1,
"compressionType": {},
"optimizeHotUpdate": {},
"inlineSpriteFrames": {},
"isRemoteBundle": {},
"subMetas": {}
}

File diff suppressed because it is too large Load Diff

View File

@ -0,0 +1,8 @@
{
"ver": "1.2.9",
"uuid": "c5f3051e-1b4f-4384-939c-b838bcb8f5bf",
"optimizationPolicy": "AUTO",
"asyncLoadAssets": false,
"readonly": false,
"subMetas": {}
}

View File

@ -0,0 +1,28 @@
{
"__type__": "cc.Material",
"_name": "test-material",
"_objFlags": 0,
"_native": "",
"_effectAsset": {
"__uuid__": "5dcffc18-b913-460e-a0d9-5d74f4cda12b"
},
"_techniqueIndex": 0,
"_techniqueData": {
"0": {
"defines": {
"USE_TEXTURE": true
},
"props": {
"texture": {
"__uuid__": "c11dfdd2-97c6-409c-9c0f-fdfa681f16a9"
},
"texture2": {
"__uuid__": "1c8a3cc1-a452-4276-848d-2bdf30e6852a"
},
"texture3": {
"__uuid__": "6e056173-d285-473c-b206-40a7fff5386e"
}
}
}
}
}

View File

@ -0,0 +1,6 @@
{
"ver": "1.0.3",
"uuid": "0e00cf72-1eb0-457b-83d2-0171cc1cd97e",
"dataAsSubAsset": null,
"subMetas": {}
}

32073
demo/creator.d.ts vendored Normal file

File diff suppressed because it is too large Load Diff

13
demo/jsconfig.json Executable file
View File

@ -0,0 +1,13 @@
{
"compilerOptions": {
"target": "es6",
"module": "commonjs"
},
"exclude": [
"node_modules",
"library",
"local",
"settings",
"temp"
]
}

8
demo/project.json Executable file
View File

@ -0,0 +1,8 @@
{
"engine": "cocos2d-html5",
"packages": "packages",
"version": "2.4.5",
"name": "cocos-service-pack-demo",
"id": "00fac3aa-a82e-4242-8505-128adae1c6c7",
"isNew": false
}

13
demo/settings/builder.json Executable file
View File

@ -0,0 +1,13 @@
{
"excludeScenes": [],
"orientation": {
"landscapeLeft": true,
"landscapeRight": true,
"portrait": false,
"upsideDown": false
},
"packageName": "org.cocos2d.helloworld",
"startScene": "2d2f792f-a40c-49bb-a189-ed176a246e49",
"title": "hello_world",
"webOrientation": "auto"
}

View File

@ -0,0 +1,7 @@
{
"excludeScenes": [],
"packageName": "org.cocos2d.helloworld",
"platform": "web-mobile",
"startScene": "2d2f792f-a40c-49bb-a189-ed176a246e49",
"title": "HelloWorld"
}

37
demo/settings/project.json Executable file
View File

@ -0,0 +1,37 @@
{
"collision-matrix": [
[
true
]
],
"excluded-modules": [],
"group-list": [
"default"
],
"start-scene": "cab4af66-dc74-41b5-8826-79b3a30ba99a",
"design-resolution-width": 960,
"design-resolution-height": 640,
"fit-width": false,
"fit-height": true,
"use-project-simulator-setting": false,
"simulator-orientation": false,
"use-customize-simulator": true,
"simulator-resolution": {
"width": 960,
"height": 640
},
"last-module-event-record-time": 0,
"assets-sort-type": "name",
"facebook": {
"enable": false,
"appID": "",
"live": {
"enable": false
},
"audience": {
"enable": false
}
},
"preview-port": 7456,
"clear-simulator-cache": true
}

View File

@ -0,0 +1,6 @@
{
"game": {
"name": "未知游戏",
"appid": "UNKNOW"
}
}

19
demo/tsconfig.json Normal file
View File

@ -0,0 +1,19 @@
{
"compilerOptions": {
"module": "commonjs",
"lib": [ "es2015", "es2017", "dom" ],
"target": "es5",
"experimentalDecorators": true,
"skipLibCheck": true,
"outDir": "temp/vscode-dist",
"forceConsistentCasingInFileNames": true
},
"exclude": [
"node_modules",
"library",
"local",
"temp",
"build",
"settings"
]
}

View File

@ -0,0 +1,8 @@
---
sidebar_position: 3
description: "详细了解新 Char 缓存模式的实现方式。"
---
# 新 Char 缓存模式
TODO

View File

@ -1,8 +1,8 @@
--- ---
sidebar_position: 2 sidebar_position: 2
description: "详细了解动态合图的实现方式。" description: "详细了解动态合图的实现方式。"
--- ---
# 动态合图 # 动态合图
TODO TODO

View File

@ -0,0 +1,8 @@
---
sidebar_position: 4
description: "详细了解高 DPI 文本渲染的实现方式。"
---
# 高 DPI 文本渲染
TODO

View File

@ -0,0 +1,8 @@
---
sidebar_position: 5
description: "详细了解使 RichText 支持自定义材质的实现方式。"
---
# 使 RichText 支持自定义材质
TODO

View File

@ -0,0 +1,8 @@
---
sidebar_position: 5
description: "详细了解增强 Spine 的实现方式。"
---
# 增强 Spine
TODO

Binary file not shown.

After

Width:  |  Height:  |  Size: 95 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 722 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 120 KiB

View File

@ -5,6 +5,55 @@ description: "了解实现多纹理渲染的基础。"
# 多纹理材质 # 多纹理材质
## 创建多纹理材质
你可以正常创建一个材质文件Effect 选择内置的多纹理 Effect 着色器 `multi-2d-sprite` 即可。
![material-settings](./assets/material-settings.png)
可以看到上面有 `texture` - `texture8` 一共 8 个纹理插槽,将需要使用的纹理拖到上面的插槽即可完成多纹理材质的配置。
## 在组件中使用多纹理材质
直接拖到组件的 `Materials` 属性上即可。
![material-comp](./assets/material-comp.png)
注意上图中已经在 `cc.Sprite` 组件拖入了刚刚创建的多纹理材质,并且其 `SpriteFrame` 属性设置的是材质中 `texture3` 插槽中的纹理。
![material-final](./assets/material-final.png)
你不需要指定组件要使用的纹理插槽 id组件内部在渲染前会自动查找纹理在材质中的 id。
:::caution 警告
如果组件使用的纹理在材质中找不到,为了保证渲染的正常(毕竟性能只是锦上添花)会在组件的材质变体中将纹理设置到 `texture` 插槽中。
这会导致这个组件的多纹理材质变体之后都不能按预期进行合批,就像 “退化” 成了普通材质。
所以使用时必须要确保纹理在材质中,假如材质变体已经 “退化” 了,那你可以通过重新设置材质的方式使组件持有一个新的材质变体。
:::
## 自定义多纹理材质
上面介绍的多纹理材质都是使用的内置的多纹理 Effect 着色器,**如果你也创建了一个拥有多个纹理插槽的 Effect 着色器,直接使用并不会被直接识别为多纹理材质。**
## MultiHandler
这个是服务包新增的一个工具类,其主要用处是便捷、高性能地管理多纹理材质上面的所有纹理。
虽然你可以直接通过 `cc.Material` 上的接口来设置纹理插槽,但是出于性能考虑,**多纹理材质必须使用该类实例来进行纹理增删改的相关操作,否则可能导致不能正确渲染。**
它有以下接口:
### `setTexture(index: number, texture: cc.Texture2D): void`
设置纹理插槽上的纹理,
当我们说 “多纹理材质” 时,指的是持有 `cc.sp.MultiHandler` 实例的材质。 当我们说 “多纹理材质” 时,指的是持有 `cc.sp.MultiHandler` 实例的材质。
并且使用内置多纹理 Effect 着色器的材质会自动持有一个 `cc.sp.MultiHandler` 实例。 并且使用内置多纹理 Effect 着色器的材质会自动持有一个 `cc.sp.MultiHandler` 实例。

5
src/creator-sp.d.ts vendored
View File

@ -10,6 +10,11 @@ declare module cc {
*/ */
const inited: boolean, const inited: boolean,
/**
*
*/
const version: string,
/** /**
* *
* *