# 粒子系统（ParticleSystem）

[ParticleSystem](https://vjmap.com/map3d/api/classes/ParticleSystem.html) 用于模拟大量微小图形（粒子）的行为，以创造出复杂的动态效果。它通过模块化的方式工作，允许开发者调整粒子的发射、运动、生命周期、外观等多个方面，从而实现高度自定义的视觉效果。

**核心功能：**

- **主模块**：控制粒子的基本属性，如发射持续时间、速度、数量等。
- **发射模块**：决定粒子如何被发射，包括发射速率、突发发射等。
- **形状模块**：定义粒子从哪里发射以及如何分布。
- **动画模块**：管理粒子的生命周期内的变化，如大小、颜色的变化。
- **碰撞模块**：使粒子能与场景中的其他对象交互，如反弹或销毁。
- **力模块**：应用额外的力场影响粒子运动，如风力、重力。

## 常用属性
|属性|描述|
|:---|:---|
|[autoDestroy](https://vjmap.com/map3d/api/classes/ParticleSystem.html#autoDestroy)|是否自动销毁，默认 `false`。注意通过 `app.addParticle`/`loadParticle*` 添加时另有 `disposeWhenEnd` 选项（默认 `true`），粒子系统结束（不循环且粒子全部消失）后自动 `dispose`|
|[prewarm](https://vjmap.com/map3d/api/classes/ParticleSystem.html#prewarm)|循环的ParticleSystem是否应该预热，即粒子系统在第一次变为可见时看起来已经模拟了一个循环。|
|[looping](https://vjmap.com/map3d/api/classes/ParticleSystem.html#looping)|粒子按照周期循环发射 让粒子发射时间循环起来，一直发射粒子。默认 `true`|
|[emitterShape](https://vjmap.com/map3d/api/classes/ParticleSystem.html#emitterShape)|发射器形状Shape模块（构造参数名为 `shape`，默认 `SphereEmitter`）：`PointEmitter`、`SphereEmitter`、`HemisphereEmitter` 半球、`ConeEmitter` 锥体、`CircleEmitter`、`DonutEmitter` 甜甜圈、`CubeEmitter` 立方体（**没有 BoxEmitter**）、`GridEmitter`、`MeshSurfaceEmitter` 等，见[粒子发射器](./particleemitter.md)。Random/Loop/PingPong/Burst 是形状的 `mode`（`vjmap3d.EmitterMode`），不是形状|
|[duration](https://vjmap.com/map3d/api/classes/ParticleSystem.html#duration)|持续时间（以秒为单位），默认 `1`|
|[startLife](https://vjmap.com/map3d/api/classes/ParticleSystem.html#startLife)|粒子从发生到消失的时间长短。|
|[startSpeed](https://vjmap.com/map3d/api/classes/ParticleSystem.html#startSpeed)|粒子起始速度的值生成器或函数值生成器。|
|[startRotation](https://vjmap.com/map3d/api/classes/ParticleSystem.html#startRotation)|用于启动粒子旋转的值生成器或函数值生成器或旋转生成器。|
|[startSize](https://vjmap.com/map3d/api/classes/ParticleSystem.html#startSize)|用于启动粒子大小的值生成器或函数值生成器或旋转生成器。|
|[startColor](https://vjmap.com/map3d/api/classes/ParticleSystem.html#startColor)|用于启动粒子颜色的值生成器或函数值生成器或旋转生成器。|
|[startTileIndex](https://vjmap.com/map3d/api/classes/ParticleSystem.html#startTileIndex)|粒子的起始平铺索引的值生成器。（精灵纹理总的图像数里面的位置索引）|
|[rendererEmitterSettings](https://vjmap.com/map3d/api/classes/ParticleSystem.html#rendererEmitterSettings)|ParticleSystem的渲染器发射器设置。`StretchedBillBoard` 模式用 `{ speedFactor, lengthFactor }`（其他模式下这两项无作用）；`Trail` 模式**必须**给 `{ startLength: ValueGenerator }`，否则发射粒子时抛错|
|[emissionOverTime](https://vjmap.com/map3d/api/classes/ParticleSystem.html#emissionOverTime)|粒子随时间的发射速率的值生成器或函数值生成器。（发射频率按时间 1秒发射的数量。）|
|[emissionOverDistance](https://vjmap.com/map3d/api/classes/ParticleSystem.html#emissionOverDistance)|粒子随距离的发射速率的值生成器或函数值生成器。|
|[emissionBursts](https://vjmap.com/map3d/api/classes/ParticleSystem.html#emissionBursts)|指定时间瞬间发射出粒子参数数组。（ 瞬间发射出粒子从第几（Time）秒开始。发射多少个（Count）。这次发射循环几次（Cycles）。每次循环间隔多久（Interval）。probability ( 每次爆发的可能性)）。⚠️ `cycle`/`interval` 运行时**未实现**（只随 toJSON 序列化），每个 burst 每个周期只按 `time` 发射一次|
|[onlyUsedByOther](https://vjmap.com/map3d/api/classes/ParticleSystem.html#onlyUsedByOther)|确定ParticleSystem是否仅由其他ParticleSystem使用。|
|[worldSpace](https://vjmap.com/map3d/api/classes/ParticleSystem.html#worldSpace)|是在世界空间中还是在局部空间中。|
|[particleNum](https://vjmap.com/map3d/api/classes/ParticleSystem.html#particleNum)|粒子数量|
|[paused](https://vjmap.com/map3d/api/classes/ParticleSystem.html#paused)|是否暂停|
|[particles](https://vjmap.com/map3d/api/classes/ParticleSystem.html#particles)|所有粒子对象数组|
|[emitterShape](https://vjmap.com/map3d/api/classes/ParticleSystem.html#emitterShape)|粒子发射器形状|
|[emitter](https://vjmap.com/map3d/api/classes/ParticleSystem.html#emitter)|添加到场景中的发射器对象|
|[rendererSettings](https://vjmap.com/map3d/api/classes/ParticleSystem.html#rendererSettings)|渲染设置：`instancingGeometry`、`renderMode`、`renderOrder`、`material`、`uTileCount`/`vTileCount`、`blendTiles`、`softParticles`/`softNearFade`/`softFarFade`、`layers`。（`speedFactor`/`lengthFactor` 不在这里，属于 `rendererEmitterSettings`）|
|[neededToUpdateRender](https://vjmap.com/map3d/api/classes/ParticleSystem.html#neededToUpdateRender)|是否需要更新批处理渲染器的渲染器设置|
|[simulations](https://vjmap.com/map3d/api/classes/ParticleSystem.html#simulations)|所有粒子模拟行为数组|



## 常用方法
|方法|描述|
|:---|:---|
|[time](https://vjmap.com/map3d/api/classes/ParticleSystem.html#time)|时间|
|[layers](https://vjmap.com/map3d/api/classes/ParticleSystem.html#layers)|当前图层， 如果更改图层设置，则需要手动设置this.neededToUpdateRender=true；|
|[texture](https://vjmap.com/map3d/api/classes/ParticleSystem.html#texture)|纹理|
|[material](https://vjmap.com/map3d/api/classes/ParticleSystem.html#material)|材质|
|[uTileCount](https://vjmap.com/map3d/api/classes/ParticleSystem.html#uTileCount)|纹理水平方向有几张图片 （uTileCount * vTileCount ) 表示此纹理总的图像数|
|[vTileCount](https://vjmap.com/map3d/api/classes/ParticleSystem.html#vTileCount)|纹理垂直方向有几张图片|
|[blendTiles](https://vjmap.com/map3d/api/classes/ParticleSystem.html#blendTiles)|blendTiles|
|[softParticles](https://vjmap.com/map3d/api/classes/ParticleSystem.html#softParticles)|当粒子接近写入深度缓冲区的对象表面时淡出粒子。当粒子与不透明几何体相交时，这对于避免硬边非常有用。例如，通过启用软粒子，可以使粒子系统发射接近不透明表面的粒子，而不会与表面产生突兀的相交|
|[softNearFade](https://vjmap.com/map3d/api/classes/ParticleSystem.html#softNearFade)|软粒子近距离淡出值|
|[softFarFade](https://vjmap.com/map3d/api/classes/ParticleSystem.html#softFarFade)|软粒子远距离淡出值|
|[instancingGeometry](https://vjmap.com/map3d/api/classes/ParticleSystem.html#instancingGeometry)|实例化几何体对象|
|[renderMode](https://vjmap.com/map3d/api/classes/ParticleSystem.html#renderMode)|渲染模式 BillBoard = 0, 粒子始终面向摄像机。StretchedBillBoard = 1, 粒子面向摄像机，但是会应用各种缩放。 Mesh = 2,Trail = 3,HorizontalBillBoard = 4, // 粒子平面与XZ“地板”平面平行。 VerticalBillBoard = 5 // 粒子在世界y轴上直立，但面向摄像机。|
|[renderOrder](https://vjmap.com/map3d/api/classes/ParticleSystem.html#renderOrder)|渲染次序|
|[blending](https://vjmap.com/map3d/api/classes/ParticleSystem.html#blending)|混合属性|
|[pause](https://vjmap.com/map3d/api/classes/ParticleSystem.html#pause)|暂停|
|[play](https://vjmap.com/map3d/api/classes/ParticleSystem.html#play)|播放|
|[restart](https://vjmap.com/map3d/api/classes/ParticleSystem.html#restart)|重新开始|
|[toJSON](https://vjmap.com/map3d/api/classes/ParticleSystem.html#toJSON)|转JSON|
|[fromJSON](https://vjmap.com/map3d/api/classes/ParticleSystem.html#fromJSON)|来源于JSON|
|[addSimulation](https://vjmap.com/map3d/api/classes/ParticleSystem.html#addSimulation)|增加粒子模拟行为|
|[clone](https://vjmap.com/map3d/api/classes/ParticleSystem.html#clone)|克隆|

## 信号 
|信号名|描述|
|:---|:---|
|onRestart|重新开始事件|
|onPlay|开始事件|
|onPause|暂停事件|
|onEnd|结束事件。⚠️ 发射结束且粒子数为 0 后**每帧都会派发**，直到系统被 dispose——自行监听请用 `system.signal.onEnd.addOne(...)` 只收一次|