FolioTier 2

@particles

Customizable persistent particles with 15 procedural presets, preset-specific style controls, wind, variance, spawn areas, and stage layering. Setting intensity=0 clears instantly and by scope, not by preset: with a sprite target it stops that sprite's streams, otherwise it stops every emitter on the stage.

@particles launches a continuous stream of ambient effects that persist across as many dialogue lines as you want, running independently of story progression until you stop them. Choosing a preset sets the basic character - whether you are after the quiet intimacy of fireflies, the weight of falling ash, or the chaos of confetti - and the style parameters let you push that character further to match your exact scene mood.

When you attach a target, the emitters anchor to a specific sprite and follow it as it moves, making the effect feel personal to a character. Omit target and the stream fills the whole frame, useful for setting a scene before anyone speaks.

Stopping particles works by scope, not by preset. Setting intensity=0 with a target stops only that sprite's streams. Setting intensity=0 without a target clears every active emitter on stage at once, regardless of how many presets or colors are running - you cannot selectively stop one full-stage preset while leaving another running.

The style parameters are preset-specific tuning knobs, not universal controls. Not every parameter has a visible effect on every preset - experimenting on the preset you have chosen is the only reliable way to know what moves the needle.

wind and direction operate at different levels. direction sets the angle particles leave the emitter; wind adds a lateral push that accumulates as particles age, bending their paths over time. Both can run together.

If you need two overlapping effects - mist behind a character and sparkles in front, for example - call @particles twice with different layer values. Each call opens its own independent stream, and they coexist until you stop them separately.

Parameters

Parameter	Kind	Required	Default	Notes
preset	string	no	sparkles	One of: sparkles, hearts, petals, aura, rain, snow, embers, fireflies, bubbles, leaves, smoke, dust, ash, confetti, mist. Default sparkles.
color	string	no		Hex color (#rgb or #rrggbb) or white/black. Default .
target	string	no	""	Optional sprite tag; empty targets the whole frame.
toward	string	no	""	Optional text value.
direction	number	no	-1	-1 to 360 degrees. Default -1.
emit_x	number	no	0.5	0-1 (0-1). Default 0.5.
emit_y	number	no	0.5	0-1 (0-1). Default 0.5.
hit_x	number	no	0.5	0-1 (0-1). Default 0.5.
hit_y	number	no	0.5	0-1 (0-1). Default 0.5.
distance	number	no	0	0-3000 pixels. Default 0.
intensity	number	no	1	0-3 × multiplier. Default 1.
speed	number	no	1	0.25-3 × multiplier. Default 1.
size	number	no	1	0.25-3 × multiplier. Default 1.
opacity	number	no	1	0.1-1 (0-1). Default 1.
wind	number	no	0	-1 to 1 × multiplier. Default 0.
variance	number	no	0.35	0-1 (0-1). Default 0.35.
layer	string	no	over	One of: over, behind, front. Default over.
area	string	no	auto	One of: auto, full, top, bottom, left, right. Default auto.
blink	number	no	1	0.25-3 × multiplier. Default 1.
drift	number	no	0.45	-1 to 1 × multiplier. Default 0.45.
flutter	number	no	0.5	0-1 × multiplier. Default 0.5.
glow	boolean	no	true	true or false. Default true.
pop	boolean	no	true	true or false. Default true.
pulse	number	no	1	0.25-3 × multiplier. Default 1.
slant	number	no	8	-45 to 45 × multiplier. Default 8.
spread	number	no	1.3	0.5-2 × multiplier. Default 1.3.
streak	number	no	1	0.5-2 × multiplier. Default 1.
tumble	number	no	0.85	0-1 × multiplier. Default 0.85.
turbulence	number	no	0.6	0-1 × multiplier. Default 0.6.
twinkle	number	no	1	0.25-3 × multiplier. Default 1.
wobble	number	no	0.55	0-1 × multiplier. Default 0.55.
duration	number	no	0	0-30 seconds. Default 0.
wait	boolean	no	false	Block for the effect's duration when true; false fires and continues so effects can overlap.

Canonical example

sprite show ada
@particles(sparkles, target=ada, intensity=1)
say "Ada": "(I can't believe this is happening.)"
say "Ada": "(It's actually happening.)"
@particles(sparkles, target=ada, intensity=0)

@particles runs a persistent particle emitter on a sprite (when target is set) or across the whole in-world frame (when target is empty). Each preset has its own particle shape, lifetime, velocity, and rotation behavior - pick by intent, then tune the feel with intensity (density), speed (velocity), size (scale), opacity, wind, and variance. Whole-frame particles also support layer and area. The inspector shows only the style controls that belong to the active preset.

Presets

| preset | Shape | Use | |---|---|---| | sparkles | Soft yellow-white twinkles | Romance, magic, "discovery" beats. Default. | | hearts | Pink hearts floating up | Affection, infatuation, a romantic kiss. | | petals | Pink ovals drifting + rotating | Cherry blossoms, "scene-setting" garden / spring moods. Best with target="" (whole frame). | | aura | Soft expanding glow circles | Breath, energy, "calm power" around a character. Low density. | | rain | Vertical white-blue streaks | Stage-wide rain. Best with target="". | | snow | Slow-drifting white dots | Stage-wide snow. Best with target="". | | embers | Glowing orange motes rising | Fire, forge, danger, warmth. Rises from the bottom edge whole-frame. | | fireflies | Slow blinking yellow-green glows | Night, summer dusk, quiet magic. Low density, omnidirectional drift. | | bubbles | Translucent blue bubbles rising | Underwater, bath, playful / dreamy beats. Rises from the bottom edge. | | leaves | Tumbling autumn-toned ovals | Fall, melancholy, the passage of time. Falls from the top edge. | | smoke | Expanding grey puffs rising | Mystery, fog, aftermath, danger. Rises from the bottom edge. | | dust | Tiny warm motes | Sunbeams, quiet rooms, suspended time. | | ash | Grey turbulent flecks | Aftermath, grief, wildfire, ruin. | | confetti | Multi-color tumbling strips | Celebration and release. | | mist | Large low-alpha drifting discs | Layered fog, best behind the cast. |

Preset-specific controls include rain slant and streak; snow and petal flutter and drift; leaf tumble; ember turbulence and glow; firefly blink; sparkle twinkle; aura pulse; heart and bubble wobble; bubble pop; and smoke or mist spread.

Lifecycle

@particles is persistent by default, unlike @sprite-opacity or @pan which complete and resolve. With the default duration=0, the player advances immediately and the emitter keeps running until you clear it:

@particles(rain, intensity=0.8)
say "Liam": "Looks like it's not letting up."
say "Liam": "We should head inside."
@particles(intensity=0)

intensity=0 is a hard clear. The particles are gone on the next frame - nothing fades out and nothing lingers.

The clear is scoped, not matched to a preset, so it does not need to name what is running. Give it a target and it clears only that sprite's streams; leave the target off and it clears every emitter on the stage at once, whatever started them:

@particles(snow, intensity=1)
@particles(embers, target=ada, intensity=1)
@particles(intensity=0)

That last line stops both.

Blocking mode

Set duration>0 for a fire-and-finish emit that blocks player advance for the specified seconds. The emitter auto-stops at the end of the duration; particles fade out naturally afterward:

@particles(hearts, target=ada, duration=2)
say "Ada": "..."

The dialogue line waits 2 seconds while hearts emit, then advances.

Target semantics

| target | Emitter attaches to | |---|---| | "" (default) | The whole frame. area=auto uses the recipe's top, bottom, or fill archetype. layer selects behind, over, or front placement. | | "backdrop" | Background scope in Forge. It supports the same whole-frame area and layer controls. | | "ada" | The sprite with that slug. Spawn area is sized to the sprite's footprint. The emitter follows the sprite if a sprite move or camera pan/zoom changes its position. This is the Sprite effect scope. |

If the targeted sprite is removed (sprite hide or scene change), the emitter is destroyed along with it.

Directional (sprite-to-sprite)

In the Sprite effect scope you can set toward to a second sprite's slug. The target sprite becomes the source, and particles stream from it toward the toward sprite - re-aimed every frame, so the stream tracks both characters as they move. Empty toward (the default) is a normal area emitter over the source.

sprite show ada
sprite show liam
@particles(hearts, target=ada, toward=liam, intensity=1)

Hearts flow from Ada toward Liam. Directional is sprite-scope only - whole-frame and backdrop emitters ignore toward.

Chosen direction (fixed heading)

Instead of aiming at a sprite, leave toward empty and set direction to a heading in degrees (0 = right, 90 = down, 180 = left, 270 = up). Particles fire that way from the emit_x/emit_y point on the source for distance pixels (default 240). direction defaults to -1, which means "off" - a plain burst or a toward stream. In Forge this is the Chosen direction option in the Stream-toward dropdown: a radial dial aims the arrow, a square places the emit origin.

sprite show ada
@particles(embers, target=ada, direction=270, distance=300, intensity=1)

Embers rise straight up off Ada.

Composition

Multiple presets can run concurrently on the same target - each (target, preset) pair gets its own emitter. Sparkles + aura around the same character compose without one canceling the other.

Notes

@particles is a Pixi-renderer effect, using @spd789562/particle-emitter (a Pixi v8-compatible fork of the classic @pixi/particle-emitter).

Particle textures are generated procedurally from Graphics on first use, so this effect ships zero image assets - the only runtime cost is the emitter package itself.

Studio