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,
      x: Math.random() * 800,
      y: Math.random() * 600,
    }),
);

const container = new ParticleContainer({
  texture,
  boundsArea: new Rectangle(0, 0, 800, 600),
  particles,
});

Passing particles in the constructor is equivalent to creating the container empty and calling addParticle for each one, but avoids per-call view updates.

Dynamic vs static properties and update()

const container = new ParticleContainer({
  dynamicProperties: {
    rotation: true,
  },
});

dynamicProperties controls which particle attributes re-upload to the GPU every frame. The defaults on ParticleContainer.defaultOptions.dynamicProperties are:

{ vertex: false, position: true, rotation: false, uvs: false, color: false }

You only need to override the properties you are animating; the rest inherit the defaults (position dynamic, everything else static). Five properties in total:

• vertex: scale/anchor vertices
• position
• rotation
• uvs: texture coordinates (for frame-swapped particles)
• color: tint and alpha

Mark only what you animate; static properties are cheaper. If you change a static property at runtime, call container.update() to re-upload:

container.particleChildren.forEach((p) => {
  p.tint = 0x00ff00;
});
container.update();