# 粒子发射器（ParticleEmitter）

 [ParticleEmitter](https://vjmap.com/map3d/api/classes/ParticleEmitter.html) 是一个单独的组件，用于控制粒子的发射。

常用粒子发射器形状

## 圆形发射器 [CircleEmitter](https://vjmap.com/map3d/api/classes/CircleEmitter.html)

发射器形状类型名称: `circle`

|属性|类型|描述|
|:---|:---|:---|
|radius|number|半径|
|arc|radian|有效发射角度（弧度表示）|
|thickness|number|发射粒子的体积比例。值为 0 表示从形状的外表面发射粒子。值为 1 表示从整个体积发射粒子。介于两者之间的值将使用体积的一定比例。当这个值为0到1之间的时候会在原球形里面再产生一个小球体，粒子从原球体和小球体之间发射。|
|mode|[emitterMode](https://vjmap.com/map3d/api/enums/EmitterMode.html)|如何在形状的弧形周围生成粒子|
|spread|number|形状周围可产生粒子的离散间隔。例如，值为 0 表示允许在弧形周围的任何位置生成粒子，值为 0.1 表示仅在形状周围以 10% 的间隔生成粒子。|
|speed|valueFunc|发射位置沿弧线推进的速度，仅在 `mode` 为 Loop/PingPong 时起作用（**不是**粒子速度，粒子初速请用粒子系统的 `startSpeed`）|

## 锥形发射器 [ConeEmitter](https://vjmap.com/map3d/api/classes/ConeEmitter.html)

发射器形状类型名称: `cone`

|属性|类型|描述|
|:---|:---|:---|
|radius|number|半径|
|arc|radian|有效发射角度（弧度表示）设置圆锥发射器发射粒子的扇形区域|
|thickness|number|发射粒子的体积比例。值为 0 表示从形状的外表面发射粒子。值为 1 表示从整个体积发射粒子。介于两者之间的值将使用体积的一定比例。当这个值为0到1之间的时候会在原球形里面再产生一个小球体，粒子从原球体和小球体之间发射。|
|angle|radian|角度（弧度表示）圆锥的轴与母线的夹角，值越大夹角越大，圆锥发射器的开合程度越大|
|mode|[emitterMode](https://vjmap.com/map3d/api/enums/EmitterMode.html)|如何在形状的弧形周围生成粒子|
|spread|number|形状周围可产生粒子的离散间隔。例如，值为 0 表示允许在弧形周围的任何位置生成粒子，值为 0.1 表示仅在形状周围以 10% 的间隔生成粒子。|
|speed|valueFunc|发射位置沿弧线推进的速度，仅在 `mode` 为 Loop/PingPong 时起作用（**不是**粒子速度，粒子初速请用粒子系统的 `startSpeed`）|


## 甜甜圈发射器 [DonutEmitter](https://vjmap.com/map3d/api/classes/DonutEmitter.html)

发射器形状类型名称: `donut`

|属性|类型|描述|
|:---|:---|:---|
|radius|number|半径|
|arc|radian|有效发射角度（弧度表示）|
|thickness|number|发射粒子的体积比例。值为 0 表示从形状的外表面发射粒子。值为 1 表示从整个体积发射粒子。介于两者之间的值将使用体积的一定比例。当这个值为0到1之间的时候会在原球形里面再产生一个小球体，粒子从原球体和小球体之间发射。|
|donutRadius|number|甜甜圈半径|
|mode|[emitterMode](https://vjmap.com/map3d/api/enums/EmitterMode.html)|如何在形状的弧形周围生成粒子|
|spread|number|形状周围可产生粒子的离散间隔。例如，值为 0 表示允许在弧形周围的任何位置生成粒子，值为 0.1 表示仅在形状周围以 10% 的间隔生成粒子。|
|speed|valueFunc|发射位置沿弧线推进的速度，仅在 `mode` 为 Loop/PingPong 时起作用（**不是**粒子速度，粒子初速请用粒子系统的 `startSpeed`）|


## 点发射器 [PointEmitter](https://vjmap.com/map3d/api/classes/PointEmitter.html)

发射器形状类型名称: `point`


## 球形发射器 [SphereEmitter](https://vjmap.com/map3d/api/classes/SphereEmitter.html)

发射器形状类型名称: `sphere`

|属性|类型|描述|
|:---|:---|:---|
|radius|number|半径|
|arc|radian|有效发射角度（弧度表示）|
|thickness|number|发射粒子的体积比例。值为 0 表示从形状的外表面发射粒子。值为 1 表示从整个体积发射粒子。介于两者之间的值将使用体积的一定比例。当这个值为0到1之间的时候会在原球形里面再产生一个小球体，粒子从原球体和小球体之间发射。|
|mode|[emitterMode](https://vjmap.com/map3d/api/enums/EmitterMode.html)|如何在形状的弧形周围生成粒子|
|spread|number|形状周围可产生粒子的离散间隔。例如，值为 0 表示允许在弧形周围的任何位置生成粒子，值为 0.1 表示仅在形状周围以 10% 的间隔生成粒子。|
|speed|valueFunc|发射位置沿弧线推进的速度，仅在 `mode` 为 Loop/PingPong 时起作用（**不是**粒子速度，粒子初速请用粒子系统的 `startSpeed`）|



## 半球发射器 [HemisphereEmitter](https://vjmap.com/map3d/api/classes/HemisphereEmitter.html)

发射器形状类型名称: `hemisphere`（JSON/注册表用此名；注意实例字段 `emitter.type` 在 2.0.0 源码里误写为 `'sphere'`，判断半球发射器请用 `instanceof vjmap3d.HemisphereEmitter` 或 `toJSON().type`）

|属性|类型|描述|
|:---|:---|:---|
|radius|number|半径|
|arc|radian|有效发射角度（弧度表示）|
|thickness|number|发射粒子的体积比例。值为 0 表示从形状的外表面发射粒子。值为 1 表示从整个体积发射粒子。介于两者之间的值将使用体积的一定比例。当这个值为0到1之间的时候会在原球形里面再产生一个小球体，粒子从原球体和小球体之间发射。|
|mode|[emitterMode](https://vjmap.com/map3d/api/enums/EmitterMode.html)|如何在形状的弧形周围生成粒子|
|spread|number|形状周围可产生粒子的离散间隔。例如，值为 0 表示允许在弧形周围的任何位置生成粒子，值为 0.1 表示仅在形状周围以 10% 的间隔生成粒子。|
|speed|valueFunc|发射位置沿弧线推进的速度，仅在 `mode` 为 Loop/PingPong 时起作用（**不是**粒子速度，粒子初速请用粒子系统的 `startSpeed`）|

## 网格发射器 [GridEmitter](https://vjmap.com/map3d/api/classes/GridEmitter.html)

发射器形状类型名称: `grid`

|属性|类型|描述|
|:---|:---|:---|
|width|number|网格宽|
|height|number|网格高|
|row|number|网格行|
|column|number|网格列|


## Mesh表面发射器 [MeshSurfaceEmitter](https://vjmap.com/map3d/api/classes/MeshSurfaceEmitter.html)

发射器形状类型名称: `mesh_surface`

|属性|类型|描述|
|:---|:---|:---|
|geometry|geometry|几何体|


## 立方体发射器 [CubeEmitter](https://vjmap.com/map3d/api/classes/CubeEmitter.html)

发射器形状类型名称: `cube`

|属性|类型|描述|
|:---|:---|:---|
|width|number|X 方向**半**宽（粒子在 `[-width, width]` 内生成），默认 10|
|height|number|Y 方向**半**高，默认 10|
|thickness|number|Z 方向**半**厚，默认 10|
|mode|[emitterMode](https://vjmap.com/map3d/api/enums/EmitterMode.html)|生成方式（只作用于 X 坐标，Y/Z 始终随机）|
|spread|number|形状周围可产生粒子的离散间隔。例如，值为 0 表示允许在弧形周围的任何位置生成粒子，值为 0.1 表示仅在形状周围以 10% 的间隔生成粒子。|
|speed|valueFunc|Loop/PingPong 模式下发射位置推进的速度（不是粒子速度）|

> ⚠️ 粒子初速度方向取自归一化前的 `[0,1)³` 随机坐标，**只朝 +X/+Y/+Z 一个卦限**发散，不是从中心向四周；需要四周发散请改用 `SphereEmitter` 等形状或用 `ChangeEmitDirection`/`SetEmitDirection` 调整方向。


## 路径发射器 [PathEmitter](https://vjmap.com/map3d/api/classes/PathEmitter.html)

发射器形状类型名称: `path`

|属性|类型|描述|
|:---|:---|:---|
|paths|[number, number, number][]|路径坐标|
|mode|[emitterMode](https://vjmap.com/map3d/api/enums/EmitterMode.html)|仅序列化，运行时**不起作用**（总是在随机一段上随机取点）|
|spread|number|仅序列化，运行时不起作用|
|speed|valueFunc|仅序列化，运行时不起作用|

> ⚠️ **运行时缺陷**：内部用 `MathUtils.randInt(0, paths.length)`（含上界）选段，约有 `1/(n+1)` 的概率取到越界下标，`new Vector3(...undefined)` 直接抛错，渲染循环随之报错；粒子初速度也固定朝 +Z。生产环境不建议使用 `PathEmitter`。