Particles

ParticleSystem is a Drawable that manages thousands of animated sprites with data-oriented performance. Instead of creating and destroying individual Sprite instances per particle, the system stores particle state in parallel typed arrays (Struct-of-Arrays) and mutates them in bulk. This keeps the work per-particle extremely lean — no allocations, no GC pressure, no per-sprite transform tree overhead.

Note: ParticleSystem ships as an official ExoJS extension package. Install @codexo/exojs-particles alongside @codexo/exojs:

npm install @codexo/exojs @codexo/exojs-particles

The mental model: you register modules that describe how particles spawn, what they do over their lifetime, and what happens when they die. The system calls those modules each frame against its channel storage. You never write a per-particle update loop.

Setup

Register the extension when creating your Application:

import { Application } from '@codexo/exojs';
import { particlesExtension } from '@codexo/exojs-particles';

const app = new Application({ extensions: [particlesExtension] });

Construction

A particle system needs a texture and a capacity:

import { Texture } from '@codexo/exojs';
import { ParticleSystem } from '@codexo/exojs-particles';

function createParticles(particleTexture: Texture): ParticleSystem {
    return new ParticleSystem(particleTexture, { capacity: 4000 });
}

capacity (default 4096) is the maximum number of particles the system can have alive at once. It’s fixed at construction — the backing typed arrays are allocated immediately.

The system is a Drawable, so it has a position, rotation, scale, tint, blend mode, and participates in the scene graph like any sprite:

import { BlendModes } from '@codexo/exojs';
import { ParticleSystem } from '@codexo/exojs-particles';

declare const system: ParticleSystem;

system.setPosition(400, 500);
system.setBlendMode(BlendModes.Additive);

Particle positions are local to the system — setting the system’s position moves the whole emitter.

Spawn modules

A spawn module creates new particles each frame. Two built-in spawners cover the common cases:

RateSpawn — continuous emission at a configurable rate (particles per second):

import { Vector } from '@codexo/exojs';
import { ConeDirection, Constant, RateSpawn, Range } from '@codexo/exojs-particles';

system.addSpawnModule(new RateSpawn({
    rate: new Constant(180),                            // 180 particles / second
    lifetime: new Range(0.6, 1.4),                      // random lifetime in seconds
    velocity: new ConeDirection(-Math.PI / 2, Math.PI / 5, 70, 180),
    scale: new Constant(new Vector(0.35, 0.35)),
}));

BurstSpawn — named bursts at scheduled times, with optional looping:

import { Vector } from '@codexo/exojs';
import { BurstSpawn, ConeDirection, Constant, Range } from '@codexo/exojs-particles';

const burst = new BurstSpawn({
    schedule: [{ time: 0, count: 100 }],  // 100 particles at t=0
    lifetime: new Range(0.5, 1.2),
    velocity: ConeDirection.omni(80, 240),  // full 360° spread
    scale: new Constant(new Vector(0.4, 0.4)),
});
system.addSpawnModule(burst);

// Re-trigger the burst schedule from t=0
burst.reset();

Every spawn config property that takes a value — lifetime, position, velocity, scale, rotation, rotationSpeed, tint, textureIndex — accepts a Distribution<T> rather than a fixed value. Distributions are sampled per-particle at spawn time.

Distributions

Distributions let each spawned particle get a different value. The most commonly used:

Curve and ColorGradient are LifetimeFunction<T> rather than Distribution<T> — they’re evaluated with a normalised lifetime t in 0..1, not sampled at spawn. They’re typically used with update modules, not spawn modules.

Update modules

Update modules mutate particle state each frame. Every built-in update module that works on both backends declares a wgsl() contribution — when a WebGPU backend is active and every registered update module is GPU-eligible, the system auto-compiles a composite WGSL compute shader and runs the full update pipeline on the GPU in a single dispatch. When any module lacks a wgsl() contribution, or when running on WebGL2, the system falls back to CPU. You don’t configure this — it’s automatic.

The frequently-used update modules:

import { Color } from '@codexo/exojs';
import {
    AlphaFadeOverLifetime,
    ApplyForce,
    ColorOverLifetime,
    ColorGradient,
    Curve,
    Drag,
    ScaleOverLifetime,
    Turbulence,
} from '@codexo/exojs-particles';

// Constant acceleration (gravity, wind)
system.addUpdateModule(new ApplyForce(0, 240));

// Speed-based drag
system.addUpdateModule(new Drag(0.1));

// Fade alpha over lifetime (requires a Curve)
system.addUpdateModule(new AlphaFadeOverLifetime(
    new Curve([{ t: 0, v: 1 }, { t: 1, v: 0 }])
));

// Full color interpolation over lifetime
system.addUpdateModule(new ColorOverLifetime(
    new ColorGradient([
        { t: 0, color: new Color(255, 200, 100, 1) },
        { t: 1, color: new Color(0, 0, 0, 0) },
    ])
));

// Animated scale
system.addUpdateModule(new ScaleOverLifetime(
    new Curve([{ t: 0, v: 0.5 }, { t: 0.3, v: 1.2 }, { t: 1, v: 0.1 }])
));

// Procedural noise-based motion
system.addUpdateModule(new Turbulence(30, 0.01));

Modules can be added and removed at any time, including while particles are in flight — the next update() rebuilds whatever the change invalidated. On the GPU path that is the compute program alone: the particles keep the state the device has been integrating, so live tuning does not restart the effect.

The one change that cannot preserve them is adding a module without a wgsl() implementation to a running GPU system. That moves the simulation to the CPU, which holds no copy of what the device computed, so the system clears its live particles rather than continuing from stale values.

Other available update modules: RotateOverLifetime, VelocityOverLifetime, AttractToPoint, RepelFromPoint, OrbitalForce, ColorOverSpeed. The API reference documents each one’s constructor options and GPU eligibility.

Death modules

A death module fires once per particle when its lifetime expires. The only built-in death module is SpawnOnDeath:

system.addDeathModule(
  new SpawnOnDeath(
    childSystem, // target ParticleSystem
    childBurst, // SpawnModule that spawns into childSystem
    3, // spawn childBurst.apply(...) this many times
  ),
);

SpawnOnDeath forwards the dying particle’s position to the child system’s spawn, so each child burst appears at the parent’s death location.

A custom death module receives that same information as a ParticleDeathContext — position, velocity, rotation, scale, colour and timing at the moment of death:

class SplashOnDeath extends DeathModule {
  private readonly ripples: ParticleSystem;

  constructor(ripples: ParticleSystem) {
    super();
    this.ripples = ripples;
  }

  override onDeath(_system: ParticleSystem, death: ParticleDeathContext): void {
    const ripple = this.ripples.emit();

    if (ripple) {
      ripple.position.set(death.x, death.y);
      ripple.velocity.set(death.velocityX * 0.25, death.velocityY * 0.25);
      ripple.lifetime = 0.6;
    }
  }
}

The context is a snapshot, not a view into the system: it is the same on both backends, stays valid for the whole callback, and carries no slot index because the slot may already hold a different particle by the time the callback runs. Delivery is exactly once per expired particle, but not necessarily in the frame it expired — a GPU-simulated death arrives with its readback, typically one frame later. Readbacks overlap, so frames that each report deaths do not queue behind one another; when the device falls far enough behind, deaths wait on the GPU and arrive with a later batch, still in the order they happened. Exactly-once holds while those waiting deaths fit the system’s capacity; past that the excess is dropped instead of stalling the frame, and a development build warns once per system.

Per-frame loop

ParticleSystem is a Drawable — it renders itself when you call context.render(system) in draw. Call system.update(delta) in your scene’s update:

class ParticleScene extends Scene {
  private system!: ParticleSystem;

  override update(delta: Seconds): void {
    this.system.update(delta);
  }

  override draw(context: RenderingContext): void {
    context.render(this.system);
  }
}

The update loop runs spawn modules, advances particle state (velocity integration, elapsed time), runs update modules, compacts dead particles, and — in GPU mode — uploads dirty slots and dispatches the compute shader. render() draws the system as a single instanced draw call, regardless of particle count.

Channels and manual emission

Particles are addressed by named channel, never by raw slot. A module receives the channels it needs and indexes them itself:

class Sway extends UpdateModule {
  override apply(particles: ParticleBatch, dt: number): void {
    const { x: velX } = particles.velocity;
    const { elapsed } = particles.timing;

    for (let i = 0; i < particles.count; i++) {
      velX[i] += Math.sin(elapsed[i] * 8) * 250 * dt;
    }
  }
}

The channels are position, velocity, scale (each .x / .y), rotation (.angle / .speed), timing (.elapsed / .lifetime), color (packed 0xAABBGGRR) and frame. Each is the simulation’s own storage, so writing moves the particle. Indices [0, particles.count) are the range worth visiting; particles.isAlive(i) skips the holes a GPU-mode system can leave behind.

To emit a particle yourself, ask the system for one:

import { ParticleSystem } from '@codexo/exojs-particles';

declare const system: ParticleSystem;

const particle = system.emit();

if (particle) {
    particle.position.set(120, 40);
    particle.velocity.set(0, -80);
    particle.lifetime = 2;
}

emit() returns null at capacity. Every field starts at its default — origin, no velocity, unit scale, no rotation, opaque white, frame 0, one second of life — so you write only what you vary. The returned writer is a cursor onto the emitted particle: the next emit() rebinds it, so fill it before emitting again.

system.clearParticles() resets the system to zero live particles, system.liveCount is the range that can hold them, system.aliveCount counts the live ones, and system.gpuMode reports whether the compute path is active.

GPU auto-routing

The decision is per-system and automatic. When:

1. A WebGpuBackend is active
2. Every registered update module implements wgsl()

…the system compiles a composite WGSL compute shader that integrates position, velocity, rotation, and every module’s dynamic behavior in one dispatch, writing directly into the renderer’s instance vertex buffer. No CPU readback in the steady state. The gpu-particles example demonstrates this at 60,000 particles.

If conditions aren’t met (WebGL2 backend, or any module without wgsl()), the system runs on CPU with the same API. Your scene code is identical — no branching, no backend checks.

Examples

import { Application, Color, FixedResolutionCanvasSizing, type RenderingContext, Scene } from '@codexo/exojs';
import { ApplyForce, ColorGradient, ColorOverLifetime, ConeDirection, Constant, Curve, particlesExtension, ParticleSystem, Range, RateSpawn, ScaleOverLifetime } from '@codexo/exojs-particles';
import { mountControls } from '@examples/runtime';

class EmitterBasicsScene extends Scene {
  private system!: ParticleSystem;
  private hud!: ReturnType<typeof mountControls>;

  override init(): void {
    const app = this.app;
    const { width, height } = app;

    this.system = new ParticleSystem(this.loader.get(assets.demo.textures.particleLight), { capacity: 4000 });
    this.systems.add(this.system);
    this.system.setPosition(width / 2, height - 80);

    // Rate, lifetime, and a cone-shaped velocity spread: a fountain that
    // shoots upward (-π/2) with a ±36° spread and 70-180 px/s speed.
    this.system.addSpawnModule(
      new RateSpawn({
        rate: new Constant(180),
        lifetime: new Range(0.6, 1.4),
        velocity: new ConeDirection(-Math.PI / 2, Math.PI / 5, 70, 180),
      }),
    );

    // Gravity pulls the fountain back down.
    this.system.addUpdateModule(new ApplyForce(0, 240));

    // Start/end size: each particle grows in fast, then shrinks to nothing
    // as it ages. ScaleOverLifetime sets the absolute scale every frame from
    // a curve sampled at elapsed / lifetime.
    this.system.addUpdateModule(
      new ScaleOverLifetime(
        new Curve([
          { t: 0, v: 0.15 },
          { t: 0.2, v: 0.55 },
          { t: 1, v: 0 },
        ]),
      ),
    );

    // Colour gradient over lifetime: white-hot core → orange → deep red, then
    // fading to transparent so particles dissolve at the end of their life.
    this.system.addUpdateModule(
      new ColorOverLifetime(
        new ColorGradient([
          { t: 0, color: new Color(255, 244, 200, 1) },
          { t: 0.35, color: new Color(255, 168, 64, 1) },
          { t: 0.75, color: new Color(220, 60, 40, 0.8) },
          { t: 1, color: new Color(120, 20, 20, 0) },
        ]),
      ),
    );

    this.hud = mountControls({
      title: 'Emitter Basics',
      controls: [{ keys: 'Auto', action: 'continuous fountain emission' }],
      status: 'Rate 180/s · lifetime 0.6–1.4s · gravity',
      hint: 'RateSpawn drives emission; ScaleOverLifetime sizes and ColorOverLifetime tints each particle as it ages.',
    });
  }

  override draw(context: RenderingContext): void {
    context.render(this.system);
  }
}

const app = new Application({
  scenes: { EmitterBasicsScene },
  canvas: {
    width: 1280,
    height: 720,
    mount: document.body,
    sizing: new FixedResolutionCanvasSizing(),
  },
  clearColor: Color.black,
  extensions: [particlesExtension],
});

await app.start(EmitterBasicsScene);

A single upward emitter with gravity and fade — RateSpawn + ApplyForce + AlphaFadeOverLifetime.

import { Application, BlendModes, Color, FixedResolutionCanvasSizing, type RenderingContext, Scene } from '@codexo/exojs';
import { ColorGradient, ColorOverLifetime, ConeDirection, Constant, particlesExtension, ParticleSystem, Range, RateSpawn, VectorRange } from '@codexo/exojs-particles';

class BonfireScene extends Scene {
  private fireSystem!: ParticleSystem;
  private smokeSystem!: ParticleSystem;

  override init(): void {
    const app = this.app;
    const { width, height } = app;

    this.fireSystem = new ParticleSystem(this.loader.get(assets.demo.textures.particleFlame));
    this.systems.add(this.fireSystem);
    this.fireSystem.setPosition(width * 0.5, height * 0.75);
    this.fireSystem.setBlendMode(BlendModes.Additive);

    this.fireSystem.addSpawnModule(
      new RateSpawn({
        rate: new Constant(50),
        lifetime: new Range(5, 10),
        position: new VectorRange(-50, 50, -10, 10),
        velocity: new ConeDirection(-Math.PI / 2, Math.PI / 36, 60, 80),
      }),
    );

    this.fireSystem.addUpdateModule(
      new ColorOverLifetime(
        new ColorGradient([
          { t: 0, color: new Color(194, 64, 30, 1) },
          { t: 1, color: new Color(0, 0, 0, 0) },
        ]),
      ),
    );

    this.smokeSystem = new ParticleSystem(this.loader.get(assets.demo.textures.particleSmoke));
    this.systems.add(this.smokeSystem);
    this.smokeSystem.setPosition(width * 0.5, height * 0.75 - 40);
    this.smokeSystem.setBlendMode(BlendModes.Normal);

    this.smokeSystem.addSpawnModule(
      new RateSpawn({
        rate: new Constant(8),
        lifetime: new Range(8, 14),
        position: new VectorRange(-30, 30, -5, 5),
        velocity: new ConeDirection(-Math.PI / 2, Math.PI / 12, 20, 35),
      }),
    );

    this.smokeSystem.addUpdateModule(
      new ColorOverLifetime(
        new ColorGradient([
          { t: 0, color: new Color(120, 100, 80, 0.4) },
          { t: 1, color: new Color(60, 55, 50, 0) },
        ]),
      ),
    );
  }

  override draw(context: RenderingContext): void {
    context.render(this.smokeSystem);
    context.render(this.fireSystem);
  }
}

const app = new Application({
  scenes: { BonfireScene },
  canvas: {
    width: 1280,
    height: 720,
    mount: document.body,
    sizing: new FixedResolutionCanvasSizing(),
  },
  clearColor: Color.black,
  extensions: [particlesExtension],
});

await app.start(BonfireScene);

A bonfire effect with additive blending — RateSpawn with random position and upward velocity, plus ColorOverLifetime from ember-orange to transparent black.

Where to go next

The next chapter, Post-processing, covers scene-wide multi-pass rendering — how to combine RenderTexture targets with filter chains for bloom, trails, and composited color grading.