> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/3d-nei-rong-ji-chu/particle-system.md).

# 粒子系统

为你的场景添加火焰、雨水、火花和魔法光环等粒子效果

粒子系统可通过发射并动画化大量小精灵来创建动态视觉效果。可用它们构建火焰、烟雾、雨、雪、火花、魔法光环、爆炸，以及许多其他用静态网格体难以实现的效果。

## 添加粒子系统

要将粒子系统添加到你的场景中，请创建一个实体并附加 `ParticleSystem` 组件。

```ts
import { engine, Transform, ParticleSystem } from '@dcl/sdk/ecs'
import { Vector3 } from '@dcl/sdk/math'

const emitter = engine.addEntity()

Transform.create(emitter, {
	position: Vector3.create(8, 1, 8),
})

ParticleSystem.create(emitter, {})
```

在未设置任何属性时，该组件会使用所有默认值：一个点发射器，每秒发射 10 个粒子，粒子生命周期为 5 秒。

## 发射器形状

发射器形状决定粒子的生成位置。可通过 `ParticleSystem.Shape` 辅助函数获取四种形状。

### 点

粒子从单个点（实体的位置）生成。这是未指定形状时的默认值。

```ts
ParticleSystem.create(emitter, {
	shape: ParticleSystem.Shape.Point(),
})
```

### Sphere

粒子从球体表面或内部生成。

```ts
ParticleSystem.create(emitter, {
	shape: ParticleSystem.Shape.Sphere({ radius: 2 }),
})
```

### 圆锥

粒子从圆锥底部生成，并沿圆锥方向向外移动。 `角度` 是以度为单位的半角； `radius` 是以米为单位的底部半径。要调整圆锥的朝向，请设置实体的 `Transform`.

```ts
ParticleSystem.create(emitter, {
	shape: ParticleSystem.Shape.Cone({ angle: 25, radius: 1 }),
})
```

### Box

粒子从盒体体积内的任意位置生成。

```ts
ParticleSystem.create(emitter, {
	shape: ParticleSystem.Shape.Box({ size: Vector3.create(3, 1, 3) }),
})
```

## 发射属性

控制会创建多少粒子以及它们存活多长时间。

| 属性       | 默认值    | 描述              |
| -------- | ------ | --------------- |
| `速率`     | `10`   | 每秒发射的粒子数（连续）。   |
| `最大粒子数`  | `1000` | 同时存活粒子的硬性上限。    |
| `生命周期`   | `5`    | 每个粒子的存活时间，单位为秒。 |
| `active` | `真`    | 系统是否正在主动发射新粒子。  |

```ts
ParticleSystem.create(emitter, {
	rate: 50,
	maxParticles: 500,
	lifetime: 3,
})
```

## 运动

### 重力

该 `重力` 属性是应用于场景重力（-9.81 m/s²）的乘数。将其设置为 `0` 可让粒子悬浮在原地；设为负值可将其向上推动，设为正值可使其向下加速。

```ts
ParticleSystem.create(emitter, {
	重力：-0.5，// 粒子缓慢向上漂浮
})
```

### 初始速度

`initialVelocitySpeed` 是一个 `FloatRange` 用于设置每个粒子发射时随机速度范围的最小值和最大值（单位 m/s）。两个值的默认值为 `1`.

```ts
ParticleSystem.create(emitter, {
	initialVelocitySpeed: { start: 2, end: 8 },
})
```

### 额外力

除重力之外，每一帧都应用于所有粒子的恒定力向量。适用于风力或磁力效果。

```ts
ParticleSystem.create(emitter, {
	additionalForce: Vector3.create(0.5, 0, 0), // 恒定的侧向推力
})
```

### 速度限制

使用 `limitVelocity` 用于限制粒子的最大速度，并可选择在每一帧衰减其超出部分的速度。

```ts
ParticleSystem.create(emitter, {
	limitVelocity: {
		speed: 5, // 允许的最大速度（m/s）
		dampen: 0.8, // 每帧移除的超出速度比例
	},
})
```

## 视觉属性

### 颜色

`initialColor` 设置粒子出生时的颜色，会在给定范围内随机选取。 `colorOverTime` 使粒子的颜色逐渐从 `start` 添加到 `end` 值在粒子的生命周期内变化。两者都接受一个 `ColorRange` 并配合一个 `start` 和 `end` 值。

```ts
import { Color4 } from '@dcl/sdk/math'

ParticleSystem.create(emitter, {
	initialColor: {
		start: Color4.create(1, 0.5, 0, 1), // 橙色
		end: Color4.create(1, 1, 0, 1), // 黄色
	},
	colorOverTime: {
		start: Color4.create(0.5, 0, 0, 0.5), // 暗红色，半透明
		end: Color4.create(0, 0, 0, 0), // 完全透明（淡出）
	},
})
```

请注意，a 中的第 4 个值 `Color4` 是 *透明度*。如果你将最终颜色设置为 alpha 为 0 的颜色，粒子会逐渐淡出并变得不可见，这通常是个不错的效果。

### 大小

`initialSize` 和 `sizeOverTime` 中是 `FloatRange` 取值列表。 `initialSize` 控制粒子出生时的缩放，会在给定范围内随机选取。 `sizeOverTime` 使粒子的缩放逐渐从 `start` 添加到 `end` 值在粒子的生命周期内变化。值为 `1` 等于原始纹理大小。

```ts
ParticleSystem.create(emitter, {
	initialSize: { start: 0.1, end: 0.3 },
	sizeOverTime: { start: 0.5, end: 1.0 }, // 在生命周期内增长
})
```

{% hint style="warning" %}
**📔 注意**： `缩放` 实体的 `Transform` 不会影响粒子的缩放。
{% endhint %}

### 纹理

默认情况下，粒子会渲染为白色方块。提供一个纹理即可使用自定义图像。

```ts
ParticleSystem.create(emitter, {
	texture: { src: 'assets/scene/Images/spark.png' },
})
```

### 混合模式

控制粒子颜色与其后方场景的合成方式。

| 值                                      | 描述                       |
| -------------------------------------- | ------------------------ |
| `ParticleSystemBlendMode.PSB_ALPHA`    | 标准透明度（默认）。               |
| `ParticleSystemBlendMode.PSB_ADD`      | 加色混合——粒子会照亮场景。适合火焰和发光效果。 |
| `ParticleSystemBlendMode.PSB_MULTIPLY` | 将粒子颜色与其后方场景相乘。           |

```ts
import { ParticleSystemBlendMode } from '@dcl/sdk/ecs'

ParticleSystem.create(emitter, {
	texture: { src: 'assets/scene/textures/ember.png' },
	blendMode: ParticleSystemBlendMode.PSB_ADD,
})
```

### 广告牌

当 `billboard` 为 `真` （默认）时，每个粒子都会始终朝向摄像机，与发射器的朝向无关。将其设置为 `false` 用于应当在 3D 空间中翻滚的粒子。

```ts
ParticleSystem.create(emitter, {
	billboard: false,
})
```

## 旋转

### 初始旋转和随时间旋转

`initialRotation` 是粒子生成时的朝向。 `rotationOverTime` 是每个轴每秒应用的角速度。两者都接受一个 `Quaternion`.

```ts
import { Quaternion } from '@dcl/sdk/math'

ParticleSystem.create(emitter, {
	initialRotation: Quaternion.fromEulerDegrees(0, 0, 45),
	rotationOverTime: Quaternion.fromEulerDegrees(0, 0, 90), // 在 Z 轴上以 90°/秒旋转
})
```

{% hint style="warning" %}
**📔 注意**：如果 `billboard` 被设为 `真`，那么粒子将只会绕一个轴旋转，并始终保持朝向摄像机。
{% endhint %}

### 面向运动方向

当 `faceTravelDirection` 为 `真`，每个粒子都会自动旋转以指向其运动方向，就像小行星或树叶在空中下落一样。

```ts
ParticleSystem.create(emitter, {
	faceTravelDirection: true,
	billboard: false,
})
```

{% hint style="warning" %}
**📔 注意**：如果 `faceTravelDirection` 为 true 时，值 `billboard` 将被忽略。
{% endhint %}

## 精灵表动画

你可以将纹理视为动画帧网格来为粒子添加动画。指定精灵表中的列数、行数以及播放速度。

```ts
ParticleSystem.create(emitter, {
	texture: { src: 'assets/scene/textures/flame-sheet.png' },
	spriteSheet: {
		tilesX: 4, // 4 列
		tilesY: 3, // 3 行（共 12 帧）
		framesPerSecond: 12,
	},
})
```

## 播放控制

粒子系统可处于由 `playbackState`.

| 值                                        | 描述                 |
| ---------------------------------------- | ------------------ |
| `ParticleSystemPlaybackState.PS_PLAYING` | 正在主动发射（默认）。        |
| `ParticleSystemPlaybackState.PS_PAUSED`  | 将当前所有粒子冻结在原地并停止发射。 |
| `ParticleSystemPlaybackState.PS_STOPPED` | 停止发射并移除所有现有粒子。     |

```ts
import { ParticleSystemPlaybackState } from '@dcl/sdk/ecs'

// 当玩家走远时暂停
ParticleSystem.getMutable(emitter).playbackState =
	ParticleSystemPlaybackState.PS_PAUSED

// 恢复
ParticleSystem.getMutable(emitter).playbackState =
	ParticleSystemPlaybackState.PS_PLAYING
```

### 循环与预热

默认情况下，系统会无限循环。将 `loop` 为 `false` 可用于一次性效果，在所有粒子死亡后自动停止。

将 `prewarm` 为 `真` （需要 `loop: true`）用于模拟该系统仿佛从一开始就已运行，因此当玩家第一次看到它时，粒子就已经充满场景。

```ts
ParticleSystem.create(emitter, {
	loop: false, // 播放一次然后停止
	prewarm: false,
})
```

## 爆发式发射

爆发可让你在特定时刻发射大量粒子，而不是以恒定速率发射。它们适用于爆炸、烟花或其他一次性事件。

单个粒子系统可以在一个周期中包含多个爆发，即使它们的间隔或概率不同，也会显得更自然。

```ts
ParticleSystem.create(emitter, {
	rate: 0, // 禁用持续发射
	bursts: {
		values: [
			{
				time: 0, // 播放开始后的时间（秒）
				count: 200, // 每次爆发发射的粒子数
				cycles: 1, // 重复次数（0 = 无限）
				interval: 0.2, // 重复周期之间的间隔（秒）
				probability: 1, // 每个周期爆发触发的概率，范围 0–1
			},
		],
	},
})
```

对于带有错时爆发的循环烟花效果：

```ts
ParticleSystem.create(emitter, {
	loop: true,
	rate: 0,
	lifetime: 2,
	bursts: {
		values: [
			{ time: 0.0, count: 80, cycles: 0, interval: 3 },
			{ time: 0.7, count: 100, cycles: 0, interval: 3 },
			{ time: 1.4, count: 60, cycles: 0, interval: 3 },
		],
	},
})
```

## 模拟空间

控制粒子是相对于发射器移动（`PSS_LOCAL`，默认）还是在生成后固定在世界坐标中（`PSS_WORLD`).

使用 `PSS_WORLD` 适用于会留下尾迹的移动发射器（例如小行星或火箭）。

```ts
import { PBParticleSystem_SimulationSpace } from '@dcl/sdk/ecs'

ParticleSystem.create(emitter, {
	simulationSpace: PBParticleSystem_SimulationSpace.PSS_WORLD,
})
```

## 性能

引擎会为每个场景强制执行粒子预算；如果总粒子数可能超过上限，它会自动降低场景中所有活动粒子系统的发射速率。请相应地规划你的场景：

* 宁可使用更少但视觉冲击力更强的系统，也不要使用许多效果平平的系统。
* 使用 `最大粒子数` 用于限制单个系统的上限。
* 使用 `active` 或 `playbackState` 用于禁用屏幕外或超出范围的系统。
* 较短 `生命周期` 的值可使存活粒子数低于较高的发射 `速率` 率单独来看所暗示的数量。

引擎将任意时刻可渲染的最大粒子数上限设为 1000。如果你发射的粒子超过这个数量，可能无法看到全部粒子。

还要注意，粒子只有在玩家站在你的场景内时才能看到。从场景外观看场景的玩家，在踏入场景之前将看不到任何粒子。

## 粒子实验室

进入世界 [ParticleLab.dcl.eth](decentraland://?realm=particlelab.dcl.eth\&dclenv=org) 用于试验不同的粒子系统。当你靠近某个粒子系统时，UI 会显示所有可用字段，你可以实时调整它们，而无需重新加载场景。满意后，点击 **复制** 按钮，即可将该粒子系统的代码复制到剪贴板。

{% hint style="info" %}
**💡 提示**：若要查看一个会使用到每个 `ParticleSystem` 字段的可运行示例，请查看 [`0,7-particle-system`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/0,7-particle-system) 测试场景。它涵盖了全部四种发射器形状、 `PSB_ADD`/`PSB_ALPHA`/`PSB_MULTIPLY` 混合模式、 `PS_PLAYING`/`PS_PAUSED`/`PS_STOPPED` 播放状态、精灵表、持续 `速率` 与一次性和循环 `爆发`，以及 `PSS_LOCAL` 与 `PSS_WORLD` 在移动发射器上。
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/3d-nei-rong-ji-chu/particle-system.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.