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();

Batch operations on particleChildren

// Bulk add
const batch = [];
for (let i = 0; i < 5000; i++) {
  batch.push(
    new Particle({ texture, x: Math.random() * 800, y: Math.random() * 600 }),
  );
}
container.particleChildren.push(...batch);
container.update();

// Bulk remove
container.particleChildren.length = 0;
container.update();

addParticle, addParticleAt, removeParticle, removeParticleAt, and removeParticles all trigger view updates per call. For large batch operations, direct array manipulation plus a single update() is faster.

Texture and shader options

texture in ParticleContainerOptions is optional. If omitted, the container falls back to the texture of the first particle added; every subsequent particle must share the same base texture source. Set it explicitly when you want to declare the atlas up front, or when the first particle might change mid-run:

const container = new ParticleContainer({ texture });

shader lets you replace the default particle shader with any Shader instance. The custom shader must declare the attributes the particle pipe uploads (aPosition, aUV, aColor, plus any dynamic-only attributes enabled via dynamicProperties). Use this for custom blending math, distance-field sprites, or non-standard effects:

const container = new ParticleContainer({ texture, shader: myCustomShader });

Limitations

ParticleContainer intentionally sacrifices features for speed:

• No filters, masks, or per-particle blend modes. Blend modes apply at the container level: set blendMode on the ParticleContainer or let it inherit from a parent Container (the default "inherit" resolves to the ancestor's blend mode, like Sprite and Mesh). The whole particle batch shares one blend mode.
• No nested children on particles.
• No automatic bounds calculation.
• All particles must share the same base texture source (atlases work; multiple unrelated textures do not).
• Custom shaders are supported via the shader option.

Container method migration

ParticleContainer uses a separate child management API optimized for GPU buffer updates. The standard Container child methods throw when called on a ParticleContainer.

Common Mistakes

[CRITICAL] Adding Sprites to ParticleContainer

Wrong:

const container = new ParticleContainer();
const sprite = new Sprite(texture);
container.addChild(sprite);

Correct:

const container = new ParticleContainer();
const particle = new Particle(texture);
container.addParticle(particle);

ParticleContainer does not accept Sprite children. addChild throws an error. Particles must be Particle instances (or any object implementing IParticle), added via addParticle. This is a complete rework from v7, where ParticleContainer accepted Sprite children.

[HIGH] Not setting boundsArea on ParticleContainer

Wrong:

const container = new ParticleContainer();
// bounds is always (0, 0, 0, 0) — culling and hit testing fail

Correct:

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

ParticleContainer returns empty bounds (0, 0, 0, 0) by default for performance. Without boundsArea, the container is culled as invisible when culling is active, and containsPoint always misses. Set boundsArea to the region your particles occupy.

[HIGH] Using children instead of particleChildren

Wrong:

container.addParticle(new Particle(texture));
console.log(container.children.length); // 0

Correct:

container.addParticle(new Particle(texture));
console.log(container.particleChildren.length); // 1

Particles are stored in the particleChildren array, not children. The standard Container.children array is empty on a ParticleContainer. All particle enumeration, counting, and manipulation must use particleChildren plus the *Particle methods.

[MEDIUM] Do not use ParticleContainer as a normal container

ParticleContainer contains particles, not display objects. If you need to group a particle system with a background sprite or UI overlay, wrap the ParticleContainer itself inside a plain Container:

const world = new Container();
world.addChild(backgroundSprite, particleContainer, uiLayer);

API Reference

• ParticleContainer
• ParticleContainerOptions
• Particle
• ParticleOptions
• IParticle
• ParticleProperties