Textures & animation

Load images or sprite sheets with PixiJS, then choose which texture each emitter uses.

Load a texture

Load your image with Assets.load() before creating the effect. Pass the texture under the emitter’s ID: sparks below matches id: 'sparks' in the effect definition.

import { Assets, type Texture } from 'pixi.js';
import { ParticleEffect } from '@reparticle/pixi';

const spark = await Assets.load<Texture>('/textures/spark.png');

const effect = new ParticleEffect({
  version: 1,
  emitters: [{
    id: 'sparks', // Emitter ID.
    capacity: 2048,
    seed: 42,
    emission: { rate: 120, shape: { type: 'point' } },
    initial: { lifetime: 2, speed: 90, direction: 0, spread: Math.PI * 2, size: 12 },
  }],
}, {
  ticker: app.ticker,
  emitters: {
    sparks: { textures: [spark] }, // Must match the emitter ID above.
  },
});

effect.position.set(app.screen.width / 2, app.screen.height / 2);
app.stage.addChild(effect);

The artwork key sparks must match the emitter’s id exactly. The texture variable spark and filename spark.png can have any name.

This uses your existing PixiJS app. For multiple emitters, add an entry for each ID under emitters. An emitter without a supplied texture draws soft procedural particles.

Missing or invalid textures use a placeholder and log a warning. Load assets before assigning them.

Load a sprite sheet

A sprite sheet packs several images into one PNG. Its JSON file tells PixiJS where each image is.

For example, put these exported files in your textures folder:

textures/
  particles.png
  particles.json

Load particles.json. PixiJS also loads particles.png, as long as that is the image referenced in the JSON. Then choose a frame and give it to your emitter:

import { Assets } from 'pixi.js';

await Assets.load('/textures/particles.json');

effect.setEmitterTexture('sparks', {
  textures: ['star.png'],
});

star.png is the name of an image inside the sheet, not a separate file to load. PixiJS caches these names when the sheet loads. A frame named star can be passed as textures: ['star']. Replace it with one of the names listed under frames in your JSON.

sparks selects the emitter from the previous example. This gives all its particles the star texture; it does not animate them.

Animate particles

After loading the sprite sheet, list its frame names in playback order. Use at least two frames from the same sheet image:

effect.setEmitterTexture('sparks', {
  textures: [
    'fire-01.png',
    'fire-02.png',
    'fire-03.png',
  ],
  playback: 'loop-forward',
  fps: 12,
});

You can also pass these same options under emitters.sparks when creating ParticleEffect. Use loop-forward to repeat at the chosen FPS, or once-forward to play once over each particle’s lifetime.

Artwork options

Clean up

Destroy the effect when removing it from your scene. Loaded textures remain available for other effects. Unload an asset only when nothing else uses it:

effect.destroy();

// Only when these assets are no longer used by your scene:
await Assets.unload('/textures/spark.png');
await Assets.unload('/textures/particles.json');