particle-system

用途

ParticleSystem 用于在 Decentraland SDK7 场景中从某个实体发射粒子，实现火焰、烟雾、雪花、烟花、魔法光效、拖尾等视觉效果。每个实体只能有一个 ParticleSystem 组件，需与 Transform 一同挂载；粒子由组件自身渲染，不需要 Mesh。

主要能力

连续发射：通过 rate 控制每秒发射粒子数。
爆发发射：通过 bursts 在指定时间点离散发射，可设置次数、间隔与概率。
发射器形状：Point（原点）、Sphere（球内随机）、Cone（锥形，angle 为半角）、Box（盒内随机）。
粒子外观：initialSize/sizeOverTime 控制大小，initialColor/colorOverTime 控制颜色与透明度，initialRotation/rotationOverTime 控制旋转，texture 指定精灵贴图，spriteSheet 支持图集帧动画。
运动控制：initialVelocitySpeed、gravity、additionalForce、limitVelocity、faceTravelDirection（沿速度方向，覆盖 billboard）。
模拟空间：PSS_LOCAL（随实体移动）或 PSS_WORLD（留在世界空间形成拖尾）。
播放控制：playbackState 可设为 PS_PLAYING、PS_PAUSED、PS_STOPPED；active 可关闭新粒子发射。
混合模式：PSB_ALPHA、PSB_ADD、PSB_MULTIPLY。

使用方式

导入：

import { engine, Transform, ParticleSystem } from '@dcl/sdk/ecs'
import {
	PBParticleSystem_BlendMode,
	PBParticleSystem_PlaybackState,
	PBParticleSystem_SimulationSpace,
} from '@dcl/sdk/ecs'
import { Color4, Vector3, Quaternion } from '@dcl/sdk/math'

创建示例：

const emitter = engine.addEntity()
Transform.create(emitter, { position: Vector3.create(8, 1, 8) })
ParticleSystem.create(emitter, {
	rate: 20,
	lifetime: 2,
	maxParticles: 100,
	initialSize: { start: 0.1, end: 0.3 },
	sizeOverTime: { start: 1.0, end: 0.0 },
	initialVelocitySpeed: { start: 1, end: 2 },
	colorOverTime: {
		start: Color4.create(1, 1, 1, 1),
		end: Color4.create(1, 1, 1, 0),
	},
	shape: ParticleSystem.Shape.Point(),
})

发射器形状使用 ParticleSystem.Shape.* 辅助方法构建：

shape: ParticleSystem.Shape.Point()
shape: ParticleSystem.Shape.Sphere({ radius: 1 })
shape: ParticleSystem.Shape.Cone({ angle: 25, radius: 1 })
shape: ParticleSystem.Shape.Box({ size: Vector3.create(1, 1, 1) })

爆发示例：

bursts: {
	values: [{ time: 0, count: 100, cycles: 1, interval: 0.01, probability: 1.0 }]
}

播放控制：

const ps = ParticleSystem.getMutable(entity)
ps.playbackState = PBParticleSystem_PlaybackState.PS_PAUSED
ps.playbackState = PBParticleSystem_PlaybackState.PS_PLAYING
ps.playbackState = PBParticleSystem_PlaybackState.PS_STOPPED
ps.active = false

精灵图集动画：

texture: { src: 'assets/Images/flame-sheet.png' },
spriteSheet: { tilesX: 4, tilesY: 3, framesPerSecond: 12 }

Creator Hub 编辑器集成：在检查器中为实体添加 ParticleSystem 组件后，可直接在面板中实时调节所有字段，无需代码或重载场景。代码仅用于动态运行时行为（如由游戏逻辑切换发射器、将播放/停止绑定到触发器）。

组件名称为 core::ParticleSystem（组件 id 1217）。shape 为 protobuf oneof，序列化形如 {"$case":"sphere","sphere":{"radius":1}}；texture 为扁平 Texture（非 TextureUnion），序列化形如 {"src":"assets/Images/spark.png"}。

适用场景

环境氛围：雪花、雨、篝火、烟雾。
特效：爆炸、拾取、魔法光环、闪电火花。
拖尾：移动实体留下的轨迹（配合 PSS_WORLD 或 faceTravelDirection）。
群集：蝙蝠群、蜜蜂群、落叶。
烟花：循环或单次爆发。

限制与注意事项

Transform.scale 不会缩放粒子；粒子大小仅由 initialSize 与 sizeOverTime 控制。
粒子仅对处于场景地块内的玩家渲染，地块外观看者看不到；粒子不属于场景 LOD 轮廓。
引擎对每场景总粒子数有约 1000 的上限，超出时会自动降低所有活跃系统的发射率；建议用 maxParticles 限制每个系统。
移动端限制（官方公布）：发射器软限 8、硬限 10；活跃粒子软限 25,000、硬限 50,000；运行时单发射器钳制 5,000、单场景 50,000，超出部分会被静默削减。建议目标为 ≤8 个发射器、每个 maxParticles 远低于 5,000。
prewarm 仅在 loop: true 时生效。
faceTravelDirection 为 true 时覆盖 billboard。
additionalForce 始终为世界空间，即使 simulationSpace 为 PSS_LOCAL。
limitVelocity.dampen = 1 为硬钳制。
建议在 colorOverTime 末尾将 alpha 设为 0 实现淡出。
bursts 在评估瞬间忽略 active = false。
发射器实体无需 MeshRenderer。
每个系统仅支持一个 texture。
纹理路径默认 assets/Images/，旧场景可能位于 assets/scene/Images/ 或 assets/scene/textures/，Creator Hub 资源包位于 assets/asset-packs/，自定义资源位于 assets/custom/。
头像/视频纹理用于粒子暂未验证。

资源

预设参考：{baseDir}/references/particle-presets.md，包含 17 个预设（火焰余烬、魔法光环、降雪、漩涡、重力喷泉、蝙蝠群、翻滚落叶、闪电火花、大雨、单次爆发、小行星拖尾、紫色漩涡、蜜蜂群、循环烟花、篝火、火焰精灵、移动拖尾）。
实时调参工具：ParticleLab.dcl.eth（使用 Decentraland 客户端打开）。
示例场景：https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/0,7-particle-system

技能介绍

用途

主要能力

使用方式

适用场景

限制与注意事项

资源