Tutorials · Particle Effects · Chapter 13

Particles and scripts

Particles a script drives

Fireworks on a timer

1. In Assets, click Assets in the path bar over the tree, so the script is written at the project’s top, beside art, artifacts and scenes, then press Create, choose New script, type fireworks, and press Enter.
2. In the Code tab, replace everything in fireworks.rgs with the script below, and press Ctrl+S.
3. Select fireworks and untick Emitting: from now on it fires only when the script says. Set Spread to 0.5, so that three shells leave in slightly different directions.
4. Press Add component and choose Fireworks. Every and Shells start at the script’s own 4 and 3: leave them.

/// Fireworks on a timer. Every `every` seconds the launcher fires `shells`
/// shells at once, fanned out by its emitter's Spread; each shell bursts where
/// it dies, as the emitter's On Death says.
component Fireworks {
    /// Seconds from one salvo to the next.
    #[suffix("s")]
    every: f32 = 4.0,
    /// How many shells a salvo fires.
    shells: f32 = 3.0,

    fn loop() {
        await wait(every);
        burst(shells);
    }
}

burst

Fires that many particles from the script node’s own emitter right now, whatever its mode: a stream gets a puff on top of its flow, a one-shot another round. Here shells, three shells at once.

Every

Seconds between one salvo and the next, 4 here. 3 to 8 suits fireworks over a town this size: under that the sky is never empty, and over it the town waits too long.

Shells

How many shells a salvo fires, 3. They are fanned across the emitter’s Spread, 0.5, so each flies a little differently. 2 to 5 reads as a salvo; a dozen would be a crowd.

A well that hears the fireflies

1. Make wish.rgs the same way, with the script below: Create, New script, wish, Enter, replace its text in the Code tab, and press Ctrl+S.
2. Select fireflies. In its Trigger group tick Trigger, and set Offset to 0 and 30, Shape to Circle with a Radius of 18, and Report to Enter.
3. Select well_ring and untick its Visible: the script lights it, so it starts dark.
4. Select fireflies again, press Add component, and choose Wish. Click the empty Ring slot and choose well_ring from the list, or drag well_ring from the Hierarchy onto the slot. Glow starts at the script’s own 3: leave it.

/// A wishing well. A firefly that drifts into the well's mouth, this emitter's
/// Trigger, lights the well's ring of light where it crossed in, for `glow`
/// seconds; another firefly arriving lights it again.
component Wish : Emitter {
    /// The node whose particles make the well's ring of light.
    #[node_path]
    ring: i32 = 0,
    /// Seconds the ring stays lit after the last firefly crossed in.
    #[suffix("s")]
    glow: f32 = 3.0,
    /// Seconds left before the ring goes dark.
    #[hidden]
    left: f32 = 0.0,

    fn on_particle_enter(at: Vec2) {
        move_node(node(ring), at);
        set_visible(node(ring), true);
        left = glow;
    }

    fn loop() {
        if left > 0.0 {
            left -= dt;
            if left <= 0.0 {
                set_visible(node(ring), false);
            }
        }
    }
}

Trigger

A region that reports the emitter’s own particles crossing it, to the scripts on the emitter’s node. Nothing happens to a particle that crosses: it flies on through. Unticked, no region exists and no hook runs. Its three settings follow.

Offset

Where the region sits, measured from the emitter’s node, in world units. 0, 30 puts it 30 units below the fireflies’ node, which hangs just over the well’s mouth, so the region covers the mouth: y grows downward. The region stays where it is while particles drift through it.

Shape (the trigger’s)

The region’s outline. A Circle asks “inside?” with one distance from its centre, its Radius, 18 here, about the width of the well’s mouth. A Box asks it with a rectangle, its Size the full width and height. This is a second Shape, beside the one chapter 4 set: that one decides where particles are born, and this one where they are heard.

Report

Which crossings call a hook: Enter, a particle crossing in; Exit, a particle crossing out; Both. Enter here, so each firefly that drifts in is heard once. One call is made for each crossing.

on_particle_enter

A hook: code the engine runs for you, here once for each particle that crosses into the Trigger, with at, where it was. on_particle_exit is its twin for particles crossing out, and runs when Report is Exit or Both.

move_node, set_visible and node

Move another node, and show or hide it. node finds that other node from a node field, here ring, which is how a script reaches a node that is not its own.

Ring

The node the script lights: well_ring. It is a node field, filled by picking from the list or dropping a node on it.

Glow

Seconds the ring stays lit after the last firefly crossed in: 3 here. 1 to 5 reads well. Under a second the ring blinks, and over five it is lit most of the night.

A chimney that coughs

1. Make cough.rgs the same way, with the script below, and press Ctrl+S.
2. Select soot_puff, press Add component, and choose Cough. Calm Min and Calm Max start at the script’s own 3 and 6: leave them.

/// A chimney that coughs. Every few seconds, somewhere between `calm_min` and
/// `calm_max`, this node's one-shot emitter is restarted, so it fires its
/// burst of soot again.
component Cough {
    /// The shortest wait between two coughs, in seconds.
    #[suffix("s")]
    calm_min: f32 = 3.0,
    /// The longest wait between two coughs, in seconds.
    #[suffix("s")]
    calm_max: f32 = 6.0,

    fn loop() {
        await wait(random(calm_min, calm_max));
        restart();
    }
}

restart

Empties the script node’s emitter and fires it again from the start: a one-shot fires its whole Burst once more, and a stream starts over. It is what the Particles panel’s Restart does, but a script’s restart() does not prewarm.

random

A random number between the two you give it, so random(calm_min, calm_max) is a wait somewhere between 3 and 6. The same town gives the same numbers every run, so the first cough always comes at the same moment.

wait

Pauses a script for that many seconds. It is written await wait(…), and the rest of loop carries on after it.

Calm Min and Calm Max

The shortest and the longest wait between coughs, in seconds: 3 and 6. A wider spread feels more like a living chimney; equal numbers make a metronome.

A shooting star

1. Make shooting_star.rgs the same way, with the script below, and press Ctrl+S.
2. Select Town, press + Add node, and choose Particles. Rename it shooting_star and set its Position to -20 and 40, just off the left edge of the window. Untick Emitting.
3. Set Rate to 120, Lifetime to 0.8, Speed to 14, Spread to 7 and Gravity to 0.
4. Set Start Color to 0.9, 0.95, 1, alpha 1, End Color to 0.5, 0.6, 1, alpha 0, Start Size to 5 and End Size to 1.5.
5. Set Capacity to 100, Sort Layer to -25, Blend to Add and Texture to soft-dot.png. In the Inherit group set Inherit Velocity to 1.
6. Press Add component and choose ShootingStar. Set From to -20 and 40, and To to 420 and 110. Seconds and Rest start at the script’s own 1 and 5: leave them.

/// A shooting star. Every `rest` seconds this node leaps back to `from`, its
/// emitter off so the leap throws no sparks, then streaks to `to` in
/// `seconds` with its emitter on. Its sparks carry its speed, as the
/// emitter's Inherit Velocity says, so they ride along its path.
component ShootingStar {
    /// Where each crossing starts.
    from: Vec2,
    /// Where it ends.
    to: Vec2,
    /// Seconds a crossing takes.
    #[suffix("s")]
    seconds: f32 = 1.0,
    /// Seconds of dark sky between crossings.
    #[suffix("s")]
    rest: f32 = 5.0,

    fn loop() {
        set_flag("ParticleEmitterComponent", "emitting", false);
        move_to(from);
        await wait(rest);
        set_flag("ParticleEmitterComponent", "emitting", true);
        await anneal_to(to, seconds, .InQuad);
    }
}

set_flag

Writes true or false onto a field of another component on this node: here "ParticleEmitterComponent" and "emitting", the emitter’s Emitting. A script can switch an emitter on and off this way, or any other tick box.

move_to and anneal_to

move_to puts the node at a place at once. anneal_to carries it there over a time, along an easing: .InQuad starts slowly and gathers speed, as a falling star does.

Inherit Velocity

The share of the emitter node’s own velocity that a new particle carries, from 0 to 1. At 0 a particle is thrown only by Speed and Direction, and hangs where it was born. At 1 it also takes all of the node’s speed at birth. 0.3 to 0.5 is where sparks off something that runs read as thrown, and the star takes 1: its sparks ride along with it.

From, To

Where each crossing starts and ends, in world units: -20, 40 just off the left edge, and 420, 110, past the middle of the town and lower.

Seconds, Rest

Seconds a crossing takes, 1, and seconds of dark sky between crossings, 5. A star every 5 to 10 seconds is a rarity; every second it is a meteor shower.

The recipes

Check it works