From 53127f8a0c39afc4a9ce10767d82a6856e5323cd Mon Sep 17 00:00:00 2001 From: AZhan Date: Sat, 16 Sep 2023 16:13:02 +0800 Subject: [PATCH] Update particle renderer, camera depth texture and clone doc (#803) * docs: update particle renderer doc * docs: add camera depth doc * docs: add depth texture playground * doc: update clone doc * docs: fix doc error * docs: fix doc * docs: fix doc * fix: doc image * fix: doc order --------- Co-authored-by: GuoLei1990 --- docs/camera.md | 9 ++ docs/camera.zh-CN.md | 35 +++-- docs/custom-material.md | 41 +++-- docs/custom-material.zh-CN.md | 46 +++--- docs/entity-clone.md | 23 +-- docs/entity-clone.zh-CN.md | 42 +++--- docs/particle-renderer.md | 255 +++++++++++++++++++++++--------- docs/particle-renderer.zh-CN.md | 249 +++++++++++++++++++++++-------- 8 files changed, 491 insertions(+), 209 deletions(-) diff --git a/docs/camera.md b/docs/camera.md index 09a048de7..4fb81133c 100644 --- a/docs/camera.md +++ b/docs/camera.md @@ -77,10 +77,12 @@ Therefore, when used in actual projects, the type of projection is generally det | | [priority](${api}core/Camera#priority) | The rendering priority is used to determine the order in which the content contained in the camera is rendered in the case of multiple cameras. | | | [renderTarget](${api}core/Camera#renderTarget) | The rendering target determines which target the content will be rendered to. | | | [viewport](${api}core/Camera#viewport) | The viewport, which determines the scope of the content that is finally rendered to the target device. | +| | [pixelViewport](${api}core/Camera#pixelViewport) | The viewport of the camera in pixel coordinates on the screen. In pixel screen coordinates, the upper-left corner is (0, 0), and the lower-right corner is (1.0, 1.0). | | | [nearClipPlane](${api}core/Camera#nearClipPlane) | Near clipping plane | | | [farClipPlane](${api}core/Camera#farClipPlane) | Far clipping plane | | Perspective projection | [fieldOfView](${api}core/Camera#fieldOfView) | Field of view | | Orthogonal projection | [orthographicSize](${api}core/Camera#orthographicSize) | Half the size of the camera in orthographic mode | +| | [depthTextureMode]((${api}core/Camera#depthTextureMode)) | Depth texture mode, defalut is `DepthTextureMode.None` | For details, please read [API documentation](${api}core/Camera)。 @@ -100,6 +102,13 @@ In the case of multiple cameras, we can combine the camera's `renderTarget`, `p Since in Galacean, the world coordinate system is a right-handed system, the positive direction of any node faces the -Z axis. Similarly, the positive direction of the camera (viewing direction) is also the -Z axis direction, and so on. In Unity and other world coordinates In a left-handed engine, the positive direction of the camera is the +Z axis. +### Depth texture + +The camera can enable the depth texture through the [depthTextureMode]((${api}core/Camera#depthTextureMode)) attribute. After the depth texture is enabled, the depth texture can be accessed in the Shader through the `camera_DepthTexture` attribute. Depth textures can be used to achieve soft particles and water edge transitions, as well as some simple post-processing effects. +Note: Depth textures only render non-transparent objects. + + + ## method | Properties | Explanation | diff --git a/docs/camera.zh-CN.md b/docs/camera.zh-CN.md index f2229e69e..1fe51924b 100644 --- a/docs/camera.zh-CN.md +++ b/docs/camera.zh-CN.md @@ -65,19 +65,21 @@ entity.engine.sceneManager.activeScene._activeCameras[0]; ## 属性 -| 类型 | 属性 | 解释 | -| :------- | :----------------------------------------------------- | :----------------------------------------------------------- | -| 通用 | [isOrthographic](${api}core/Camera#isOrthographic) | 是否正交投影，默认是 `false` | -| | [aspectRatio](${api}core/Camera#aspectRatio) | 画布宽高比，一般是根据 canvas 大小自动计算，也可以手动改变（不推荐） | -| | [cullingMask](${api}core/Camera#cullingMask) | 裁剪遮罩，用来选择性地渲染场景中的渲染组件。 | -| | [priority](${api}core/Camera#priority) | 渲染优先级，用来确定在多相机的情况下按照什么顺序去渲染相机包含的内容。 | -| | [renderTarget](${api}core/Camera#renderTarget) | 渲染目标，确定内容最后被渲染到哪个目标上。 | -| | [viewport](${api}core/Camera#viewport) | 视口，确定内容最后被渲染到目标设备里的范围。 | -| | [nearClipPlane](${api}core/Camera#nearClipPlane) | 近裁剪平面 | -| | [farClipPlane](${api}core/Camera#farClipPlane) | 远裁剪平面 | -| | [clearFlags](${api}core/Camera#clearFlags) | 在渲染这个相机前清理画布缓冲的标记 | -| 透视投影 | [fieldOfView](${api}core/Camera#fieldOfView) | 视角 | -| 正交投影 | [orthographicSize](${api}core/Camera#orthographicSize) | 正交模式下相机的一半尺寸 | +| 类型 | 属性 | 解释 | +| :------- | :------------------------------------------------------- | :----------------------------------------------------------- | +| 通用 | [isOrthographic](${api}core/Camera#isOrthographic) | 是否正交投影，默认是 `false` | +| | [aspectRatio](${api}core/Camera#aspectRatio) | 画布宽高比，一般是根据 canvas 大小自动计算，也可以手动改变（不推荐） | +| | [cullingMask](${api}core/Camera#cullingMask) | 裁剪遮罩，用来选择性地渲染场景中的渲染组件。 | +| | [priority](${api}core/Camera#priority) | 渲染优先级，用来确定在多相机的情况下按照什么顺序去渲染相机包含的内容。 | +| | [renderTarget](${api}core/Camera#renderTarget) | 渲染目标，确定内容最后被渲染到哪个目标上。 | +| | [viewport](${api}core/Camera#viewport) | 视口，确定内容最后被渲染到目标设备里的范围。 | +| | [pixelViewport](${api}core/Camera#pixelViewport) | 屏幕上相机的视口（以像素坐标表示）。 在像素屏幕坐标中，左上角为(0, 0)，右下角为(1.0, 1.0)。 | +| | [nearClipPlane](${api}core/Camera#nearClipPlane) | 近裁剪平面 | +| | [farClipPlane](${api}core/Camera#farClipPlane) | 远裁剪平面 | +| | [clearFlags](${api}core/Camera#clearFlags) | 在渲染这个相机前清理画布缓冲的标记 | +| 透视投影 | [fieldOfView](${api}core/Camera#fieldOfView) | 视角 | +| 正交投影 | [orthographicSize](${api}core/Camera#orthographicSize) | 正交模式下相机的一半尺寸 | +| | [depthTextureMode]((${api}core/Camera#depthTextureMode)) | 深度我哪里模式，模型不生成 | 详情请查看 [API 文档](${api}core/Camera)。 @@ -99,6 +101,13 @@ entity.engine.sceneManager.activeScene._activeCameras[0]; 为了方便区分，我们可以使用人脸朝向法判断，无论在左手系或者右手系，将右手放在 +X 轴上，将头部放在 +Y 轴上，此时面部朝向即正方向。 +### 深度纹理 + +相机可以通过 [depthTextureMode]((${api}core/Camera#depthTextureMode)) 属性开启深度纹理，开启深度纹理后可以通过 `camera_DepthTexture` 属性在 Shader 中访问深度纹理。深度纹理可以用于实现软粒子和水面边缘过渡，以及一些简单的后处理效果。 +注意：深度纹理仅渲染非透明物体。 + + + ## 方法 | 属性 | 解释 | diff --git a/docs/custom-material.md b/docs/custom-material.md index 0a9a37068..9b12ebc89 100644 --- a/docs/custom-material.md +++ b/docs/custom-material.md @@ -67,32 +67,41 @@ In the above, we gave the material a shader, this time the program can start ren ### Properties -| Name | Type | Meaning | -| :----------- | :--- | ------------------------------------ | -| camera_ViewMat | mat4 | viewport matrix | -| camera_ProjMat | mat4 | projection matrix | -| camera_VPMat | mat4 | viewport projection matrix | -| camera_ViewInvMat | mat4 | viewport inverse matrix | -| camera_Position | vec3 | camera position | -| renderer_LocalMat | mat4 | model local coordinate system matrix | -| renderer_ModelMat | mat4 | model world Coordinate System Matrix | -| renderer_MVMat | mat4 | model viewport matrix | -| renderer_MVPMat | mat4 | model viewport projection matrix | -| renderer_NormalMat | mat4 | normal inverse transpose matrix | +#### Renderer + +| Name | Type | Meaning | +| :----------------- | :--- | ------------------------------------ | +| renderer_LocalMat | mat4 | model local coordinate system matrix | +| renderer_ModelMat | mat4 | model world Coordinate System Matrix | +| renderer_MVMat | mat4 | model viewport matrix | +| renderer_MVPMat | mat4 | model viewport projection matrix | +| renderer_NormalMat | mat4 | normal matrix | + +#### Camera + +| Name | Type | Meaning | +| :----------------------- | :-------- | ------------------------------------------------------------ | +| camera_ViewMat | mat4 | viewport matrix | +| camera_ProjMat | mat4 | projection matrix | +| camera_VPMat | mat4 | viewport projection matrix | +| camera_ViewInvMat | mat4 | viewport inverse matrix | +| camera_Position | vec3 | camera position | +| camera_DepthTexture | sampler2D | camera depth information texture | +| camera_DepthBufferParams | Vec4 | camera depth buffer params: (x: 1.0 - far / near, y: far / near, z: 0, w: 0) | #### Time | Name | Type | Meaning | | :---------------- | :--- | :----------------------------------------------------------- | | scene_ElapsedTime | vec4 | Total time elapsed since engine started: (x: t, y: sin(t), z: cos(t), w: 0) | -| oasis_DeltaTime | vec4 | Interval time from previous frame: (x: dt, y: 0, z: 0, w: 0) | +| scene_DeltaTime | vec4 | Interval time from previous frame: (x: dt, y: 0, z: 0, w: 0) | #### Fog | Name | Type | Meaning | | :-------------- | :--- | :----------------------------------------------------------- | -| oasis_FogColor | vec4 | Fog color | -| oasis_FogParams | vec4 | Fog parameters: (x: -1/(end-start), y: end/(end-start), z: density / ln(2), w: density / sqr(ln(2)) | +| scene_FogColor | vec4 | Fog color | +| scene_FogParams | vec4 | Fog parameters: (x: -1/(end-start), y: end/(end-start), z: density / ln(2), w: density / sqr(ln(2)) | @@ -102,7 +111,7 @@ In the above, we gave the material a shader, this time the program can start ren In addition to the built-in variables, we can upload any variable with a custom name in the shader (it is recommended to use u\_\*\*, v\_\*\* to represent uniform and varying variables respectively), the only thing we have to do is using the correct interface according to the shader variable type. The upload interface is all in [ShaderData](${api}core/ShaderData), and the shaderData instance objects are saved in the four categories [Scene](${api}core/Scene), [Camera](${api}core/Camera), [Renderer](${api}core/Renderer), [Material](${api}core/Material) of the engine , we only need to call the interface in these shaderData, upload variables, and engine will automatically help us assemble these data at the bottom layer and optimize performance such as judging duplication. -![image-20210722153638785](https://gw.alipayobjects.com/zos/OasisHub/fc605510-5b14-476f-8c91-03205c623b4b/image-20210722153638785.png) +![original](https://mdn.alipayobjects.com/huamei_jvf0dp/afts/img/A*vC3NTp2qOuAAAAAAAAAAAAAADleLAQ/original) ### ShaderData separate benefits diff --git a/docs/custom-material.zh-CN.md b/docs/custom-material.zh-CN.md index b8aa70d6e..7559e59b5 100644 --- a/docs/custom-material.zh-CN.md +++ b/docs/custom-material.zh-CN.md @@ -66,35 +66,43 @@ const material = new Material(engine, Shader.find("demo")); ### 属性 -#### 变换 - - -| 名字 | 类型 | 解释 | -| :--- | :--- | ---- | -| camera_ViewMat | mat4 | 视口矩阵 | -| camera_ProjMat | mat4 | 投影矩阵 | -| camera_VPMat | mat4 | 视口投影矩阵 | -| camera_ViewInvMat | mat4 | 视口逆矩阵 | -| camera_Position | vec3 | 相机位置 | -| renderer_LocalMat | mat4 | 模型本地坐标系矩阵 | -| renderer_ModelMat | mat4 | 模型世界坐标系矩阵 | -| renderer_MVMat | mat4 | 模型视口矩阵 | -| renderer_MVPMat | mat4 | 模型视口投影矩阵 | -| renderer_NormalMat | mat4 | 法线逆转置矩阵 | +#### 渲染器 + + +| 名字 | 类型 | 解释 | +| :----------------- | :--- | ------------------ | +| renderer_LocalMat | mat4 | 模型本地坐标系矩阵 | +| renderer_ModelMat | mat4 | 模型世界坐标系矩阵 | +| renderer_MVMat | mat4 | 模型视口矩阵 | +| renderer_MVPMat | mat4 | 模型视口投影矩阵 | +| renderer_NormalMat | mat4 | 法线矩阵 | + +#### 相机 + + +| 名字 | 类型 | 解释 | +| :----------------------- | :-------- | ------------------------------------------------------------ | +| camera_ViewMat | mat4 | 视口矩阵 | +| camera_ProjMat | mat4 | 投影矩阵 | +| camera_VPMat | mat4 | 视口投影矩阵 | +| camera_ViewInvMat | mat4 | 视口逆矩阵 | +| camera_Position | vec3 | 相机位置 | +| camera_DepthTexture | sampler2D | 深度信息纹理 | +| camera_DepthBufferParams | Vec4 | 相机深度缓冲参数：(x: 1.0 - far / near, y: far / near, z: 0, w: 0) | #### 时间 | 名字 | 类型 | 解释 | | :---------------- | :--- | :-------------------------------------------------------- | | scene_ElapsedTime | vec4 | 引擎启动后经过的总时间：(x: t, y: sin(t), z:cos(t), w: 0) | -| oasis_DeltaTime | vec4 | 距离上一帧的间隔时间：(x: dt, y: 0, z:0, w: 0) | +| scene_DeltaTime | vec4 | 距离上一帧的间隔时间：(x: dt, y: 0, z:0, w: 0) | #### 雾 | 名字 | 类型 | 解释 | | :-------------- | :--- | :----------------------------------------------------------- | -| oasis_FogColor | vec4 | 雾的颜色 | -| oasis_FogParams | vec4 | 雾的参数：(x: -1/(end-start), y: end/(end-start), z: density / ln(2), w: density / sqr(ln(2)) | +| scene_FogColor | vec4 | 雾的颜色 | +| scene_FogParams | vec4 | 雾的参数：(x: -1/(end-start), y: end/(end-start), z: density / ln(2), w: density / sqr(ln(2)) | ## 上传 shader 变量 @@ -103,7 +111,7 @@ const material = new Material(engine, Shader.find("demo")); 除了内置的变量，我们可以在 shader 中上传任何自定义名字的变量(建议使用 u_** 、 v_** 分别表示 uniform、varying变量)，我们唯一要做的就是根据 shader 的变量类型，使用正确的接口。 上传接口全部保存在 [ShaderData](${api}core/ShaderData) 中，而 shaderData 实例对象又分别保存在引擎的四大类 [Scene](${api}core/Scene)、[Camera](${api}core/Camera)、[Renderer](${api}core/Renderer)、[Material](${api}core/Material) 中，我们只需要分别往这些 shaderData 中调用接口，上传变量，引擎便会在底层自动帮我们组装这些数据，并进行判重等性能的优化。 -![](https://gw.alipayobjects.com/mdn/rms_d27172/afts/img/A*yR97QbVx-QwAAAAAAAAAAAAAARQnAQ) +![](https://mdn.alipayobjects.com/huamei_jvf0dp/afts/img/A*ijQMQJM_Vy0AAAAAAAAAAAAADleLAQ/original) ### shaderData 分开的好处 shaderData 分别保存在引擎的四大类 [Scene](${api}core/Scene)、[Camera](${api}core/Camera)、[Renderer](${api}core/Renderer)、[Material](${api}core/Material) 中，这样做的好处之一就是底层可以根据上传时机上传某一块 uniform，提升性能；另外，将材质无关的 shaderData 剥离出来，可以实现共享材质，比如两个 renderer ，共享了一个材质，虽然都要操控同一个 shader，但是因为这一部分 shader 数据的上传来源于两个 renderer 的 shaderData，所以是不会影响彼此的渲染结果的。 diff --git a/docs/entity-clone.md b/docs/entity-clone.md index 047173485..de83738fc 100644 --- a/docs/entity-clone.md +++ b/docs/entity-clone.md @@ -29,19 +29,19 @@ class CustomScript extends Script{ c:Vector3 = new Vector3(0,0,0); } -// init entity and script. +// Init entity and script const entity = engine.createEntity(); const script = entity.addComponent(CustomScript); script.a = true; script.b = 2; script.c.set(1,1,1); -// clone logic. +// Clone logic const cloneEntity = entity.clone(); const cloneScript = cloneEntity.getComponent(CustomScript); -console.log(cloneScript.a);// output is true. -console.log(cloneScript.b);// output is 2. -console.log(cloneScript.c);// output is (1,1,1). +console.log(cloneScript.a); // output is true. +console.log(cloneScript.b); // output is 2. +console.log(cloneScript.c); // output is (1,1,1). ``` ### Clone decorator In addition to the default cloning method, the engine also provides a "cloning decorator" to customize the cloning method of script fields. The engine has four built-in clone decorations: @@ -74,7 +74,7 @@ class CustomScript extends Script{ d:Vector3[] = [new Vector3(0,0,0)]; } -//init entity and script. +// Init entity and script const entity = engine.createEntity(); const script = entity.addComponent(CustomScript); script.a = true; @@ -82,7 +82,7 @@ script.b = 2; script.c[0].set(1,1,1); script.d[0].set(1,1,1); -// clone logic. +// Clone logic const cloneEntity = entity.clone(); const cloneScript = cloneEntity.getComponent(CustomScript); console.log(cloneScript.a);// output is false,ignoreClone will ignore the value. @@ -96,8 +96,9 @@ cloneScript.d[0].set(2,2,2);// change the field d[0] value to (2,2,2). console.log(script.c[0]);// output is (2,2,2). bacause shallowClone let c[0] use the same reference with cloneScript's c[0]. console.log(script.d[0]);// output is (1,1,1). bacause deepClone let d[0] use the different reference with cloneScript's d[0]. ``` -Note: +- Notice: -- `shallowClone` and `deepClone` are applicable to *Object*, *Array* and *Class* types. -- `shallowClone` will keep its own references independent after cloning, and clone all its internal fields by means of assignment (if the internal field is a basic type, the value will be copied, if the internal field is a reference type, its reference address will be copied). -- `deepClone` If *Class* is encountered in the deep cloning process, it will call the object's [cloneTo()](${api}design/IClone#cloneTo) to implement cloning, and the object needs to implement [IClone](${api}design /IClone) interface. + - `shallowClone` and `deepClone` are usually used for *Object*, *Array* and *Class* types. + - `shallowClone` will keep its own reference independent after cloning, and use assignment to clone all its internal fields (if the internal field is a basic type, the value will be copied, if the internal field is a reference type, its reference address will be copied). + - `deepClone` is a deep clone, which will perform deep recursion on the properties. How to clone the sub-properties of the properties depends on the decorator of the sub-properties. + - If the clone decorator cannot meet the requirements, you can add a custom clone by implementing the [_cloneTo()](${api}design/IClone#cloneTo) method. diff --git a/docs/entity-clone.zh-CN.md b/docs/entity-clone.zh-CN.md index 6a0760b6f..aec4f3b04 100644 --- a/docs/entity-clone.zh-CN.md +++ b/docs/entity-clone.zh-CN.md @@ -29,19 +29,19 @@ class CustomScript extends Script{ c:Vector3 = new Vector3(0,0,0); } -//init entity and script. +// Init entity and script const entity = engine.createEntity(); const script = entity.addComponent(CustomScript); script.a = true; script.b = 2; script.c.set(1,1,1); -// clone logic. +// Clone logic const cloneEntity = entity.clone(); const cloneScript = cloneEntity.getComponent(CustomScript); -console.log(cloneScript.a);// output is true. -console.log(cloneScript.b);// output is 2. -console.log(cloneScript.c);// output is (1,1,1). +console.log(cloneScript.a); // output is true. +console.log(cloneScript.b); // output is 2. +console.log(cloneScript.c); // output is (1,1,1). ``` ### 克隆装饰器 除了默认的克隆方式外，引擎还提供了“克隆装饰器“对脚本字段的克隆方式进行定制。引擎内置四种克隆装饰： @@ -53,7 +53,7 @@ console.log(cloneScript.c);// output is (1,1,1). | [shallowClone](${api}core/shallowClone) | 克隆时对字段进行浅克隆。克隆后会保持自身引用独立，并使用赋值的方式克隆其内部所有字段（如果内部字段是基本类型则会拷贝值，如果内部字段是引用类型则会拷贝其引用地址）。| | [deepClone](${api}core/deepClone) | 克隆时对字段进行深克隆。克隆后会保持自身引用独立，并且其内部所有深层字段均保持完全独立。| - 我们将上面的案例稍加修改,分别对 `CustomScript` 中的四个字段添加了不同的“克隆装饰器“,由于 `shallowClone` 和 `deepCone`  较复杂，我们对字段 `c` 和 `d` 增加了额外的打印输出进行进一步讲解。 +我们将上面的案例稍加修改,分别对 `CustomScript` 中的四个字段添加了不同的“克隆装饰器“。由于 `shallowClone` 和 `deepCone`  较复杂，我们对字段 `c` 和 `d` 增加了额外的打印输出进行进一步讲解。 ```typescript // define a custom script class CustomScript extends Script{ @@ -74,7 +74,7 @@ class CustomScript extends Script{ d:Vector3[] = [new Vector3(0,0,0)]; } -//init entity and script. +// Init entity and script const entity = engine.createEntity(); const script = entity.addComponent(CustomScript); script.a = true; @@ -82,22 +82,24 @@ script.b = 2; script.c[0].set(1,1,1); script.d[0].set(1,1,1); -// clone logic. +// Clone logic const cloneEntity = entity.clone(); const cloneScript = cloneEntity.getComponent(CustomScript); -console.log(cloneScript.a);// output is false,ignoreClone will ignore the value. -console.log(cloneScript.b);// output is 2,assignmentClone is just assignment the origin value. -console.log(cloneScript.c[0]);// output is Vector3(1,1,1),shallowClone clone the array shell,but use the same element. -console.log(cloneScript.d[0]);// output is Vector3(1,1,1),deepClone clone the array shell and also clone the element. +console.log(cloneScript.a); // output is false,ignoreClone will ignore the value. +console.log(cloneScript.b); // output is 2,assignmentClone is just assignment the origin value. +console.log(cloneScript.c[0]); // output is Vector3(1,1,1),shallowClone clone the array shell,but use the same element. +console.log(cloneScript.d[0]); // output is Vector3(1,1,1),deepClone clone the array shell and also clone the element. -cloneScript.c[0].set(2,2,2);// change the field c[0] value to (2,2,2). -cloneScript.d[0].set(2,2,2);// change the field d[0] value to (2,2,2). +cloneScript.c[0].set(2,2,2); // change the field c[0] value to (2,2,2). +cloneScript.d[0].set(2,2,2); // change the field d[0] value to (2,2,2). -console.log(script.c[0]);// output is (2,2,2). bacause shallowClone let c[0] use the same reference with cloneScript's c[0]. -console.log(script.d[0]);// output is (1,1,1). bacause deepClone let d[0] use the different reference with cloneScript's d[0]. +console.log(script.c[0]); // output is (2,2,2). bacause shallowClone let c[0] use the same reference with cloneScript's c[0]. +console.log(script.d[0]); // output is (1,1,1). bacause deepClone let d[0] use the different reference with cloneScript's d[0]. ``` -注意: +- 注意: + + - `shallowClone` 和 `deepClone` 通常用于 *Object*、*Array* 和 *Class* 类型。 + - `shallowClone` 克隆后会保持自身引用独立，并使用赋值的方式克隆其内部所有字段（如果内部字段是基本类型则会拷贝值，如果内部字段是引用类型则会拷贝其引用地址）。 + - `deepClone` 为深克隆，会对属性进行深度递归，至于属性的子属性如何克隆，取决于子属性的装饰器。 + - 如果克隆装饰器不能满足诉求，可以通过实现 [_cloneTo()](${api}design/IClone#cloneTo) 方法追加自定义克隆。 -- `shallowClone` 和 `deepClone` 适用于 *Object*、*Array* 和 *Class* 类型。 -- `shallowClone` 克隆后会保持自身引用独立，并使用赋值的方式克隆其内部所有字段（如果内部字段是基本类型则会拷贝值，如果内部字段是引用类型则会拷贝其引用地址）。 -- `deepClone` 如果在深克隆过程中遇到 *Class* 则会调用对象的 [cloneTo()](${api}design/IClone#cloneTo) 实现克隆，需要对象实现 [IClone](${api}design/IClone) 接口。 diff --git a/docs/particle-renderer.md b/docs/particle-renderer.md index 83ac8fc0f..fbe9ea7bc 100644 --- a/docs/particle-renderer.md +++ b/docs/particle-renderer.md @@ -1,83 +1,204 @@ --- order: 5 -title: Particle +title: Particle Renderer type: Animation label: Animation + --- -Galacean Engine's particle renderer [ParticleRenderer](${api}core/ParticleRenderer) is a commonly used rendering component with rich properties. By adjusting each property value, it can achieve brilliant and colorful particle effects. +Galacean Engine's particle renderer [ParticleRenderer](${api}core/ParticleRenderer) is a commonly used rendering component with rich properties. Colorful particle effects can be achieved by adjusting each property value. + + - + -## Code example +## Code Example ```typescript -let particles: ParticleRenderer = particleEntity.addComponent(ParticleRenderer); - -particles.maxCount = 100; -particles.velocity = new Vector3(1, 1, 1); -particles.acceleration = new Vector3(-1, -1, -1); -particles.accelerationRandomness = new Vector3(-3, -3, -3); -particles.velocityRandomness = new Vector3(-1, -1, -1); -particles.rotateVelocity = 1; -particles.rotateVelocityRandomness = 1; -particles.size = 1; -particles.is2d = true; +let particleRenderer = particleEntity.addComponent(ParticleRenderer); + +//Set Material +const material = new ParticleMaterial(particleEntity.engine); +material.blendMode = BlendMode.Additive; +material.baseTexture = texture; +particleRenderer.setMaterial(material); + +//Config main params +const generator = particleRenderer.generator; +const main = generator.main; +....... + +// Config emission params +const generator = particleRenderer.generator; +const emission = generator.emission; +....... + +// Config sizeOverLifetime params +const generator = particleRenderer.generator; +const sizeOverLifetime = generator.sizeOverLifetime; +....... + +// Config colorOverLifetime params +const generator = particleRenderer.generator; +const colorOverLifetime = generator.colorOverLifetime; +....... + +// Config velocityOverLifetime params +const generator = particleRenderer.generator; +const velocityOverLifetime = generator.velocityOverLifetime; +....... + +// Config rotationOverLifetime params +const generator = particleRenderer.generator; +const rotationOverLifetime = generator.rotationOverLifetime; +....... // Start play -particles.start(); +particleComp.play(); // Stop -particles.stop(); +particleComp.stop(); ``` -## Properties - -The particle renderer contains properties such as life cycle, material, transformation and so on. - -### Basic properties -- [maxCount](${api}core/ParticleRenderer#maxCount): The maximum number of particles determines the size of the memory occupied, which needs to be allocated reasonably. - -### Life cycle -- [lifetime](${api}core/ParticleRenderer#lifetime): The life cycle of the particle, in seconds. -- [startTimeRandomness](${api}core/ParticleRenderer#startTimeRandomness): Start time random factor. -- [isOnce](${api}core/ParticleRenderer#isOnce): Whether to emit only once, the default is `false` (loop). -- [playOnEnable](${api}core/ParticleRenderer#playOnEnable): Whether to play automatically, the default is `true`. - -### Material -- [texture](${api}core/ParticleRenderer#texture): Texture of every particle. -- [color](${api}core/ParticleRenderer#color):Color of Particle. -- [colorRandomness](${api}core/ParticleRenderer#colorRandomness): The color random factor, the value is between `0~1`, the color value of the R, G, and B channels of the color will take a random value within the range of the random factor. -- [isUseOriginColor](${api}core/ParticleRenderer#isUseOriginColor): Whether to use the original color of the image. When it is `true` (default), the original color of the image is used. Otherwise, the original color of the image is mixed with the color configured by the user. -- [spriteSheet](${api}core/ParticleRenderer#spriteSheet):Sprite atlas, each particle renders certain area in the sprite atlas: - - - -- [alpha](${api}core/ParticleRenderer#alpha): transparency value. -- [alphaRandomness](${api}core/ParticleRenderer#alphaRandomness): Transparency random factor. -- [isFadeIn](${api}core/ParticleRenderer#isFadeIn): Is fade-in. -- [isFadeOut](${api}core/ParticleRenderer#isFadeOut): Is fade-out. -- [blendMode](${api}core/ParticleRenderer#blendMode): Blend mode, currently supports [Transparent](${api}core/ParticleRendererBlendMode#Transparent)(default) and [Additive](${api}core/ParticleRendererBlendMode#Additive). - -### Transform -- [position](${api}core/ParticleRenderer#position): Initial position. -- [positionRandomness](${api}core/ParticleRenderer#positionRandomness): Position random factor. -- [velocity](${api}core/ParticleRenderer#velocity): Moving velocity. -- [velocityRandomness](${api}core/ParticleRenderer#velocityRandomness): Moving velocity random factor. -- [acceleration`](${api}core/ParticleRenderer#acceleration): Moving acceleration. -- [accelerationRandomness](${api}core/ParticleRenderer#accelerationRandomness): Moving acceleration factor. -- [angle](${api}core/ParticleRenderer#angle): Initial rotation angle. -- [angleRandomness](${api}core/ParticleRenderer#angleRandomness): The initial rotation angle random factor. The value is between `0~1`, for example: if the random factor is 1, the generated angle is random between `-PI~PI`. -- [rotateVelocity](${api}core/ParticleRenderer#rotateVelocity): Rotation velocity. -- [rotateVelocityRandomness](${api}core/ParticleRenderer#rotateVelocityRandomness): Rotation velocity factor. -- [isRotateToVelocity](${api}core/ParticleRenderer#isRotateToVelocity): Whether to follow the direction of the particle moving. The default is `false`. When it is `true`, the unit vector of the particle map texture rotated to the direction of the particle moving, such as fireworks. When it is `false`, there is no rotation, which is suitable for the same direction scenes, such as Kong Ming Lantern. -- [is2d](${api}core/ParticleRenderer#is2d): Whether it is a 2D particle, the default is `true`. -- [size](${api}core/ParticleRenderer#size): Particle size. -- [sizeRandomness](${api}core/ParticleRenderer#sizeRandomness): Particle size random factor. -- [scale](${api}core/ParticleRenderer#scale): The size of particle. -. -- [isScaleByLifetime](${api}core/ParticleRenderer#isScaleByLifetime): Whether to shrink to disappear with the life cycle. When it is `true`, the particles will become smaller and smaller. - - ## Methods -- [start()](${api}core/ParticleRenderer#start): Start playing. -- [stop()](${api}core/ParticleRenderer#stop): Stop playing. \ No newline at end of file +## Particle generator + +The [generator](<](${api}core/ParticleGenerator)>) property of ParticleRenderer is mainly responsible for the generation and playback functions of particles. The functions related to generating particles are composed of multiple modules, namely the main module, the emitter module, and the life cycle size. Module, life cycle color module, life cycle speed module, life cycle rotation module, texture table animation module. + +### Main module + +[`MainModule`](${api}core/MainModule) is the main module of `ParticleGeneratorModule`, which contains the most basic particle generation parameters. + +#### Properties + +- [`duration`](${api}core/MainModule#duration): The duration of the particle generator (unit: seconds). + +- [`isLoop`](${api}core/MainModule#isLoop): Specifies whether the particle generator loops. + +- [`startDelay`](#${api}core/MainModule#startDelay): The start delay of particle emission (unit: seconds). + +- [`startLifetime`](#${api}core/MainModule#startLifetime): The initial life cycle when particles are emitted. + +- [`startSpeed`](#${api}core/MainModule#startSpeed): The initial speed when the particle generator first generates particles. + +- [`startSize3D`](#${api}core/MainModule#startSize3D): Whether to specify the particle size of each axis separately. + +- [`startSize`](#${api}core/MainModule#startSize): The initial size of the particle generator when it first generates particles. + +- [`startSizeX`](#${api}core/MainModule#startSizeX): The initial size along the x-axis when the particle generator first generates particles. + +- [`startSizeY`](#${api}core/MainModule#startSizeY): The initial size along the y-axis when the particle generator first generates particles. + +- [`startSizeZ`](#${api}core/MainModule#startSizeZ): The initial size along the z-axis when the particle generator first generates particles. + +- [`startRotation3D`](#${api}core/MainModule#startRotation3D): Whether to enable 3D particle rotation. + +- [`startRotation`](#${api}core/MainModule#startRotation): The initial rotation when the particle generator first generates particles. + +- [`startRotationX`](#${api}core/MainModule#startRotationX): The initial rotation along the x-axis when the particle is emitted. + +- [`startRotationY`](#${api}core/MainModule#startRotationY): The initial rotation along the y-axis when the particle is emitted. + +- [`startRotationZ`](#${api}core/MainModule#startRotationZ): The initial rotation along the z-axis when the particle is emitted. + +- [`flipRotation`](#${api}core/MainModule#flipRotation): Make some particles rotate in the opposite direction. + +- [`startColor`](#${api}core/MainModule#startColor): The initial color mode of particles. + +- [`gravityModifier`](#${api}core/MainModule#gravityModifier): This particle generator applies the scale of gravity defined by Physics.gravity. + +- [`simulationSpace`](#${api}core/MainModule#simulationSpace): Select the space to simulate particles, which can be world space or local space. + +- [`simulationSpeed`](#${api}core/MainModule#simulationSpeed): Overrides the default playback speed of the particle generator. + +- [`scalingMode`](#${api}core/MainModule#scalingMode): Controls how the particle generator applies its Transform component to the particles it emits. + +- [`playOnEnabled`](#${api}core/MainModule#playOnEnabled): If set to true, the particle generator will automatically start playing on startup. + +- [`maxParticles`](#${api}core/MainModule#maxParticles): Maximum number of particles. + +### Launch module module + +[`EmissionModule`](${api}core/EmissionModule) is the emission module of `ParticleGeneratorModule`. This module is used to process the emission behavior of particle systems, including particle emission rate, emission shape, and burst behavior. + +#### Properties + +- [rateOverTime](${api}core/EmissionModule#rateOverTime): This is a `ParticleCompositeCurve` object representing the emission rate of particles. The default value is `10`. +- [rateOverDistance](${api}core/EmissionModule#rateOverDistance): This is a `ParticleCompositeCurve` object that represents the distance emission rate of particles. The default value is `0`. +- [shape](${api}core/EmissionModule#shape): This is a `BaseShape` object that represents the shape of the emitter. + +#### method + +- [addBurst(burst: Burst)](${api}core/EmissionModule#addBurst): Add a burst behavior. + +- [removeBurst(burst: Burst)](${api}core/EmissionModule#removeBurst): Remove a burst behavior. + +- [removeBurstByIndex(index: number)](${api}core/EmissionModule#removeBurstByIndex): Remove a bursting behavior by index. + +- [clearBurst()](${api}core/EmissionModule#clearBurst): Clear all blasting behaviors. + +### Life cycle size module + +[`SizeOverLifetimeModule`](${api}core/SizeOverLifetimeModule) is a subclass of `ParticleGeneratorModule`, used to handle size changes during the life cycle of the particle system. + +#### Properties + +- [separateAxes](#${api}core/SizeOverLifetimeModule#separateAxes): Boolean value, specifying whether the size of each axis changes independently. +- [sizeX](#${api}core/SizeOverLifetimeModule#sizeX): `ParticleCompositeCurve` object, representing the size change curve of particles in the x-axis direction. +- [sizeY](#${api}core/SizeOverLifetimeModule#sizeY): `ParticleCompositeCurve` object, representing the size change curve of particles in the y-axis direction. +- [sizeZ](#${api}core/SizeOverLifetimeModule#sizeZ): `ParticleCompositeCurve` object, representing the size change curve of particles in the z-axis direction. +- [size](#${api}core/SizeOverLifetimeModule#size): `ParticleCompositeCurve` object, gets or sets the particle size change curve. + +### Life cycle color module + +[`ColorOverLifetimeModule`](${api}core/ColorOverLifetimeModule) inherited from `ParticleGeneratorModule`, used to handle color changes during the life cycle of the particle system. + +#### Properties + +- [color](#${api}core/ColorOverLifetimeModule#color): `ParticleCompositeGradient` object, representing the color gradient of particles during their life cycle. + +### Life cycle rotation module + +[`RotationOverLifetimeModule`](${api}core/RotationOverLifetimeModule) Inherits from `ParticleGeneratorModule` and is used to control rotation changes during the life cycle of the particle system. + +#### Properties + +- [separateAxes](#${api}core/RotationOverLifetimeModule#separateAxes): `boolean` type, indicating whether to rotate on each axis separately. If disabled, only the z-axis will be used. + +- [rotationX](#${api}core/RotationOverLifetimeModule#rotationX): `ParticleCompositeCurve` object, representing the x-axis rotation of the particle during its lifetime. + +- [rotationY](#${api}core/RotationOverLifetimeModule#rotationY): `ParticleCompositeCurve` object, representing the y-axis rotation of the particle during its life cycle. + +- [rotationZ](#${api}core/RotationOverLifetimeModule#rotationZ): `ParticleCompositeCurve` object, representing the z-axis rotation of the particle during its lifetime. + +### Texture table animation module + +[`TextureSheetAnimationModule`](${api}core/TextureSheetAnimationModule) Inherits from `ParticleGeneratorModule` and is used to control the texture sheet animation of the particle system. + +#### Properties + +- [startFrame](${api}core/TextureSheetAnimationModule#startFrame): `ParticleCompositeCurve` object, representing the starting frame of the texture table. + +- [frameOverTime](${api}core/TextureSheetAnimationModule#frameOverTime): `ParticleCompositeCurve` object, representing the curve of the frame of the texture table changing over time. + +- [type](${api}core/TextureSheetAnimationModule#type): `TextureSheetAnimationType` enumeration, indicating the type of texture sheet animation. + +- [cycleCount](${api}core/TextureSheetAnimationModule#cycleCount): `number` type, indicating the cycle count of texture sheet animation. + +- [tiling](${api}core/TextureSheetAnimationModule#tiling): `Vector2` object, representing the tiling of the texture table. Can be accessed and modified through the `get` and `set` methods. + +## Other parameters + +- [velocityScale](${api}core/ParticleRenderer#velocityScale): Specifies the extent to which particles stretch based on their speed, type. +- [lengthScale](${api}core/ParticleRenderer#lengthScale): Defines the extent to which the particle stretches in the direction of its motion, defined as the ratio of the particle's length to its width. +- [pivot](${api}core/ParticleRenderer#pivot): The pivot of the particle. +- [renderMode](${api}core/ParticleRenderer#renderMode): The rendering mode of particles. +- [mesh](${api}core/ParticleRenderer#mesh): The mesh of particles, valid when `renderMode` is `Mesh`. + +## Rendering material + +[ParticleMaterial](${api}core/ParticleMaterial) is the default material of particles and contains some basic common material properties of particles. + +### Properties + +- [baseColor](${api}core/ParticleMaterial#baseColor): Base color. +- [baseTexture](${api}core/ParticleMaterial#baseColor): Base texture. diff --git a/docs/particle-renderer.zh-CN.md b/docs/particle-renderer.zh-CN.md index 808db38e3..507103998 100644 --- a/docs/particle-renderer.zh-CN.md +++ b/docs/particle-renderer.zh-CN.md @@ -1,81 +1,204 @@ --- order: 5 -title: 粒子动画 +title: 粒子渲染器 type: 动画 label: Animation + --- Galacean Engine 的粒子渲染器 [ParticleRenderer](${api}core/ParticleRenderer) 是常用的渲染组件，具备丰富的属性，通过调节各个属性值达到绚丽多彩的粒子效果。 - + + + + ## 代码示例 ```typescript -let particles: ParticleRenderer = particleEntity.addComponent(ParticleRenderer); - -particles.maxCount = 100; -particles.velocity = new Vector3(1, 1, 1); -particles.acceleration = new Vector3(-1, -1, -1); -particles.accelerationRandomness = new Vector3(-3, -3, -3); -particles.velocityRandomness = new Vector3(-1, -1, -1); -particles.rotateVelocity = 1; -particles.rotateVelocityRandomness = 1; -particles.size = 1; -particles.is2d = true; +let particleRenderer = particleEntity.addComponent(ParticleRenderer); + +// Set Material +const material = new ParticleMaterial(particleEntity.engine); +material.blendMode = BlendMode.Additive; +material.baseTexture = texture; +particleRenderer.setMaterial(material); + +// Config main params +const generator = particleRenderer.generator; +const main = generator.main; +....... + +// Config emission params +const generator = particleRenderer.generator; +const emission = generator.emission; +....... + +// Config sizeOverLifetime params +const generator = particleRenderer.generator; +const sizeOverLifetime = generator.sizeOverLifetime; +....... + +// Config colorOverLifetime params +const generator = particleRenderer.generator; +const colorOverLifetime = generator.colorOverLifetime; +....... + +// Config velocityOverLifetime params +const generator = particleRenderer.generator; +const velocityOverLifetime = generator.velocityOverLifetime; +....... + +// Config rotationOverLifetime params +const generator = particleRenderer.generator; +const rotationOverLifetime = generator.rotationOverLifetime; +....... // Start play -particleComp.start(); +particleComp.play(); // Stop particleComp.stop(); ``` -## 属性 - -粒子渲染器包含生命周期、材质、变换等属性。 - -### 基础属性 -- [maxCount](${api}core/ParticleRenderer#maxCount)：最大粒子数，决定所占内存的大小，需要合理分配。 - -### 生命周期 -- [lifetime](${api}core/ParticleRenderer#lifetime)：粒子的生命周期，单位秒。 -- [startTimeRandomness](${api}core/ParticleRenderer#startTimeRandomness)：开始时间随机因子。 -- [isOnce](${api}core/ParticleRenderer#isOnce) ：是否只发射一次，默认 `false` （循环发射）。 -- [playOnEnable](${api}core/ParticleRenderer#playOnEnable) ：是否自动播放，默认`true`。 - -### 材质 -- [texture](${api}core/ParticleRenderer#texture) ： 粒子形状贴图。 -- [color](${api}core/ParticleRenderer#color)：粒子颜色。 -- [colorRandomness](${api}core/ParticleRenderer#colorRandomness)：颜色随机因子，取值在 `0~1` 之间，颜色的 R、G、B通道的色值会分别在随机因子范围内取一个随机值。 -- [isUseOriginColor](${api}core/ParticleRenderer#isUseOriginColor) ：是否使用图片原色，为 `true` (默认) 时使用图片原色，为 `false`  时，图片原色混合用户配置的颜色。 -- [spriteSheet](${api}core/ParticleRenderer#spriteSheet)：精灵图表，每个粒子可以渲染精灵图中某块区域： - - - -- [alpha](${api}core/ParticleRenderer#alpha)：透明度。 -- [alphaRandomness](${api}core/ParticleRenderer#alphaRandomness)：透明度随机因子。 -- [isFadeIn](${api}core/ParticleRenderer#isFadeIn) ：是否添加淡入效果。 -- [isFadeOut](${api}core/ParticleRenderer#isFadeOut) ：是否添加淡出效果。 -- [blendMode](${api}core/ParticleRenderer#blendMode)：混合模式，目前支持 [Transparent](${api}core/ParticleRendererBlendMode#Transparent) 和 [Additive](${api}core/ParticleRendererBlendMode#Additive) 模式，默认`Transparent`。 - -### 变换 -- [position](${api}core/ParticleRenderer#position) ：初始位置。 -- [positionRandomness](${api}core/ParticleRenderer#positionRandomness)：位置随机因子。 -- [velocity](${api}core/ParticleRenderer#velocity) ：移动速度。 -- [velocityRandomness](${api}core/ParticleRenderer#velocityRandomness)：移动速度随机因子。 -- [acceleration`](${api}core/ParticleRenderer#acceleration)：加速度。 -- [accelerationRandomness](${api}core/ParticleRenderer#accelerationRandomness)：加速度随机因子。 -- [angle](${api}core/ParticleRenderer#angle): 初始旋转角度。 -- [angleRandomness](${api}core/ParticleRenderer#angleRandomness): 初始旋转角度随机因子，取值在 `0~1` 之间，例如：若随机因子为 1，则生成的角度在 `-PI~PI` 之间随机。 -- [rotateVelocity](${api}core/ParticleRenderer#rotateVelocity): 旋转速度。 -- [rotateVelocityRandomness](${api}core/ParticleRenderer#rotateVelocityRandomness): 旋转速度随机因子。 -- [isRotateToVelocity](${api}core/ParticleRenderer#isRotateToVelocity)：是否跟随粒子运动速度的方向，默认 `false`，为 `true`  时，将粒子贴图的单位向量旋转至粒子运动速度的方向，例如烟花。为 `false` 时，无旋转，适用于方向一致的场景，例如孔明灯。 -- [is2d](${api}core/ParticleRenderer#is2d)：是否是 2D 粒子，默认 `true`。 -- [size](${api}core/ParticleRenderer#size)：粒子大小。 -- [sizeRandomness](${api}core/ParticleRenderer#sizeRandomness)：粒子大小随机因子。 -- [scale](${api}core/ParticleRenderer#scale)：粒子缩放。 -- [isScaleByLifetime](${api}core/ParticleRenderer#isScaleByLifetime)：是否随生命周期缩小至消失。为 `true` 时粒子会越来越小。 - - ## 方法 -- [start()](${api}core/ParticleRenderer#start)：开始播放。 -- [stop()](${api}core/ParticleRenderer#stop)：停止播放。 \ No newline at end of file +## 粒子生成器 + +ParticleRenderer 的 [generator](<](${api}core/ParticleGenerator)>) 属性主要负责粒子的生成和播放功能，生成粒子相关的功能由多个模块组成，分别是主模块、发射器模块、生命周期尺寸模块、生命周期颜色模块、生命周期速度模块、生命周期旋转模块、纹理表格动画模块。 + +### 主模块 + +[`MainModule`](${api}core/MainModule) 是 `ParticleGeneratorModule` 的主模块，包含了最基本的粒子生成参数。 + +#### 属性 + +- [`duration`](${api}core/MainModule#duration): 粒子生成器的持续时间（单位：秒）。 + +- [`isLoop`](${api}core/MainModule#isLoop): 指定粒子生成器是否循环。 + +- [`startDelay`](#${api}core/MainModule#startDelay): 粒子发射的开始延迟（单位：秒）。 + +- [`startLifetime`](#${api}core/MainModule#startLifetime): 粒子发射时的初始生命周期。 + +- [`startSpeed`](#${api}core/MainModule#startSpeed): 粒子生成器首次生成粒子时的初始速度。 + +- [`startSize3D`](#${api}core/MainModule#startSize3D): 是否以每个轴的粒子大小分别指定。 + +- [`startSize`](#${api}core/MainModule#startSize): 粒子生成器首次生成粒子时的初始大小。 + +- [`startSizeX`](#${api}core/MainModule#startSizeX): 粒子生成器首次生成粒子时沿 x 轴的初始大小。 + +- [`startSizeY`](#${api}core/MainModule#startSizeY): 粒子生成器首次生成粒子时沿 y 轴的初始大小。 + +- [`startSizeZ`](#${api}core/MainModule#startSizeZ): 粒子生成器首次生成粒子时沿 z 轴的初始大小。 + +- [`startRotation3D`](#${api}core/MainModule#startRotation3D): 是否启用 3D 粒子旋转。 + +- [`startRotation`](#${api}core/MainModule#startRotation): 粒子生成器首次生成粒子时的初始旋转。 + +- [`startRotationX`](#${api}core/MainModule#startRotationX): 粒子发射时沿 x 轴的初始旋转。 + +- [`startRotationY`](#${api}core/MainModule#startRotationY): 粒子发射时沿 y 轴的初始旋转。 + +- [`startRotationZ`](#${api}core/MainModule#startRotationZ): 粒子发射时沿 z 轴的初始旋转。 + +- [`flipRotation`](#${api}core/MainModule#flipRotation): 使部分粒子以相反方向旋转。 + +- [`startColor`](#${api}core/MainModule#startColor): 粒子的初始颜色模式。 + +- [`gravityModifier`](#${api}core/MainModule#gravityModifier): 此粒子生成器应用于由 Physics.gravity 定义的重力的比例。 + +- [`simulationSpace`](#${api}core/MainModule#simulationSpace): 选择模拟粒子的空间，它可以是世界空间或本地空间。 + +- [`simulationSpeed`](#${api}core/MainModule#simulationSpeed): 覆盖粒子生成器的默认播放速度。 + +- [`scalingMode`](#${api}core/MainModule#scalingMode): 控制粒子生成器如何将其 Transform 组件应用到它发射的粒子。 + +- [`playOnEnabled`](#${api}core/MainModule#playOnEnabled): 如果设置为 true，粒子生成器将在启动时自动开始播放。 + +- [`maxParticles`](#${api}core/MainModule#maxParticles): 最大粒子数。 + +### 发射模块模块 + +[`EmissionModule`](${api}core/EmissionModule) 是 `ParticleGeneratorModule` 的发射模块。该模块用于处理粒子系统的发射行为，包括粒子发射速率、发射形状以及爆破（burst）行为等。 + +#### 属性 + +- [rateOverTime](${api}core/EmissionModule#rateOverTime): 这是一个 `ParticleCompositeCurve` 对象，表示粒子的发射速率。默认值为 `10`。 +- [rateOverDistance](${api}core/EmissionModule#rateOverDistance): 这是一个 `ParticleCompositeCurve` 对象，表示粒子的距离发射速率。默认值为 `0`。 +- [shape](${api}core/EmissionModule#shape): 这是一个 `BaseShape` 对象，表示发射器的形状。 + +#### 方法 + +- [addBurst(burst: Burst)](${api}core/EmissionModule#addBurst): 添加一个爆破行为。 + +- [removeBurst(burst: Burst)](${api}core/EmissionModule#removeBurst): 移除一个爆破行为。 + +- [removeBurstByIndex(index: number)](${api}core/EmissionModule#removeBurstByIndex): 通过索引移除一个爆破行为。 + +- [clearBurst()](${api}core/EmissionModule#clearBurst): 清除所有的爆破行为。 + +### 生命周期尺寸模块 + +[`SizeOverLifetimeModule`](${api}core/SizeOverLifetimeModule) 是 `ParticleGeneratorModule` 的子类，用于处理粒子系统的生命周期内的大小变化。 + +#### 属性 + +- [separateAxes](#${api}core/SizeOverLifetimeModule#separateAxes): 布尔值，指定每个轴的大小是否独立变化。 +- [sizeX](#${api}core/SizeOverLifetimeModule#sizeX): `ParticleCompositeCurve` 对象，表示 x 轴方向上粒子的大小变化曲线。 +- [sizeY](#${api}core/SizeOverLifetimeModule#sizeY): `ParticleCompositeCurve` 对象，表示 y 轴方向上粒子的大小变化曲线。 +- [sizeZ](#${api}core/SizeOverLifetimeModule#sizeZ): `ParticleCompositeCurve` 对象，表示 z 轴方向上粒子的大小变化曲线。 +- [size](#${api}core/SizeOverLifetimeModule#size): `ParticleCompositeCurve` 对象，获取或设置粒子的大小变化曲线。 + +### 生命周期颜色模块 + +[`ColorOverLifetimeModule`](${api}core/ColorOverLifetimeModule) 继承自 `ParticleGeneratorModule`，用于处理粒子系统的生命周期内的颜色变化。 + +#### 属性 + +- [color](#${api}core/ColorOverLifetimeModule#color): `ParticleCompositeGradient` 对象，表示粒子在其生命周期内的颜色渐变。 + +### 生命周期旋转模块 + +[`RotationOverLifetimeModule`](${api}core/RotationOverLifetimeModule) 继承自 `ParticleGeneratorModule`，用于控制粒子系统的生命周期内的旋转变化。 + +#### 属性 + +- [separateAxes](#${api}core/RotationOverLifetimeModule#separateAxes): `boolean` 类型，表示是否在每个轴上分别进行旋转。如果禁用，将只使用 z 轴。 + +- [rotationX](#${api}core/RotationOverLifetimeModule#rotationX): `ParticleCompositeCurve` 对象，表示粒子在其生命周期内的 x 轴旋转。 + +- [rotationY](#${api}core/RotationOverLifetimeModule#rotationY): `ParticleCompositeCurve` 对象，表示粒子在其生命周期内的 y 轴旋转。 + +- [rotationZ](#${api}core/RotationOverLifetimeModule#rotationZ): `ParticleCompositeCurve` 对象，表示粒子在其生命周期内的 z 轴旋转。 + +### 纹理表格动画模块 + +[`TextureSheetAnimationModule`](${api}core/TextureSheetAnimationModule) 继承自 `ParticleGeneratorModule`，用于控制粒子系统的纹理表动画。 + +#### 属性 + +- [startFrame](${api}core/TextureSheetAnimationModule#startFrame): `ParticleCompositeCurve` 对象，表示纹理表的起始帧。 + +- [frameOverTime](${api}core/TextureSheetAnimationModule#frameOverTime): `ParticleCompositeCurve` 对象，表示纹理表的帧随时间变化的曲线。 + +- [type](${api}core/TextureSheetAnimationModule#type): `TextureSheetAnimationType` 枚举，表示纹理表动画的类型。 + +- [cycleCount](${api}core/TextureSheetAnimationModule#cycleCount): `number` 类型，表示纹理表动画的周期计数。 + +- [tiling](${api}core/TextureSheetAnimationModule#tiling): `Vector2` 对象，表示纹理表的平铺。可以通过 `get` 和 `set` 方法访问和修改。 + +## 其他参数 + +- [velocityScale](${api}core/ParticleRenderer#velocityScale): 指定粒子根据其速度伸展的程度，类型为。 +- [lengthScale](${api}core/ParticleRenderer#lengthScale): 定义粒子在其运动方向上伸展的程度，定义为粒子的长度与其宽度的比例。 +- [pivot](${api}core/ParticleRenderer#pivot): 粒子的枢轴。 +- [renderMode](${api}core/ParticleRenderer#renderMode): 粒子的渲染模式。 +- [mesh](${api}core/ParticleRenderer#mesh): 粒子的网格，当 `renderMode` 为 `Mesh` 时有效。 + +## 渲染材质 + +[ParticleMaterial](${api}core/ParticleMaterial) 是粒子的默认材质，包含了一些粒子基本的常用材质属性。 + +### 属性 + +- [baseColor](${api}core/ParticleMaterial#baseColor): 基础颜色。 +- [baseTexture](${api}core/ParticleMaterial#baseColor): 基础纹理。