lywsvip/engine
1
0
Fork 0
mirror of https://github.com/galacean/engine.git synced 2026-05-06 22:23:05 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #2704 from eyworldwide/main

Browse Source 
Docs: particle renderer main module
This commit is contained in:
鹅叔
2025-05-28 20:01:12 +08:00
committed by GitHub
parent 927bd6c1ec c60ec02137
commit d0707bf2e6
2 changed files with 62 additions and 62 deletions
Download Patch File Download Diff File Expand all files Collapse all files

64
docs/en/graphics/particle/renderer-main-module.mdx
View File

@@ -6,44 +6,44 @@ group: Particle
label: Graphics/Particle
---
[MainModule](/apis/core/#MainModule) is the main module of `ParticleGeneratorModule`, containing the most basic particle generation parameters. These properties are mostly used to control the initial state of newly created particles.
[MainModule](/apis/core/#MainModule) is the primary module of the `ParticleGeneratorModule`, containing the most basic particle generation parameters. Most of these properties are used to control the initial state of newly created particles.
<Image src="https://mdn.alipayobjects.com/huamei_qbugvr/afts/img/A*JUjgTLfiz7kAAAAAAAAAAAAADtKFAQ/original" alt="avatar" style={{ zoom: "50%" }} />
## Properties
You can debug each property one by one in the provided example to help you better understand and control the main particle module, thereby achieving various complex and beautiful visual effects.
You can debug each property in the provided example to better understand and control the particle main module, thereby achieving various complex and beautiful visual effects.
Duration [duration](/apis/core/#MainModule-duration) determines how long the particle generator runs, in seconds. A longer duration means the particle system will generate more particles, creating a continuous effect.
| Property | Description |
| :--- | :--- |
| [duration](/apis/core/#MainModule-duration) | Duration. Determines how long the particle generator runs, in seconds. A longer duration means the particle system will generate more particles, creating a continuous effect. |
| [isLoop](/apis/core/#MainModule-isLoop) | Whether to loop. If set to true, the particle generator will automatically restart after the duration ends, forming a continuous effect like smoke or flowing water. |
| [startDelay](/apis/core/#MainModule-startDelay) | Start delay time. Determines how long the particle generator waits before emitting particles after starting. Useful for achieving effects like fireworks that require a time delay. |
| [startLifetime](/apis/core/#MainModule-startLifetime) | Initial lifetime. Determines how long each particle can survive before disappearing. A longer lifetime means particles will stay on the screen longer. |
| [startSpeed](/apis/core/#MainModule-startSpeed) | Initial speed when particles are first generated. Determines the speed at which particles are emitted. A higher initial speed will cause particles to spread rapidly, like an explosion effect; a lower speed will make particles float slowly, like smoke. |
| [startSize3D](/apis/core/#MainModule-startSize3D) | Whether to specify particle size separately for each axis. Allows setting different sizes for the particle's x, y, and z axes, creating anisotropic particle effects, such as elongated flames. |
| [startSize](/apis/core/#MainModule-startSize) | Initial size when the particle generator first generates particles. Controls the size of each particle. A larger initial size is suitable for simulating large clouds of smoke or flames, while a smaller size is suitable for delicate dust or splashes. |
| [startSizeX](/apis/core/#MainModule-startSizeX) | Initial size along the x-axis when the particle generator first generates particles. |
| [startSizeY](/apis/core/#MainModule-startSizeY) | Initial size along the y-axis when the particle generator first generates particles. |
| [startSizeZ](/apis/core/#MainModule-startSizeZ) | Initial size along the z-axis when the particle generator first generates particles. |
| [startRotation3D](/apis/core/#MainModule-startRotation3D) | Whether to enable 3D particle rotation. Allows particles to rotate in 3D space, increasing their sense of depth and complexity, such as falling leaves in three-dimensional space. |
| [startRotation](/apis/core/#MainModule-startRotation) | Initial rotation when the particle generator first generates particles. Sets the rotation angle at particle emission, suitable for effects where particles need to move in a specific direction, such as directional flames. |
| [startRotationX](/apis/core/#MainModule-startRotationX) | Initial rotation along the x-axis at particle emission. |
| [startRotationY](/apis/core/#MainModule-startRotationY) | Initial rotation along the y-axis at particle emission. |
| [startRotationZ](/apis/core/#MainModule-startRotationZ) | Initial rotation along the z-axis at particle emission. |
| [flipRotation](/apis/core/#MainModule-flipRotation) | Flip rotation. Ranges from 0 to 1, causing some particles to rotate in the opposite direction, increasing the randomness and naturalness of the particle system, suitable for simulating complex motion trajectories. |
| [startColor](/apis/core/#MainModule-startColor) | Initial color. Determines the color of particles, which can be used to simulate effects of different materials, such as the red-orange color of flames or the gray-white color of smoke. |
| [gravityModifier](/apis/core/#MainModule-gravityModifier) | Gravity modifier. Adjusts the extent to which particles are affected by gravity, making them appear more realistic, such as falling raindrops or rising smoke. |
| [simulationSpace](/apis/core/#MainModule-simulationSpace) | Chooses the space in which particles are simulated. Determines whether particles move relative to the world or relative to the generator itself. World space is suitable for stationary effects like smoke; local space is suitable for effects that move with the object, such as flame trails. |
| [simulationSpeed](/apis/core/#MainModule-simulationSpeed) | Simulation speed. Can globally speed up or slow down the movement speed of particles, suitable for slow motion or accelerated effects. |
| [scalingMode](/apis/core/#MainModule-scalingMode) | Scaling mode. Determines how the particle generator handles transformations such as position, rotation, and scaling when emitting particles. Using scalingMode ensures that the transformation relationship between the particle generator and the particles meets expectations. |
| [playOnEnabled](/apis/core/#MainModule-playOnEnabled) | If set to true, the particle generator will automatically start playing on launch. Enabling this option ensures that the particle system starts emitting particles as soon as it is activated, suitable for scenarios where immediate effects are needed. |
| [maxParticles](/apis/core/#MainModule-maxParticles) | Maximum particles. Limits the maximum number of particles in the particle system to prevent performance issues. A larger value is suitable for effects that require a large number of particles, such as dense smoke. |
Is Loop [isLoop](/apis/core/#MainModule-isLoop) if set to true, the particle generator will automatically restart after the duration ends, forming a continuous effect, such as smoke or flowing water.
### Explanation of scalingMode
Start Delay [startDelay](/apis/core/#MainModule-startDelay) determines the delay time before the particle generator starts emitting after being activated, which is useful for effects that require a time difference, such as fireworks.
The scalingMode has the following options:
Start Lifetime [startLifetime](/apis/core/#MainModule-startLifetime) determines how long each particle can live before disappearing. A longer lifetime means particles will stay on the screen longer.
Start Speed [startSpeed](/apis/core/#MainModule-startSpeed) determines the speed at which particles are emitted. Higher initial speed will cause particles to spread quickly, like an explosion effect; lower speed will make particles drift slowly, like a smoke effect.
Start Size 3D [startSize3D](/apis/core/#MainModule-startSize3D) allows setting different sizes for the x, y, z axes of the particles to achieve anisotropic particle effects, such as elongated flames. The initial size of particles when the particle generator first generates particles [startSize](/apis/core/#MainModule-startSize) controls the size of each particle. Larger initial size is suitable for simulating large clouds of smoke or flames, while smaller size is suitable for fine dust or splashes. For specific axis initial size, the initial size along the x-axis [startSizeX](/apis/core/#MainModule-startSizeX), along the y-axis [startSizeY](/apis/core/#MainModule-startSizeY), and along the z-axis [startSizeZ](/apis/core/#MainModule-startSizeZ) respectively control the size of particles on the x, y, z axes, making the particle shapes more diverse and delicate.
Start Rotation 3D [startRotation3D](/apis/core/#MainModule-startRotation3D) allows particles to rotate in 3D space, increasing the three-dimensionality and complexity of particles, such as falling leaves in three-dimensional space. The initial rotation of particles when the particle generator first generates particles (startRotation) sets the rotation angle of particles when emitted, suitable for effects where particles need to move in a specific direction, such as directional flames. The initial rotation along the x-axis [startRotationX](/apis/core/#MainModule-startRotationX), along the y-axis [startRotationY](/apis/core/#MainModule-startRotationY), and along the z-axis [startRotationZ](/apis/core/#MainModule-startRotationZ) respectively control the rotation of particles on the x, y, z axes, increasing the freedom of particle movement. Flip Rotation [flipRotation](/apis/core/#MainModule-flipRotation) ranges from 0 to 1, making some particles rotate in the opposite direction, increasing the randomness and naturalness of the particle system, suitable for simulating complex motion trajectories.
Start Color [startColor](/apis/core/#MainModule-startColor) determines the color of particles, which can be used to simulate different material effects, such as the red-orange color of flames or the gray-white color of smoke.
Gravity Modifier [gravityModifier](/apis/core/#MainModule-gravityModifier) adjusts the degree to which particles are affected by gravity, making particles look more realistic, such as falling raindrops or rising smoke.
The choice of simulation space [simulationSpace](/apis/core/#MainModule-simulationSpace) determines whether particles move relative to the world or to the emitter itself. World space is suitable for effects with fixed positions, such as smoke; local space is suitable for effects that move with objects, such as flame trails.
Simulation speed [simulationSpeed](/apis/core/#MainModule-simulationSpeed) can globally increase or decrease the movement speed of particles, suitable for slow-motion or accelerated effects.
Scaling mode [scalingMode](/apis/core/#MainModule-scalingMode) determines how the particle emitter handles position, rotation, and scaling transformations when emitting particles. Using scalingMode ensures that the transformation relationship between the particle emitter and particles meets expectations. scalingMode has the following modes:
- Local: Particles inherit the local transformation of the particle emitter, meaning particle transformations occur in the emitter's local coordinate system.
- World: Particles inherit the global transformation of the particle emitter, meaning particle transformations occur in the world coordinate system.
- Hierarchy: Particles inherit transformations from the entire hierarchy, considering the parent and higher-level transformations of the emitter.
If set to true, the particle emitter will automatically start playing when enabled [playOnEnabled](/apis/core/#MainModule-playOnEnabled). Enabling this option ensures that the particle system starts emitting particles immediately upon startup, suitable for scenes requiring immediate display of effects.
Maximum particles [maxParticles](/apis/core/#MainModule-maxParticles) limits the maximum number of particles in the particle system to prevent performance issues. A larger value is suitable for effects requiring a large number of particles, such as dense smoke.
- **Local**: Particles inherit the local transformation of the particle generator, meaning the particle transformation occurs in the generator's local coordinate system.
- **World**: Particles inherit the global transformation of the particle generator, meaning the particle transformation occurs in the world coordinate system.
- **Hierarchy**: Particles inherit transformations from the entire transformation hierarchy, meaning particles consider transformations of the generator's parent and higher-level transformations.

60
docs/zh/graphics/particle/renderer-main-module.mdx
View File

@@ -14,36 +14,36 @@ label: Graphics/Particle
你可以在提供的示例中逐个调试各项属性，帮助你更好地理解和掌控粒子住模块，从而实现各种复杂和精美的视觉效果。
持续时间 [duration](/apis/core/#MainModule-duration) 决定了粒子生成器运行多长时间，单位为秒。更长的持续时间意味着粒子系统会生成更多的粒子，创造出持续的效果。
| 属性 | 释义 |
| :--- | :--- |
| [duration](/apis/core/#MainModule-duration) | 持续时间。决定了粒子生成器运行多长时间，单位为秒。更长的持续时间意味着粒子系统会生成更多的粒子，创造出持续的效果 |
| [isLoop](/apis/core/#MainModule-isLoop) | 是否循环。如果设置为 true，粒子生成器会在持续时间结束后自动重新开始，从而形成一个连续的效果，比如烟雾或流水 |
| [startDelay](/apis/core/#MainModule-startDelay) | 开始延迟时间。决定了粒子生成器在启动后延迟一定时间才开始发射，这对于实现如烟花等需要时间差的效果非常有用 |
| [startLifetime](/apis/core/#MainModule-startLifetime) | 初始生命周期。决定了每个粒子在消失前能存活多久。更长的生命周期意味着粒子会在屏幕上停留更长时间 |
| [startSpeed](/apis/core/#MainModule-startSpeed) | 首次生成粒子时的初始速度。决定了粒子发射时的速度，较高的初始速度会使粒子迅速扩散，如爆炸效果；较低的速度则会使粒子缓慢飘动，如烟雾效果 |
| [startSize3D](/apis/core/#MainModule-startSize3D) | 是否以每个轴的粒子大小分别指定。允许为粒子的 x、y、z 轴设置不同的大小，以实现各向异性的粒子效果，比如长条形火焰 |
| [startSize](/apis/core/#MainModule-startSize) | 粒子生成器首次生成粒子时的初始大小。控制每个粒子的大小，较大的初始大小适合模拟大块的烟云或火焰，较小的则适合细腻的尘土或水花 |
| [startSizeX](/apis/core/#MainModule-startSizeX) | 粒子生成器首次生成粒子时沿 x 轴的初始大小 |
| [startSizeY](/apis/core/#MainModule-startSizeY) | 粒子生成器首次生成粒子时沿 y 轴的初始大小 |
| [startSizeZ](/apis/core/#MainModule-startSizeZ) | 粒子生成器首次生成粒子时沿 z 轴的初始大小 |
| [startRotation3D](/apis/core/#MainModule-startRotation3D) | 是否启用 3D 粒子旋转。允许粒子在 3D 空间中旋转，增加粒子的立体感和复杂性，如在三维空间内下坠的树叶 |
| [startRotation](/apis/core/#MainModule-startRotation) | 粒子生成器首次生成粒子时的初始旋转。设置粒子发射时的旋转角度，适用于需要粒子朝特定方向运动的效果，如方向性的火焰 |
| [startRotationX](/apis/core/#MainModule-startRotationX) | 粒子发射时沿 x 轴的初始旋转 |
| [startRotationY](/apis/core/#MainModule-startRotationY) | 粒子发射时沿 y 轴的初始旋转 |
| [startRotationZ](/apis/core/#MainModule-startRotationZ) | 粒子发射时沿 z 轴的初始旋转 |
| [flipRotation](/apis/core/#MainModule-flipRotation) | 翻转旋转。范围在 0 到 1 之间，使部分粒子以相反方向旋转，增加粒子系统的随机性和自然感，适用于模拟复杂的运动轨迹 |
| [startColor](/apis/core/#MainModule-startColor) | 初始颜色。决定了粒子的颜色，可用于模拟不同材质的效果，如火焰的红橙色或烟雾的灰白色 |
| [gravityModifier](/apis/core/#MainModule-gravityModifier) | 重力修正。调整粒子受重力影响的程度，使粒子看起来更真实，如下降的雨滴或上升的烟雾 |
| [simulationSpace](/apis/core/#MainModule-simulationSpace) | 选择模拟粒子的空间。决定了粒子是相对于世界还是相对于生成器自身运动。世界空间适合固定位置的效果，如烟雾；本地空间适合随对象移动的效果，如火焰尾迹 |
| [simulationSpeed](/apis/core/#MainModule-simulationSpeed) | 模拟速度。可整体加快或减慢粒子的运动速度，适用于时间慢动作或加速效果 |
| [scalingMode](/apis/core/#MainModule-scalingMode) | 缩放模式。决定了粒子生成器在发射粒子时，如何处理位置、旋转和缩放等变换操作。使用 scalingMode 能确保粒子生成器和粒子之间的变换关系符合预期 |
| [playOnEnabled](/apis/core/#MainModule-playOnEnabled) | 如果设置为 true，粒子生成器将在启动时自动开始播放。开启这个选项会确保粒子系统一启动就开始发射粒子，适用于需要立即显示效果的场景 |
| [maxParticles](/apis/core/#MainModule-maxParticles) | 最大粒子数。限制了粒子系统的最大粒子数，以防止性能问题。较大的值适用于需要大量粒子的效果，如浓烟 |
是否循环 [isLoop](/apis/core/#MainModule-isLoop) 如果设置为 true，粒子生成器会在持续时间结束后自动重新开始，从而形成一个连续的效果，比如烟雾或流水。
### scalingMode 模式说明
开始延迟时间 [startDelay](/apis/core/#MainModule-startDelay) 决定了粒子生成器在启动后延迟一定时间才开始发射，这对于实现如烟花等需要时间差的效果非常有用。
scalingMode 有以下几种模式：
初始生命周期 [startLifetime](/apis/core/#MainModule-startLifetime) 决定了每个粒子在消失前能存活多久。更长的生命周期意味着粒子会在屏幕上停留更长时间。
首次生成粒子时的初始速度 [startSpeed](/apis/core/#MainModule-startSpeed) 决定了粒子发射时的速度，较高的初始速度会使粒子迅速扩散，如爆炸效果；较低的速度则会使粒子缓慢飘动，如烟雾效果。
是否以每个轴的粒子大小分别指定 [startSize3D](/apis/core/#MainModule-startSize3D) 允许为粒子的 x、y、z 轴设置不同的大小，以实现各向异性的粒子效果，比如长条形火焰。粒子生成器首次生成粒子时的初始大小 [startSize](/apis/core/#MainModule-startSize) 控制每个粒子的大小，较大的初始大小适合模拟大块的烟云或火焰，较小的则适合细腻的尘土或水花。针对具体轴的初始大小，粒子生成器首次生成粒子时沿 x 轴的初始大小 [startSizeX](/apis/core/#MainModule-startSizeX) 、沿 y 轴的初始大小 [startSizeY](/apis/core/#MainModule-startSizeY) 和沿 z 轴的初始大小 [startSizeZ](/apis/core/#MainModule-startSizeZ) 分别控制粒子在 x、y、z 轴上的大小，使粒子形状更加多样化和细腻。
是否启用 3D 粒子旋转 [startRotation3D](/apis/core/#MainModule-startRotation3D) 允许粒子在 3D 空间中旋转，增加粒子的立体感和复杂性，如在三维空间内☑️下坠的树叶。粒子生成器首次生成粒子时的初始旋转 (startRotation) 设置粒子发射时的旋转角度，适用于需要粒子朝特定方向运动的效果，如方向性的火焰。而粒子发射时沿 x 轴的初始旋转 [startRotationX](/apis/core/#MainModule-startRotationX)、沿 y 轴的初始旋转 [startRotationY](/apis/core/#MainModule-startRotationY) 和沿 z 轴的初始旋转 [startRotationZ](/apis/core/#MainModule-startRotationZ) 分别控制粒子在 x、y、z 轴上的旋转，增加粒子运动的自由度。翻转旋转 [flipRotation](/apis/core/#MainModule-flipRotation) 范围在 0 到 1 之间，使部分粒子以相反方向旋转，增加粒子系统的随机性和自然感，适用于模拟复杂的运动轨迹。
初始颜色 [startColor](/apis/core/#MainModule-startColor) 决定了粒子的颜色，可用于模拟不同材质的效果，如火焰的红橙色或烟雾的灰白色。
重力修正 [gravityModifier](/apis/core/#MainModule-gravityModifier) 调整粒子受重力影响的程度，使粒子看起来更真实，如下降的雨滴或上升的烟雾。
选择模拟粒子的空间 [simulationSpace](/apis/core/#MainModule-simulationSpace) 决定了粒子是相对于世界还是相对于生成器自身运动。世界空间适合固定位置的效果，如烟雾；本地空间适合随对象移动的效果，如火焰尾迹。
模拟速度 [simulationSpeed](/apis/core/#MainModule-simulationSpeed) 可整体加快或减慢粒子的运动速度，适用于时间慢动作或加速效果。
缩放模式 [scalingMode](/apis/core/#MainModule-scalingMode) 决定了粒子生成器在发射粒子时，如何处理位置、旋转和缩放等变换操作。使用 scalingMode 能确保粒子生成器和粒子之间的变换关系符合预期。scalingMode 有以下几种模式：
- Local：粒子会继承粒子生成器的局部变换，即粒子的变换是在生成器的本地坐标系中进行的。
- World：粒子会继承粒子生成器的全局变换，即粒子的变换是在世界坐标系中进行的。
- Hierarchy：粒子会继承整个变换层级中的变换，即粒子会考虑到生成器的父级及更上级的变换。
如果设置为 true，粒子生成器将在启动时自动开始播放 [playOnEnabled](/apis/core/#MainModule-playOnEnabled) 。开启这个选项会确保粒子系统一启动就开始发射粒子，适用于需要立即显示效果的场景。
最大粒子数 [maxParticles](/apis/core/#MainModule-maxParticles) 限制了粒子系统的最大粒子数，以防止性能问题。较大的值适用于需要大量粒子的效果，如浓烟。
- **Local**：粒子会继承粒子生成器的局部变换，即粒子的变换是在生成器的本地坐标系中进行的
- **World**：粒子会继承粒子生成器的全局变换，即粒子的变换是在世界坐标系中进行的
- **Hierarchy**：粒子会继承整个变换层级中的变换，即粒子会考虑到生成器的父级及更上级的变换