Pixijs Scene Particle Container

ParticleContainer is a specialized container for rendering hundreds to tens of thousands of lightweight sprites in a single draw call. Use it for particle effects, bullet patterns, or any case where you need a large number of similar-looking objects with minimal per-object overhead. Particles share a single base texture and have a restricted transform set; they are not full Container children.

Assumes familiarity with pixijs-scene-core-concepts. ParticleContainer is a special leaf in a different sense: it contains Particle instances in its own particleChildren array and rejects normal PixiJS children. Use addParticle, not addChild, and wrap the whole ParticleContainer in a Container if you need to group it with other scene objects.

The Particle API is new in v8 but is stable for production use.

Quick Start

const texture = await Assets.load("particle.png");

const container = new ParticleContainer({
  texture,
  boundsArea: new Rectangle(0, 0, app.screen.width, app.screen.height),
  dynamicProperties: {
    position: true,
    rotation: false,
    color: false,
  },
});

for (let i = 0; i < 10000; i++) {
  container.addParticle(
    new Particle({
      texture,
      x: Math.random() * app.screen.width,
      y: Math.random() * app.screen.height,
    }),
  );
}

app.stage.addChild(container);

Related skills: pixijs-scene-core-concepts (scene graph basics), pixijs-scene-sprite (when you need full features per object), pixijs-assets (shared textures, atlases), pixijs-performance (batching, texture optimization), pixijs-scene-container (wrap with other display objects).

Constructor options

ParticleContainerOptions

All Container options (position, scale, tint, label, filters, zIndex, etc.) are also valid here — see skills/pixijs-scene-core-concepts/references/constructor-options.md. Note that children is omitted: use particles instead.

boundsArea is inherited from Container but is effectively required on ParticleContainer: the container returns empty bounds (0, 0, 0, 0) by default for performance, so without boundsArea it is culled as invisible when culling is active and containsPoint always misses.

ParticleOptions

Particle is a lightweight struct, not a Container subclass — none of the ContainerOptions fields apply. The full option list:

The constructor also accepts a bare Texture as its sole argument (new Particle(texture)), which is shorthand for new Particle({ texture }) using the defaults above.

Particle.defaultOptions is a static object you can reassign to change defaults globally; see the "Particle creation" section below.

Core Patterns

Particle creation

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

container.addParticle(particle);

Particle is a lightweight struct with flat numeric fields: x, y, scaleX, scaleY, anchorX, anchorY, rotation, color, texture. It also exposes tint (hex/CSS color) and alpha (0-1) as setters that combine into the internal color field. No transform hierarchy, no events, no filters.

You can pass a Texture directly as the sole argument: new Particle(texture).

Override Particle.defaultOptions to change defaults globally:

Particle.defaultOptions = {
  ...Particle.defaultOptions,
  anchorX: 0.5,
  anchorY: 0.5,
};

Pre-populating with the particles option

const particles = Array.from(
  { length: 10000 },
  () =>
    new Particle({
      texture,