Working with effects
Effect configuration
Control how particles appear, move, and change over time. Explore each setting and try it in the lab.
Download a complete effect JSON example.
Most settings apply to a single emitter. Settings marked effect. apply to the whole effect. Optional settings use the defaults shown below.
Texture assets and animation playback belong to @reparticle/pixi artwork options, not this configuration.
Modifiers change particle movement. They run in the order you list them: the emitter’s modifiers first, then the effect’s shared modifiers. You can use the same modifier more than once.
Emitter
| Setting | Description | Default | Required | Value |
|---|---|---|---|---|
id↗ | Unique emitter identifier within this effect. Use it to look up the emitter and bind its artwork. Renaming it does not change motion. | — | Yes | — |
capacity↗ | Maximum simultaneous particles for this emitter. When all slots are occupied, excess births are dropped and living particles are preserved. Try 64 to see the stream run out of free slots. | — | Yes | 1 to 1,000,000 |
seed↗ | Deterministic random seed. The same definition and playback steps reproduce the same variation. Changing the seed changes the pattern, not the configured ranges. | — | Yes | 0 to 65,535 |
Playback
| Setting | Description | Default | Required | Value |
|---|---|---|---|---|
playMode↗ | Loop repeats the emission cycle. Once runs a single cycle, then lets surviving particles finish. Restart to replay a one-shot effect. | loop | No | once loop |
duration↗ | Length of the emission cycle. Emitter-lifetime curves use this interval. The experiment emits once so the end of the cycle is visible. | 1 | No | 0 or more |
durationSpread↗ | Random variation around the authored duration. Restart to observe playback; the seed keeps variation reproducible. | 0 | No | 0 or more |
startDelay↗ | Wait before emission begins. No particles are born during the delay. Restart the preview to watch it from the beginning. | 0 | No | 0 or more |
startDelaySpread↗ | Random variation around the start delay. Used when initializing playback; it does not add a pause between every loop. | 0 | No | 0 or more |
startOffset↗ | Prewarm the effect by advancing simulation before displaying its first frame. This performs real simulation work in fixed 1/60-second steps. Compare zero with two seconds. | 0 | No | 0 or more |
Transform
| Setting | Description | Default | Required | Value |
|---|---|---|---|---|
position.x↗ | Emitter position relative to the effect origin. Positive X moves right. This is independent of the ParticleEffect display-object position. | 0 | No | — |
position.y↗ | Emitter position relative to the effect origin. Positive Y moves down in Pixi canvas coordinates. | 0 | No | — |
rotation↗ | Rotate the emitter and its emission direction. Positive authored angles turn counterclockwise. Pixi display-object rotation uses radians instead. | 0 | No | — |
scale↗ | Uniform emitter scale, affecting emission geometry, particle size, and motion. Compare 0.5, 1, and 2. | 1 | No | — |
space↗ | World particles stay behind when the effect moves. Local particles follow its transform. The experiment moves the whole effect so the difference is visible. | world | No | world local |
inheritVelocity↗ | Amount of emitter movement velocity added to newborn particles. Zero adds none; one inherits the full measured velocity. Existing particles keep their own motion. | 0 | No | — |
Appearance
| Setting | Description | Default | Required | Value |
|---|---|---|---|---|
orientation↗ | Choose fixed rotation, alignment with the initial direction, alignment with current movement, or integrated angular velocity. The rectangular artwork makes the orientation visible. | default | No | default initial-direction movement-direction angular-velocity |
stretchWithVelocity↗ | Scale Y stretch by particle speed, using a fixed 60 FPS shutter factor. It needs nonzero stretchY; it does not stretch particles by itself. | false | No | — |
Emission
| Setting | Description | Default | Required | Value |
|---|---|---|---|---|
rate↗ | Particles requested per second. Can be a constant or a curve over normalized emitter lifetime. Capacity still limits the number alive. | — | Yes | — |
rateSpread↗ | Random variation around the emission rate, sampled for playback. This changes birth frequency rather than particle speed. | 0 | No | 0 or more |
shape↗ | Spawn from a point, a filled circle, a box, or a 2D cone. Each shape has its own valid fields. Change the JSON type and dimensions together. | — | Yes | — |
shape.type↗ | Select the shape. Point has no dimensions; circle uses diameter; box and cone2d use width and height. The preview supplies dimensions for the selected shape. | — | Yes | point circle box cone2d |
shape.diameter↗ | Circle diameter, not radius. Births sample its filled area. A curve changes the diameter over the emitter cycle. | — | Yesfor circle | — |
shape.diameterSpread↗ | Variation around the circle diameter. It varies the sampled emitter dimension, rather than moving the whole effect. | 0 | No | 0 or more |
shape.width↗ | Box or cone width. Constants and curves over emitter lifetime are supported. This experiment uses a box. | — | Yesfor box / cone2d | — |
shape.widthSpread↗ | Random variation around the authored width. The nominal dimension stays unchanged. | 0 | No | 0 or more |
shape.height↗ | Box or cone height. Constants and curves over emitter lifetime are supported. This experiment uses a box. | — | Yesfor box / cone2d | — |
shape.heightSpread↗ | Random variation around the authored height. The nominal dimension stays unchanged. | 0 | No | 0 or more |
Initial properties
| Setting | Description | Default | Required | Value |
|---|---|---|---|---|
direction↗ | Base direction for point emission. Zero points right; -π/2 points up. Positive angles turn clockwise in canvas coordinates. Other shapes define their own spawn directions. | — | Yes | — |
spread↗ | Full angular width around the point-emitter direction. Zero produces a straight stream; 2π distributes directions all around. | — | Yes | 0 or more |
lifetime↗ | Seconds each particle remains alive. Longer lifetimes require more capacity at the same emission rate. Accepts a number or a curve sampled at birth using normalized emitter lifetime. | — | Yes | — |
lifetimeSpread↗ | Per-particle variation added to initial.lifetime: base + a deterministic value between -1 and 1 × spread. Zero gives every particle the same base value. | 0 | No | 0 or more |
speed↗ | Initial velocity magnitude. Changing it affects new particles; modifiers change velocity afterward. Accepts a number or a curve sampled at birth using normalized emitter lifetime. | — | Yes | — |
speedSpread↗ | Per-particle variation added to initial.speed: base + a deterministic value between -1 and 1 × spread. Zero gives every particle the same base value. | 0 | No | 0 or more |
size↗ | Particle size in manual texture sizing mode. Initial size is multiplied by overLifetime.scale. Accepts a number or a curve sampled at birth using normalized emitter lifetime. | 24 | No | — |
sizeSpread↗ | Per-particle variation added to initial.size: base + a deterministic value between -1 and 1 × spread. Zero gives every particle the same base value. | 0 | No | 0 or more |
rotation↗ | Initial particle rotation. Positive angles turn counterclockwise. It is added to orientation and lifetime rotation. Accepts a number or a curve sampled at birth using normalized emitter lifetime. | 0 | No | — |
rotationSpread↗ | Per-particle variation added to initial.rotation: base + a deterministic value between -1 and 1 × spread. Zero gives every particle the same base value. | 0 | No | 0 or more |
angularVelocity↗ | Spin speed used by angular-velocity orientation. Integrated over simulation time. Accepts a number or a curve sampled at birth using normalized emitter lifetime. | 0 | No | — |
angularVelocitySpread↗ | Per-particle variation added to initial.angularVelocity: base + a deterministic value between -1 and 1 × spread. Zero gives every particle the same base value. | 0 | No | 0 or more |
stretchX↗ | Extra horizontal stretch. Zero keeps original width; one adds another full width. Accepts a number or a curve sampled at birth using normalized emitter lifetime. | 0 | No | — |
stretchXSpread↗ | Per-particle variation added to initial.stretchX: base + a deterministic value between -1 and 1 × spread. Zero gives every particle the same base value. | 0 | No | 0 or more |
stretchY↗ | Extra vertical stretch. Zero keeps original height; one doubles it. Accepts a number or a curve sampled at birth using normalized emitter lifetime. | 0 | No | — |
stretchYSpread↗ | Per-particle variation added to initial.stretchY: base + a deterministic value between -1 and 1 × spread. Zero gives every particle the same base value. | 0 | No | 0 or more |
red↗ | Initial red channel, multiplied by lifetime red and rendering tint. Accepts a number or a curve sampled at birth using normalized emitter lifetime. | 1 | No | — |
redSpread↗ | Per-particle variation added to initial.red: base + a deterministic value between -1 and 1 × spread. Zero gives every particle the same base value. | 0 | No | 0 or more |
green↗ | Initial green channel, multiplied by lifetime green and rendering tint. Accepts a number or a curve sampled at birth using normalized emitter lifetime. | 1 | No | — |
greenSpread↗ | Per-particle variation added to initial.green: base + a deterministic value between -1 and 1 × spread. Zero gives every particle the same base value. | 0 | No | 0 or more |
blue↗ | Initial blue channel, multiplied by lifetime blue and rendering tint. Accepts a number or a curve sampled at birth using normalized emitter lifetime. | 1 | No | — |
blueSpread↗ | Per-particle variation added to initial.blue: base + a deterministic value between -1 and 1 × spread. Zero gives every particle the same base value. | 0 | No | 0 or more |
alpha↗ | Initial opacity, multiplied by lifetime alpha, emitter tint, and display-object alpha. Accepts a number or a curve sampled at birth using normalized emitter lifetime. | 1 | No | — |
alphaSpread↗ | Per-particle variation added to initial.alpha: base + a deterministic value between -1 and 1 × spread. Zero gives every particle the same base value. | 0 | No | 0 or more |
Rendering
| Setting | Description | Default | Required | Value |
|---|---|---|---|---|
blendMode↗ | How particle pixels combine with the scene: normal alpha blending, additive light, multiply, or screen. These map directly to Pixi blend modes. | normal | No | normal add multiply screen |
tint.red↗ | Rendering-only red multiplier. Applies after per-particle color and opacity. One leaves the channel unchanged; zero removes it. | 1 | No | — |
tint.green↗ | Rendering-only green multiplier. Applies after per-particle color and opacity. One leaves the channel unchanged; zero removes it. | 1 | No | — |
tint.blue↗ | Rendering-only blue multiplier. Applies after per-particle color and opacity. One leaves the channel unchanged; zero removes it. | 1 | No | — |
tint.alpha↗ | Rendering-only alpha multiplier. Applies after per-particle color and opacity. One leaves the channel unchanged; zero removes it. | 1 | No | — |
Modifiers
| Setting | Description | Default | Required | Value |
|---|---|---|---|---|
modifiers | Ordered list of acceleration, drag, radial, and vortex forces. Up to 64 per emitter. Emitter modifiers run before effect-level modifiers; repeated types are allowed. | [] | No | 0 to 64 items |
acceleration.magnitude↗ | Constant force along the rotated local up direction. Changes velocity every simulation step. Accepts a number or a curve. Curve time 1 equals the configured emitter duration; beyond 1, the curve continues along its final slope. | 0 | No | — |
acceleration.spread↗ | Variation in modifier strength for individual particles. | 0 | No | 0 or more |
acceleration.rotation↗ | Counterclockwise rotation of the modifier axis, in degrees. | 0 | No | — |
drag.magnitude↗ | Velocity damping. Positive strength slows particles; directional mode damps only the selected axis. Accepts a number or a curve. Curve time 1 equals the configured emitter duration; beyond 1, the curve continues along its final slope. | 0 | No | — |
drag.spread↗ | Variation in modifier strength for individual particles. | 0 | No | 0 or more |
drag.useDirection↗ | Damp velocity along the rotated axis instead of damping all directions. | false | No | — |
drag.rotation↗ | Counterclockwise rotation of the modifier axis, in degrees. | 0 | No | — |
radial.magnitude↗ | Force away from a center, with distance falloff. Negative magnitude attracts particles. Accepts a number or a curve. Curve time 1 equals the configured emitter duration; beyond 1, the curve continues along its final slope. | 0 | No | — |
radial.spread↗ | Variation in modifier strength for individual particles. | 0 | No | 0 or more |
radial.x↗ | Horizontal center of the modifier in its authored scope. | 0 | No | — |
radial.y↗ | Vertical center of the modifier in its authored scope. | 0 | No | — |
radial.maxDistance↗ | Distance over which the force falls off to zero. | 100 | No | 0 or more |
vortex.magnitude↗ | Tangential force around a center, with distance falloff. Change the sign to reverse circulation. Accepts a number or a curve. Curve time 1 equals the configured emitter duration; beyond 1, the curve continues along its final slope. | 0 | No | — |
vortex.spread↗ | Variation in modifier strength for individual particles. | 0 | No | 0 or more |
vortex.rotation↗ | Counterclockwise rotation of the modifier axis, in degrees. | 0 | No | — |
vortex.x↗ | Horizontal center of the modifier in its authored scope. | 0 | No | — |
vortex.y↗ | Vertical center of the modifier in its authored scope. | 0 | No | — |
vortex.maxDistance↗ | Distance over which the force falls off to zero. | 100 | No | 0 or more |
type | Modifier discriminator. Acceleration pushes, drag slows, radial pushes away from a center, and vortex circulates around it. Each type has its own valid fields. | — | Yes | acceleration drag radial vortex |
Effect
| Setting | Description | Default | Required | Value |
|---|---|---|---|---|
modifiers | Shared modifiers applied to every emitter after its local modifier list. Up to 64 at effect scope. Positions are relative to the effect. | [] | No | 0 to 64 items |
version↗ | Configuration format version. The current schema accepts only 1. This is a compatibility marker, not a visual setting. | — | Yes | 1 |
emitters↗ | Nonempty list of emitters. Each must have a unique ID, capacity, seed, emission settings, and required initial values. Add another emitter to combine effects. | — | Yes | 1 or more items |
Over lifetime
| Setting | Description | Default | Required | Value |
|---|---|---|---|---|
scale↗ | Multiplies the particle’s initial size. A number stays constant; a curve follows each particle from birth at time 0 to expiration at time 1. | 1 | No | — |
stretchX↗ | Added to the particle’s initial stretchX. A number stays constant; a curve follows each particle from birth at time 0 to expiration at time 1. | 0 | No | — |
stretchY↗ | Added to the particle’s initial stretchY. A number stays constant; a curve follows each particle from birth at time 0 to expiration at time 1. | 0 | No | — |
rotation↗ | Added to the particle’s initial rotation. A number stays constant; a curve follows each particle from birth at time 0 to expiration at time 1. | 0 | No | — |
angularVelocity↗ | Multiplies the particle’s initial angularVelocity. A number stays constant; a curve follows each particle from birth at time 0 to expiration at time 1. | 1 | No | — |
red↗ | Multiplies the particle’s initial red. A number stays constant; a curve follows each particle from birth at time 0 to expiration at time 1. | 1 | No | — |
green↗ | Multiplies the particle’s initial green. A number stays constant; a curve follows each particle from birth at time 0 to expiration at time 1. | 1 | No | — |
blue↗ | Multiplies the particle’s initial blue. A number stays constant; a curve follows each particle from birth at time 0 to expiration at time 1. | 1 | No | — |
alpha↗ | Multiplies the particle’s initial alpha. A number stays constant; a curve follows each particle from birth at time 0 to expiration at time 1. | 1 | No | — |
Curves
| Setting | Description | Default | Required | Value |
|---|---|---|---|---|
overLifetime.alpha↗ | Shape particle opacity over its lifetime. Edit point times, values, and tangents, then apply the curve to the preview. Time runs from birth (0) to expiration (1). A tangent controls the slope through a point. | 1 to 0 | No | — |