粒子系统

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

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

添加粒子系统

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

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 辅助函数获取四种形状。

点

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

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

Sphere

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

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

圆锥

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

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

Box

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

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

发射属性

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

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

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

运动

重力

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

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

初始速度

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

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

额外力

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

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

速度限制

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

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

视觉属性

颜色

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

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 等于原始纹理大小。

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

📔 注意： 缩放 实体的 Transform 不会影响粒子的缩放。

纹理

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

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

混合模式

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

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

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

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

广告牌

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

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

旋转

初始旋转和随时间旋转

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

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

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

📔 注意：如果 billboard 被设为 真，那么粒子将只会绕一个轴旋转，并始终保持朝向摄像机。

面向运动方向

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

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

📔 注意：如果 faceTravelDirection 为 true 时，值 billboard 将被忽略。

精灵表动画

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

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	停止发射并移除所有现有粒子。

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）用于模拟该系统仿佛从一开始就已运行，因此当玩家第一次看到它时，粒子就已经充满场景。

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

爆发式发射

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

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

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

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

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 适用于会留下尾迹的移动发射器（例如小行星或火箭）。

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

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

性能

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

• 宁可使用更少但视觉冲击力更强的系统，也不要使用许多效果平平的系统。

• 使用 最大粒子数 用于限制单个系统的上限。

• 使用 active 或 playbackState 用于禁用屏幕外或超出范围的系统。

• 较短 生命周期 的值可使存活粒子数低于较高的发射 速率 率单独来看所暗示的数量。

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

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

粒子实验室

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

💡 提示：若要查看一个会使用到每个 ParticleSystem 字段的可运行示例，请查看 0,7-particle-system 测试场景。它涵盖了全部四种发射器形状、 PSB_ADD/PSB_ALPHA/PSB_MULTIPLY 混合模式、 PS_PLAYING/PS_PAUSED/PS_STOPPED 播放状态、精灵表、持续 速率 与一次性和循环 爆发，以及 PSS_LOCAL 与 PSS_WORLD 在移动发射器上。