3.4 材质系统 (cocos#1986)

材质系统

Author: UniqueDisplayNameIsInUse

zh/SUMMARY.md

@@ -1,29 +1,29 @@
 # Summary
 
-## 新手入门
+[Cocos Creator 3.4 用户手册](index.md)
 
-[介绍](index.md)
+## 基础使用
 
-- [基础使用](getting-started/index.md)
+- [新手上路](getting-started/index.md)
     - [关于 Cocos Creator](getting-started/introduction/index.md)
     - [安装和启动](getting-started/install/index.md)
     - [使用 Dashboard](getting-started/dashboard/index.md)
     - [Hello World!](getting-started/helloworld/index.md)
     - [项目结构](getting-started/project-structure/index.md)
-    - [编辑器界面](editor/index.md)
-        - [场景编辑器](editor/scene/index.md)
-        - [层级管理器](editor/hierarchy/index.md)
-        - [资源管理器](editor/assets/index.md)
-        - [属性检查器](editor/inspector/index.md)
-        - [控制台](editor/console/index.md)
-        - [偏好设置](editor/preferences/index.md)
-        - [项目设置](editor/project/index.md)
-        - [主菜单](editor/mainMenu/index.md)
-        - [工具栏](editor/toolbar/index.md)
-        - [编辑器布局](editor/editor-layout/index.md)
-        - [预览调试](editor/preview/index.md)
-    - [获取帮助和支持](getting-started/support.md)
-    - [注意事项](getting-started/attention/index.md)
+- [编辑器界面](editor/index.md)
+    - [场景编辑器](editor/scene/index.md)
+    - [层级管理器](editor/hierarchy/index.md)
+    - [资源管理器](editor/assets/index.md)
+    - [属性检查器](editor/inspector/index.md)
+    - [控制台](editor/console/index.md)
+    - [偏好设置](editor/preferences/index.md)
+    - [项目设置](editor/project/index.md)
+    - [主菜单](editor/mainMenu/index.md)
+    - [工具栏](editor/toolbar/index.md)
+    - [编辑器布局](editor/editor-layout/index.md)
+    - [预览调试](editor/preview/index.md)
+- [获取帮助和支持](getting-started/support.md)
+- [注意事项](getting-started/attention/index.md)
 - [快速上手：制作第一个游戏](getting-started/first-game/index.md)
 - [升级指南](release-notes/index.md)
     - [v3.0 升级指南](release-notes/upgrade-guide-v3.0.md)
@@ -33,7 +33,7 @@
     - [资源分包升级指南](asset/subpackage-upgrade-guide.md)
     - [资源管理模块升级指南](asset/asset-manager-upgrade-guide.md)
 
-## 基本工作流
+## 工作流
 
 - [场景制作](concepts/scene/index.md)
     - [场景资源](asset/scene.md)
@@ -147,10 +147,26 @@
         - [压缩纹理](asset/compress-texture.md)
         - [渲染纹理](asset/render-texture.md)
     - [材质系统](material-system/overview.md)
-        - [YAML 101](material-system/yaml-101.md)
-        - [Effect Syntax](material-system/effect-syntax.md)
-        - [Pass Params](material-system/pass-parameter-list.md)
-        - [Builtin Shader Uniforms](material-system/builtin-shader-uniforms.md)
+        - [在脚本中使用材质](material-system/material-script.md)
+        - [内置材质](material-system/builtin-material.md)
+        - [材质系统类图](material-system/material-structure.md)
+    - [着色器](shader/index.md)
+        - [着色器资源](shader/effect-inspector.md)
+        - [着色器语法](shader/effect-syntax.md)
+            - [Pass 可选配置参数](shader/pass-parameter-list.md)
+            - [YAML 101 语法简介](shader/yaml-101.md)
+            - [GLSL 语法简介](shader/glsl.md)
+            - [预处理宏定义](shader/macros.md)
+            - [着色器片段（Chunk）](shader/effect-chunk-index.md)
+                - [Cocos Effect 内置 Uniform](shader/uniform.md)
+        - [内置着色器](shader/effect-builtin.md)
+            - [基于物理的光照模型 PBR](shader/effect-builtin-pbr.md)
+            - [卡通渲染](shader/effect-builtin-toon.md)
+            - [无光照](shader/effect-builtin-unlit.md)
+        - [自定义着色器](shader/write-effect-overview.md)
+            - [3D 着色器：RimLight](shader/write-effect-3d-rim-light.md)
+            - [2D 着色器：Gradient](shader/write-effect-2d-sprite-gradient.md)
+
     - [特效组件](module-map/effects/index.md)
         - [广告牌](particle-system/billboard-component.md)
         - [线段组件](particle-system/line-component.md)

zh/asset/material.md

@@ -1,31 +1,77 @@
-## 材质资源
+# 材质资源
 
-### 材质创建
+## 材质创建
 
-材质创建方式如下：
+在 **资源管理器** 面板中点击右键并选择 **创建 -> 材质**：
 
 ![material-create](material/material-create.png)
 
-或
+或者点击 **资源管理器** 左上角的 **+** 号按钮并选择 **材质**：
 
 ![material-create-menu](material/material-create-menu.png)
 
-材质控制着每个模型最终的着色，材质由 Effect 构成，由材质操控 Effect 的着色流程。材质本身也可以看作是 Effect 资源的容器，材质可以任意切换当前要使用的 Effect 资源。下图就是我们创建的材质默认选择的 Effect 资源。
+此时便会在 **资源管理器** 中创建一个默认名为 **material** 的材质资源：
 
-![default-effect](material/default-effect.png)
+![default-material](material/default-material.png)
 
-同时，我们还可以通过点击 Effect 属性右边的框要切换当前材质的 Effect。
+材质控制着每个模型最终的着色，材质由着色器构成，通过材质和着色器控制最终的着色流程。
 
-![effects](material/effects.png)
+## 材质资源属性
 
-### Effect 创建
+| 属性 | 说明 |
+| :-- | :-- |
+| Effect（着色器） | 当前材质所使用的着色器，默认使用的是内置 PBR 着色器 [builtin-standard.effect](../shader/effect-builtin-pbr.md)。<br>点击 Effect 的下拉框，可以看到当前项目中所有的着色器，开发者可根据需要选择使用。当切换了着色器后其他属性也会同步更新，详情请参考 [着色器](../shader/effect-inspector.md)。<br>点击右侧的 ![image](../material-system/img/locate.png) 按钮，会在 **资源管理器** 中定位当前使用的着色器。|
+| Technique | Technique 下拉框会列出当前使用的着色器中所有的 Technique。一个着色器中可能会存在多个 Technique，每个 Technique 适用于不同的情况，例如效果差一点但是性能更好的 Technique 更适合用于手机平台。当切换了 Technique 后 Pass 列表也会同步更新。 |
+| USE INSTANCING | 是否启用动态 Instancing。需要注意的是，Instancing 只应该在场景中有大量相同模型的实例时启用，适当合理地应用 Instancing 可以有不错的性能提升，但过度使用反而很可能会因为额外的开销维护导致性能下降 |
+| USE BATCHING | 是否启用动态 VB 合并式合批。 |
+| Pass | Pass 列表会列出当前使用的 Technique 中所有的 Pass（例如 Pass 0、Pass 1、Pass 2......）。<br>每个 Pass 可能会有不同的属性和定义，开发者可以分别设置这些属性和定义。如果属性是被定义包裹住的，需要先勾上定义才能看到对应的属性。详情请参考 [Pass 可选配置参数](../shader/pass-parameter-list.md) |
 
-Effect 的创建方式跟 Material 的创建方式类似。
+在 **属性检查器** 面板右上方还可以选择其他的模型以预览效果：
 
-![effect-create](material/effect-create.png)
+![image](../material-system/img/preview-model-select.png)
 
-创建出来的 Effect 默认是一个 PBR 的 Effect。
+若修改了材质属性，面板右上角会出现 ![image](../material-system/img/save-material.png) 保存和 ![image](../material-system/img/revert-material.png) 重置按钮。重置会将材质属性回退到上一次保存时的设置，而一旦点击保存后便无法再重置。
 
-![effect-show](material/effect-show.png)
+## 使用材质
 
-以上就是一个材质的创建流程，更多信息可以参考：[Effect 书写格式与语法](../material-system/effect-syntax.md)
+一般情况下，3D 模型、2D 对象以及粒子系统都需要指定材质才可以正确渲染出物体表面的外观。
+
+### 在 3D 模型中使用
+
+通过 [网格/蒙皮网格/批量蒙皮网格渲染器组件](../module-map/mesh/) 上的 `Materials` 属性，我们可以指定当前 3D 模型所使用的材质。点击 `Materials` 属性框右侧的箭头图标按钮，可以看到当前项目中所有的材质资源，根据需要选择即可。或者也可以将所需的材质资源从 **资源管理器** 直接拖拽到 `Materials` 属性框中。
+
+#### 导出模型资源中的材质
+
+通常 [模型资源](./model/mesh.md) 都是由第三方工具制作并导出，然后导入到 Creator 中使用的（支持 FBX 和 glTF 格式）。若模型资源文件中自带了材质资源，则导入后材质为 **只读** 状态，不可编辑。
+
+![fbx-mat](../material-system/img/readonly-material.png)
+
+若要编辑模型资源自带的材质，我们需要先将其提取到模型资源外。<br>在 **资源管理器** 中选中模型资源，然后在 **属性检查器** 的 **材质** 分页中勾选 **提取材质**，并设置 **材质提取目录**，最后点击右上角的绿色打钩按钮，即可将模型资源的材质提取到指定目录。详情请参考 [模型资源 - Material 模块](./model/mesh.md#material-%E6%A8%A1%E5%9D%97)。
+
+![导出模型](../material-system/img/dump-material.png)
+
+材质提取完成后，会自动和模型节点的网格渲染器组件中的 `Materials` 属性绑定。例如：
+
+材质提取前：
+
+![材质提取前](../material-system/img/dump-result.png)
+
+材质提取后：
+
+![材质提取后](../material-system/img/post-dump.png)
+
+### 在 2D 以及 UI 渲染组件中使用
+
+2D 对象（包括 2D 渲染和 UI 系统）默认情况下只支持一个单独的自定义材质。若留空则会使用引擎内置的标准材质。
+
+若要进行自定义，在组件 **属性检查器上**，通过选择 `Custom Material` 的下拉框选择相应的材质。
+
+![ui-select-mat](../material-system/img/ui-select.png)
+
+### 在粒子系统中使用
+
+粒子系统渲染模块 Renderer 中的 **ParticleMaterial** 和 **TrailMaterial** 属性分别用于渲染粒子材质和粒子拖尾，将所需的材质资源从 **资源管理器** 直接拖拽到 **渲染器（Renderer）** 相应的属性框中即可。
+
+![img-particle](../material-system/img/particle-material.png)
+
+详情请参考 [粒子渲染模块](../particle-system/renderer.md)。

zh/asset/material/default-effect.png

@@ -62,7 +62,7 @@ Creator 提供了几个简单的静态 3D 模型，其中包含了立方体、
 关于蒙皮模型的支持及相关设定，参考 [骨骼动画组件](../../animation/skeletal-animation.md#关于动态-Instancing)。
 
 另外 instancing 还支持自定义额外的 instanced attributes，可以传递更多不同 instance 之间的差异性数据（比如不同人物间给一个漫反射颜色的外观差异，或大片草地中的风力影响）。<br>
-这需要自定义 effect 的支持，更详细的说明可以参考 [语法指南](../../material-system/effect-syntax.md#自定义-Instanced-属性)。
+这需要自定义 effect 的支持，更详细的说明可以参考 [语法指南](../../shader/effect-syntax.md#%E8%87%AA%E5%AE%9A%E4%B9%89%E5%87%A0%E4%BD%95%E4%BD%93%E5%AE%9E%E4%BE%8B%E5%8C%96%E5%B1%9E%E6%80%A7)
 
 ### 合并 VB 合批
 

zh/asset/material/default-material.png

@@ -918,8 +918,8 @@ export class GameManager extends Component {
     @property({type: Prefab})
     public cubePrfb: Prefab | null = null;
     // 赛道长度
-    @property
-    public roadLength = 50;
+    @property({type: CCInteger})
+    public roadLength: Number = 50;
     private _road: BlockType[] = [];
     // 主界面根节点
     @property({type: Node})
@@ -929,11 +929,11 @@ export class GameManager extends Component {
     public playerCtrl: PlayerController | null = null;
     // 关联步长文本组件
     @property({type: Label})
-    public stepsLabel: Label = null!;
+    public stepsLabel: Label | null = null!;
 
     start () {
         this.curState = GameState.GS_INIT;
-        this.playerCtrl.node.on('JumpEnd', this.onPlayerJumpEnd, this);
+        this.playerCtrl?.node.on('JumpEnd', this.onPlayerJumpEnd, this);
     }
 
     init() {
@@ -958,14 +958,20 @@ export class GameManager extends Component {
             case GameState.GS_INIT:
                 this.init();
                 break;
-            case GameState.GS_PLAYING:
-                this.startMenu.active = false;
-                this.stepsLabel.string = '0';   // 将步数重置为0
-            // 设置 active 为 true 时会直接开始监听鼠标事件，此时鼠标抬起事件还未派发
-            // 会出现的现象就是，游戏开始的瞬间人物已经开始移动
-            // 因此，这里需要做延迟处理
-                setTimeout(() => {
-                    this.playerCtrl.setInputActive(true);
+            case GameState.GS_PLAYING: 
+                if (this.startMenu) {
+                    this.startMenu.active = false;
+                }
+
+                if (this.stepsLabel) {
+                    this.stepsLabel.string = '0';   // 将步数重置为0
+                }
+                // 会出现的现象就是，游戏开始的瞬间人物已经开始移动
+                // 因此，这里需要做延迟处理
+                setTimeout(() => { 
+                    if (this.playerCtrl) {
+                        this.playerCtrl.setInputActive(true);
+                    }
                 }, 0.1);
                 break;
             case GameState.GS_END:
@@ -992,18 +998,40 @@ export class GameManager extends Component {
         }
 
         // 根据赛道类型生成赛道
+        let linkedBlocks = 0;
         for (let j = 0; j < this._road.length; j++) {
-            let block: Node = this.spawnBlockByType(this._road[j]);
-            // 判断是否生成了道路，因为 spawnBlockByType 有可能返回坑（值为 null）
-            if (block) {
-                this.node.addChild(block);
-                block.setPosition(j, -1.5, 0);
+            if(this._road[j]) {
+                ++linkedBlocks;
+            }
+            if(this._road[j] == 0) {
+                if(linkedBlocks > 0) {
+                    this.spawnBlockByCount(j - 1, linkedBlocks);
+                    linkedBlocks = 0;
+                }
+            }        
+            if(this._road.length == j + 1) {
+                if(linkedBlocks > 0) {
+                    this.spawnBlockByCount(j, linkedBlocks);
+                    linkedBlocks = 0;
+                }
             }
         }
     }
 
+    spawnBlockByCount(lastPos: number, count: number) {
+        let block: Node|null = this.spawnBlockByType(BlockType.BT_STONE);
+        if(block) {
+            this.node.addChild(block);
+            block?.setScale(count, 1, 1);
+            block?.setPosition(lastPos - (count - 1) * 0.5, -1.5, 0);
+        }
+    }
     spawnBlockByType(type: BlockType) {
-        let block = null;
+        if (!this.cubePrfb) {
+            return null;
+        }
+
+        let block: Node|null = null;
         switch(type) {
             case BlockType.BT_STONE:
                 block = instantiate(this.cubePrfb);

zh/asset/material/effect-create.png

@@ -0,0 +1,12 @@
+# 内置材质
+
+Creator 在 **资源管理器** 面板的 **internal -> default_materials** 目录下内置了几种常见的材质，其使用的 Effect 为 [内置着色器](../shader/effect-builtin.md) ，内置材质的属性都不允许修改。
+
+![内置材质](img/builtin-material.png)
+
+|内置材质|说明|
+|:--|:--|
+|default-materail| 非透明物体的 [标准材质](../shader/effect-builtin-pbr.md) |
+|default-materail-transparent|  半透明物体的 [标准材质](../shader/effect-builtin-pbr.md) |
+|particle-add| 标准粒子材质|
+|ui-sprite-material| 精灵的标准材质|