用途:在 Decentraland SDK7 场景中从实体发射粒子,制作火焰、烟雾、火花、雪花、魔法、烟花等效果。每个实体只能挂一个 ParticleSystem 组件,需与 Transform 搭配;粒子由组件本身渲染,无需 Mesh。
主要能力:支持连续发射(rate)与爆发(bursts);四种发射器形状 Point、Sphere、Cone、Box;可设置生命周期、重力、附加力、初始尺寸/颜色/速度及随时间变化、贴图、混合模式(PSB_ALPHA/PSB_ADD/PSB_MULTIPLY)、billboard、精灵表帧动画、仿真空间(局部/世界)、限速、播放状态(播放/暂停/停止)等。
使用方式:发射器位置写在 main-entities.ts(Transform 及可选 GltfContainer),ParticleSystem 不属于声明式支持列表,需在 src/index.ts 运行时通过 engine.getEntityOrNullByName 获取实体后用 ParticleSystem.create 附加。形状用 ParticleSystem.Shape.* 辅助方法,不要手动拼 oneof。控制播放用 ParticleSystem.getMutable(entity) 修改 playbackState 或 active。
限制:Transform.scale 不缩放粒子,尺寸只由 initialSize/sizeOverTime 控制;粒子仅对场景地块内的玩家渲染;仅在 Unity 版探索器可用,移动 Godot 与 Bevy 探索器会忽略该组件,需准备降级方案;场景粒子总量约上限 1000,超出会降发射率;prewarm 仅在 loop 为 true 时生效;faceTravelDirection 会覆盖 billboard。建议用 maxParticles 限制每个系统,一个系统只用一张贴图。详细字段默认值、代码示例与测试场景见原文。