Particle Systems

A particle system emits copies of a sprite with randomized, physically-simulated motion — sparks, embers, dust, rain, snow. The simulation is seeded and deterministic: the same definition always produces the same frames, so a particle effect can be baked to a fixed frame-set and shipped like any other animation.

Basic Syntax

{
  type: "particle",
  name: "embers",
  sprite: "ember",        // the sprite emitted as each particle
  emitter: {
    rate: 1.5,            // particles spawned per frame (fractional accumulates)
    lifetime: [6, 10],    // frames each particle lives, [min, max]
    velocity: { x: [-0.4, 0.4], y: [-1.2, -0.6] },  // initial velocity range
    gravity: -0.02,       // per-frame acceleration on vy (negative = rises)
    fade: true,           // fade alpha to zero over the particle's lifetime
    rotation: [0, 0],     // rotation range in degrees (optional)
    seed: 7,              // RNG seed — fix it for reproducible bakes
  },
}

Fields

FieldRequiredDescription
typeYesMust be "particle"
nameYesUnique identifier (and the base name of the baked frame-set)
spriteYesName of the sprite to emit as each particle
emitterYesEmitter configuration (below)

Emitter

FieldDefaultDescription
rate1.0Particles emitted per frame; fractional rates accumulate across frames
lifetime[10, 20]Per-particle lifetime in frames, [min, max]
velocitynoneInitial velocity range { x: [min, max], y: [min, max] }
gravity0Acceleration added to vy each frame (negative rises, positive falls)
fadefalseIf true, alpha fades linearly to zero over the lifetime
rotation[0, 0]Rotation range in degrees
seed42RNG seed — set this so bakes are reproducible

Baking to Frames

Particle systems are runtime constructs, so pxl render does not draw them statically by default. Pass --frames N to simulate the emitter and bake N frames:

# A numbered PNG per frame: embers_00.png … embers_11.png
pxl render embers.pxl --frames 12 --canvas 16x32 --origin 8,31 -o frames/

# A single animated GIF instead
pxl render embers.pxl --frames 12 --canvas 16x32 --gif --fps 12 -o embers.gif
FlagDefaultDescription
--frames N—Bake N frames (required to render a particle system)
--canvas WxH32x32Output canvas size
--origin X,Ybottom-centerEmitter origin on the canvas
--gifoffEmit one animated GIF instead of numbered PNGs
--fps N10GIF playback rate
--sprite NAMEallBake only the named particle system

The PNG output follows the frame-set naming convention {name}_NN.png, so a baked particle drops straight into an animation frames array or any pipeline that consumes numbered frames. Because the simulation is seeded, re-baking the same file reproduces byte-identical frames — safe to commit and diff.

Tip: the emitted sprite is a normal sprite, so it can itself use extends, transforms, or any palette.