particle-system

ParticleSystem (SDK7)

Emit particles from an entity. One ParticleSystem component per entity, attached alongside a Transform. No mesh required — particles render from the component itself.

Authoring split

The emitter position (entity Transform + optional GltfContainer of a torch/fire pit/fog vent) is static and belongs in main-entities.ts. ParticleSystem itself is not in the supported declarative list — attach it at runtime in src/index.ts via getEntityOrNullByName.

// main-entities.ts — emitter placement
campfire: {
  components: {
    Transform: { position: { x: 8, y: 0, z: 8 } },
    GltfContainer: { src: 'models/campfire.glb' }
  }
}

// src/index.ts — attach ParticleSystem
import { engine, ParticleSystem, PBParticleSystem_BlendMode } from '@dcl/sdk/ecs'
import { Color4 } from '@dcl/sdk/math'

export function main() {
  const fire = engine.getEntityOrNullByName('campfire')
  if (!fire) return
  ParticleSystem.create(fire, { /* ... config ... */ })
}

RULE: Transform.scale does NOT scale particles

Particle size is controlled exclusively by initialSize and sizeOverTime (FloatRange). The ParticleSystem also sets the emitter shape's spatial dimensions when the shape has size fields (Sphere radius, Box size, Cone radius). These are not affected by the entity's Transform.scale.

RULE: Particles only render to players inside scene parcels

Players viewing the scene from outside its parcels see nothing. Particles are not part of the scene LOD silhouette. Position emitters within parcel bounds.

RULE: Particles only work in the Unity explorer

The mobile Godot explorer and the Bevy explorer don't have this feature implemented. The renderer ignores the component. Design fallbacks (a glowing emissive sphere, a baked-in GLTF animation) for scenes that should look reasonable everywhere.

RULE: Engine caps total particles at ~1000

The engine enforces a per-scene particle budget and will scale down emission rates across all active systems if total live particles would exceed the limit. Cap each system with maxParticles and prefer fewer impactful systems over many small ones.

RULE: prewarm requires loop = true

prewarm: true only takes effect when loop: true. On a one-shot system (loop: false) prewarm is silently ignored.

RULE: faceTravelDirection overrides billboard

When faceTravelDirection: true, particles orient along their velocity vector and billboard is ignored. Use this for trails/streaks (asteroids, bullets, sparks). Set billboard: false explicitly to avoid confusion.

Import

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

Aliases ParticleSystemBlendMode and ParticleSystemPlaybackState are also exported from @dcl/sdk/ecs and are interchangeable with the PB-prefixed names. There is no ParticleSystemSimulationSpace alias — only PBParticleSystem_SimulationSpace. Prefer the PB-prefixed names everywhere for consistency.

Field reference

Field	Type	Default	Notes
`active`	`boolean`	`true`	Master on/off for new emission.
`rate`	`number`	`10`	Particles emitted per second (continuous). Set to `0` when using `bursts`.
`maxParticles`	`number`	`1000`	Hard cap on simultaneous live particles for this system.
`lifetime`	`number`	`5`	Particle lifespan in seconds.
`gravity`	`number`	`0`	Multiplier on scene gravity (~ -9.81 m/s²). Negative = particles rise.
`additionalForce`	`Vector3`	—	Constant force vector applied each frame (world space).
`initialSize`	`FloatRange`	`{start:1, end:1}`	Random size at spawn.
`sizeOverTime`	`FloatRange`	`{start:1, end:1}`	Size lerped start→end over particle lifetime.
`initialRotation`	`Quaternion`	identity	Spawn orientation.
`rotationOverTime`	`Quaternion`	identity	Per-axis angular velocity.
`faceTravelDirection`	`boolean`	`false`	Orient along velocity. Overrides `billboard`.
`initialColor`	`ColorRange`	`{white,white}`	Random color at spawn.
`colorOverTime`	`ColorRange`	`{white,white}`	Color lerped start→end. Use alpha=0 at end to fade out.
`initialVelocitySpeed`	`FloatRange`	`{start:1, end:1}`	Initial speed in m/s, randomized per particle.
`texture`	`Texture`	white quad	Particle sprite. Same `Texture` shape as Material textures.
`blendMode`	`PBParticleSystem_BlendMode`	`PSB_ALPHA`	`PSB_ALPHA` / `PSB_ADD` / `PSB_MULTIPLY`.
`billboard`	`boolean`	`true`	Particles always face camera.
`spriteSheet`	`{tilesX, tilesY, framesPerSecond?}`	—	Texture-atlas frame animation.
`shape`	oneof Point/Sphere/Cone/Box	Point	Emitter geometry.
`loop`	`boolean`	`true`	Loop emission cycle. `false` = one-shot.
`prewarm`	`boolean`	`false`	Start as if one full loop already simulated. Requires `loop: true`.
`simulationSpace`	`PBParticleSystem_SimulationSpace`	`PSS_LOCAL`	`PSS_LOCAL` (move with entity) / `PSS_WORLD` (stay put after spawn).
`limitVelocity`	`{speed, dampen?}`	—	Clamp top speed. `dampen` 0–1, default `1` = hard clamp.
`playbackState`	`PBParticleSystem_PlaybackState`	`PS_PLAYING`	`PS_PLAYING` / `PS_PAUSED` / `PS_STOPPED`.
`bursts`	`{values: Burst[]}`	—	Discrete emission events.

FloatRange = { start: number, end: number }. ColorRange = { start: Color4, end: Color4 }.

Emitter shapes

Use ParticleSystem.Shape.* helpers — never assemble the oneof manually:

shape: ParticleSystem.Shape.Point()
shape: ParticleSystem.Shape.Sphere({ radius: 1 })
shape: ParticleSystem.Shape.Cone({ angle: 25, radius: 1 })  // angle = half-angle in degrees
shape: ParticleSystem.Shape.Box({ size: Vector3.create(1, 1, 1) })

Point — emits from entity origin.
Sphere — random points inside a sphere of radius.
Cone — base disk projecting outward within angle half-angle. Cone direction is the entity's local forward; rotate the parent Transform to aim it.
Box — random points inside an axis-aligned box of size.

To rotate the emission direction (snow falling, rain), rotate the parent entity's Transform.rotation (in main-entities.ts).

Bursts

Discrete emission events at specific times. Set rate: 0 to use bursts only, or combine with rate > 0 for continuous + bursty.

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

Burst fields: time (s from cycle start), count (particles per burst), cycles (default 1, 0 = infinite), interval (s between cycles, default 0.01), probability (0–1 chance per cycle, default 1). Multiple bursts in one cycle = staggered ignition pattern (fireworks).

Common patterns

// 1. Fire ember — Point + ADD blend, slight upward drift
const fire = engine.getEntityOrNullByName('campfire')
if (fire) ParticleSystem.create(fire, {
  rate: 40,
  lifetime: 2,
  maxParticles: 200,
  initialSize: { start: 0.1, end: 0.3 },
  sizeOverTime: { start: 1.0, end: 0.0 },
  initialColor: { start: Color4.create(1, 0.6, 0.1, 1), end: Color4.create(1, 0.2, 0, 1) },
  colorOverTime: { start: Color4.create(1, 0.5, 0.1, 1), end: Color4.create(0.2, 0, 0, 0) },
  initialVelocitySpeed: { start: 1.5, end: 2.5 },
  gravity: -0.3,
  blendMode: PBParticleSystem_BlendMode.PSB_ADD,
  shape: ParticleSystem.Shape.Point()
})

// 2. One-shot burst — explosion/pickup VFX
ParticleSystem.create(entity, {
  loop: false,
  rate: 0,
  lifetime: 3,
  maxParticles: 150,
  initialSize: { start: 0.1, end: 0.25 },
  sizeOverTime: { start: 1.0, end: 0.0 },
  initialVelocitySpeed: { start: 2, end: 4 },
  shape: ParticleSystem.Shape.Sphere({ radius: 0.5 }),
  bursts: {
    values: [{ time: 0, count: 100, cycles: 1, interval: 0.01, probability: 1.0 }]
  }
})

Playback control

const ps = ParticleSystem.getMutable(entity)
ps.playbackState = PBParticleSystem_PlaybackState.PS_PAUSED   // pause + freeze particles
ps.playbackState = PBParticleSystem_PlaybackState.PS_PLAYING  // resume
ps.playbackState = PBParticleSystem_PlaybackState.PS_STOPPED  // hard cut, clear live particles
ps.active = false                                              // graceful trail-off

Sprite-sheet animation

Texture atlas with frames laid out in a grid (left-to-right, top-to-bottom). Total frames = tilesX * tilesY.

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

Simulation space (local vs world)

PSS_LOCAL (default) — particles move with the emitter. A moving emitter drags its particle cloud. Good for auras / halos on moving entities.
PSS_WORLD — particles stay at their spawn position in world space. A moving emitter leaves a trail. Required for proper trails combined with Tween movement on the emitter.

Texture field

texture: { src: 'images/spark.png' }

The full Texture form supports filterMode/wrapMode but particle systems generally only need src. Avatar/Video textures on particles are unverified — stick with file textures.

Gotchas

rotationOverTime is interpreted as per-axis angular velocity. Quaternion.fromEulerDegrees(0, 90, 0) = spin 90°/s on Y. Identity = no spin.
additionalForce is world-space even when simulationSpace = PSS_LOCAL. Wind/drift directions stay constant regardless of emitter rotation.
limitVelocity.dampen = 1 = hard clamp. Lower values let velocity exceed cap briefly then decay.
Color alpha = 0 at end of colorOverTime is the standard way to fade particles out.
No mesh attached to the emitter entity — adding MeshRenderer is unrelated; particles render from the ParticleSystem component itself.

Performance

Cap each system with maxParticles. Total scene budget across all systems is ~1000.
Keep lifetime * rate low; that product is the steady-state live count.
Disable systems out of view via playbackState = PS_STOPPED or active = false.
Prefer PSB_ALPHA for opaque/translucent effects. PSB_ADD is best for glow/fire (it stacks visually) but multi-layer additive overdraw is the most expensive case.
One texture per system.

Resources

Test scene: https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/0%2C7-particle-system
Live tuner: ParticleLab.dcl.eth (open with Decentraland client).