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.

RULE: Transform.scale does NOT scale particles

Particle size is controlled exclusively by initialSize and sizeOverTime (FloatRange). The ParticleSystem also sets 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. Setting Transform.scale larger does not produce bigger particles.

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: Engine caps total particles at ~1000

The engine enforces a per-scene particle budget and will scale down emission rates across all active particle 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, 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'

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 (3D).
rotationOverTime	Quaternion	identity	Per-axis angular velocity (quaternion converted to Euler XYZ rad/s-equivalent).
faceTravelDirection	boolean	false	Orient along velocity. Overrides billboard.
initialColor	ColorRange	{white,white}	Random color at spawn.
colorOverTime	ColorRange	{white,white}	Color lerped start→end over lifetime. 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. Disable for 3D-oriented particles.
spriteSheet	{tilesX, tilesY, framesPerSecond?}	—	Texture-atlas frame animation. framesPerSecond defaults to 30.
shape	oneof Point/Sphere/Cone/Box	Point	Emitter geometry — see below.
loop	boolean	true	Loop the emission cycle. false = one-shot.
prewarm	boolean	false	Start as if one full loop has 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 (see Bursts).

FloatRange = { start: number, end: number } — random value sampled per particle. ColorRange = { start: Color4, end: Color4 } — random color sampled per particle (each end of the range is sampled independently of the other particle randoms).

Emitter shapes

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

shape: ParticleSystem.Shape.Point()
shape: ParticleSystem.Shape.Sphere({ radius: 1 }) // default 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 the entity origin.
• Sphere — random points inside a sphere of radius.
• Cone — emits from base disk, projecting outward within angle half-angle. Default 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 (e.g. point a cone downward for snow/rain), rotate the parent entity's Transform.rotation. Example: snow falling from a cone uses rotation: Quaternion.fromEulerDegrees(180, 0, 0) on the entity, or any orientation that flips the cone axis.

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

Anatomy of a ParticleSystem definition — attach to an entity that also has a Transform:

const emitter = engine.addEntity()
Transform.create(emitter, { position: Vector3.create(8, 1, 8) })
ParticleSystem.create(emitter, {
	rate: 20, // particles per second
	lifetime: 2, // seconds each particle lives
	maxParticles: 100,
	initialSize: { start: 0.1, end: 0.3 }, // FloatRange sampled per particle
	sizeOverTime: { start: 1.0, end: 0.0 }, // shrink to nothing over lifetime
	initialVelocitySpeed: { start: 1, end: 2 },
	colorOverTime: {
		// fade out via alpha = 0 at end
		start: Color4.create(1, 1, 1, 1),
		end: Color4.create(1, 1, 1, 0),
	},
	shape: ParticleSystem.Shape.Point(), // emitter geometry
})

For full production-ready configurations, see {baseDir}/references/particle-presets.md — 17 presets: Fire Ember, Magic Aura, Snowfall, Vortex Spiral, Gravity Fountain, Bat Swarm, Tumbling Leaves, Lightning Sparks, Heavy Rain, One-Shot Burst, Asteroid Trail, Purple Swirl, Bee Swarm, Fireworks Loop, Campfire, Flame Wisps, Moving Trail. The explosion/pickup VFX (Point/Cone + ADD fire, one-shot Sphere burst) all live there — e.g. Fire Ember (preset 1), the One-Shot Burst explosion (preset 10), and looping Fireworks Loop (preset 14).

Creator Hub editor integration

The Creator Hub inspector has a dedicated ParticleSystem panel (verified source: ParticleSystemInspector.tsx, multiEntity-capable, registered in EntityInspector.tsx). The recommended way to create and tune particle effects in Creator Hub scenes is:

1. Add a ParticleSystem component to an entity in the editor.
2. Tweak all fields live in the inspector panel -- no code, no scene reload.

Reserve code (ParticleSystem.create/getMutable in src/ or via a Script component) for dynamic runtime behavior only: toggling emitters from game logic, wiring play/stop to triggers/actions, or computing configs at runtime.

Programmatic / composite component name

• Component name: core::ParticleSystem (component id 1217).
• shape is a protobuf oneof, serialized as {"$case":"sphere","sphere":{"radius":1}}, {"$case":"cone","cone":{"angle":25,"radius":1}}, {"$case":"box","box":{"size":{"x":1,"y":1,"z":1}}}, or {"$case":"point","point":{}}.
• texture is a flat Texture (NOT TextureUnion), serialized as {"src":"assets/Images/spark.png"}. The $case/tex wrapper used by Material does not apply here.

Playback control

const ps = ParticleSystem.getMutable(entity)

// Pause emission and freeze existing particles
ps.playbackState = PBParticleSystem_PlaybackState.PS_PAUSED

// Resume
ps.playbackState = PBParticleSystem_PlaybackState.PS_PLAYING

// Stop and clear all live particles
ps.playbackState = PBParticleSystem_PlaybackState.PS_STOPPED

// Disable new emission (existing particles continue to live out their lifetime)
ps.active = false

Use playbackState = PS_STOPPED for a hard cut. Use active = false for a 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: 'assets/Images/flame-sheet.png' },
spriteSheet: { tilesX: 4, tilesY: 3, framesPerSecond: 12 }   // 12 frames, plays at 12fps

Test-scene examples use 4x4 (16 frames, bat swarm @24fps), 4x3 (12 frames, fire/flame @10–12fps), and 1x20 (20-frame strip, bee @30fps) sheets.

Simulation space (local vs world)

• PSS_LOCAL (default) — particles move with the emitter. A moving emitter drags its particle cloud along. Suits aura/halo effects on a moving entity.
• PSS_WORLD — particles stay at their spawn position in world space, so a moving emitter leaves a trail behind it.

For a Tween-driven emitter (verified in 0,7-particle-system, "Moving Trail"): PSS_LOCAL keeps the cloud attached to the entity as it moves; switch to PSS_WORLD if you want the spawned particles to stay put and form a persistent trail. The test scene demonstrates the effect with PSS_LOCAL — pick the space by the look you want, not as a hard requirement.

Texture field

The texture field uses the same Texture type as Material. Common case (local file):

texture: {
	src: 'assets/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

• Texture path — particle textures default to assets/Images/. Same path conventions as Material textures. Legacy scenes may have them under assets/scene/Images/ or assets/scene/textures/ (still works); textures from Creator Hub asset packs land in assets/asset-packs/ and custom items in assets/custom/ — reference those paths as-is.
• Quaternion rotation fields — rotationOverTime is interpreted as per-axis angular velocity (quaternion → Euler XYZ). 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 (particles never exceed speed). Lower values let velocity exceed cap briefly then decay.
• Color.alpha = 0 at end of colorOverTime is the standard way to fade particles out — don't rely on sizeOverTime ending at 0 alone.
• Bursts ignore active = false at the moment of evaluation — active is checked once per frame for continuous rate; setting it after a burst time will not retroactively cancel that burst.
• No mesh attached to the emitter entity — adding MeshRenderer is unrelated; particles render via the ParticleSystem component itself.

Performance

• 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.
• Sprite sheets are cheap; multiple textures per system is not supported (one texture per system).

Resources

• {baseDir}/references/particle-presets.md — 17 ready-to-use preset configurations from the SDK7 test scene (fire, magic, snowfall, vortex, fountain, swarms, sparks, rain, bursts, fireworks, campfire, trails).
• Live tuner: ParticleLab.dcl.eth (open with Decentraland client).

Example scenes

• https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/0,7-particle-system — engine-team ground truth: all 17 presets above, every shape (Point/Sphere/Cone/Box), PSB_ADD/PSB_ALPHA, continuous rate vs bursts (one-shot + looping fireworks), spriteSheet (4×4/4×3/1×20), limitVelocity, initialRotation/rotationOverTime with billboard: false, faceTravelDirection, additionalForce, and a Tween-driven emitter demonstrating simulationSpace.