Particle Container

PixiJS v8 includes a high-performance particle system via the ParticleContainer and Particle classes. Designed for rendering vast numbers of lightweight visuals (sparks, bubbles, explosions), this system provides raw speed by stripping away non-essential overhead.

Warning

The Particle API is stable but experimental. Its interface may evolve in future PixiJS versions. We welcome feedback to help guide its development.

import { ParticleContainer, Particle, Texture } from 'pixi.js';

const texture = Texture.from('bunny.png');

const container = new ParticleContainer({
  dynamicProperties: {
    position: true, // default
    vertex: false,
    rotation: false,
    color: false,
  },
});

for (let i = 0; i < 100000; i++) {
  const particle = new Particle({
    texture,
    x: Math.random() * 800,
    y: Math.random() * 600,
  });

  container.addParticle(particle);
}

app.stage.addChild(container);

Why use ParticleContainer?

Extreme performance: Render hundreds of thousands or millions of particles at high FPS.
Lightweight design: Particles are more efficient than Sprite, lacking children, events, or filters.
Fine-grained GPU uploads: You declare which properties change per frame (dynamic) vs which are set once (static). Only dynamic properties are uploaded to the GPU each frame, reducing bandwidth.

Performance tip: static vs dynamic

Dynamic properties are uploaded to the GPU every frame.
Static properties are uploaded only when update() is called.

Declare your needs explicitly:

const container = new ParticleContainer({
  dynamicProperties: {
    position: true,
    rotation: true,
    vertex: false,
    color: false,
  },
});

If you later modify a static property or the particle list, you must call:

container.update();

Limitations and API differences

ParticleContainer is designed for speed and simplicity. As such, it doesn't support the full Container API:

ParticleContainer uses a separate child management API optimized for GPU buffer updates:

Standard Container method	ParticleContainer equivalent
`addChild(child)`	`addParticle(particle)`
`removeChild(child)`	`removeParticle(particle)`
`addChildAt(child, index)`	`addParticleAt(particle, index)`
`removeChildAt(index)`	`removeParticleAt(index)`
`removeChildren(begin, end)`	`removeParticles(begin, end)`
`getChildAt(index)`	Access `container.particleChildren[index]` directly
`swapChildren()`	Not available
`reparentChild()`	Not available

Creating a particle

A Particle supports key display properties and is far more efficient than Sprite.

Particle example

const particle = new Particle({
  texture: Texture.from('spark.png'),
  x: 200,
  y: 100,
  scaleX: 0.8,
  scaleY: 0.8,
  rotation: Math.PI / 4,
  tint: 0xff0000,
  alpha: 0.5,
});

You can also use the shorthand:

const particle = new Particle(Texture.from('spark.png'));

Inherited properties

A ParticleContainer is a normal scene object, so alpha, tint, and blendMode set on it or on any ancestor apply to every particle it renders. Each particle's own alpha and tint multiply on top of that.

const group = new Container();
group.alpha = 0.5;
group.tint = 0xff0000;
group.addChild(particleContainer); // every particle renders at half alpha with a red tint

blendMode defaults to 'inherit', so the container takes the blend mode of its nearest ancestor that sets one. Set particleContainer.blendMode directly to override it. All particles in a container share one blend mode.