Skip to content

Particles

The particle plugin draws effects made of many small sprites: sparks, smoke, explosions, engine trails. You describe an effect once, as a table, then play it from an emitter on an entity, or once at a point. Add the plugin in project.luau:

engine.settings.plugins = { "rtype.SpriteDraw", "rtype.Particle" }

rtype.Particle lives on the client only: particles are something you see, not gameplay. The server has no particles, so the files that build and play effects are required by the client entry only. Systems that play effects are client systems (side = "client").

A first effect

-- scripts/client/effects_assets.luau: returns the ids, for the files that play the effects
return {
    sparks = engine.assets.particle({
        name = "game.sparks",
        texture = engine.assets.texture("particles/spark.png"),
        loop = false,
        duration = 0.1,
        bursts = { { count = 24 } },
        lifetime = { min = 0.2, max = 0.4 },
        speed = { min = 80, max = 160 },
        colorOverLife = { { t = 0, color = { 1, 0.9, 0.4 } }, { t = 1, color = { 1, 0.2, 0, 0 } } },
    }),
    trail = engine.assets.particle({
        name = "game.trail",
        texture = engine.assets.texture("particles/smoke.png"),
        blend = "alpha",
        rate = 40,
        lifetime = 0.6,
        angle = { min = math.pi - 0.2, max = math.pi + 0.2 },
        speed = 60,
        sizeOverLife = { { t = 0, value = 8 }, { t = 1, value = 24 } },
        colorOverLife = { { t = 0, color = { 1, 1, 1, 0.6 } }, { t = 1, color = { 1, 1, 1, 0 } } },
    }),
}
-- scripts/client/effects.luau: sparks where each new laser appears
local effects = require("@scripts/client/effects_assets")

engine.ecs.system("game.MuzzleSparks", {
    phase = "Update",
    side = "client",
    query = { read = { "rtype.Transform" }, added = { "game.Laser" } },
    events = { send = { "rtype.SpawnParticles" } },
    run = function(ctx)
        for _, transform in ctx.query do
            local at = transform.position
            ctx.events.send("rtype.SpawnParticles", { effect = effects.sparks, position = { x = at.x, y = at.y } })
        end
    end,
})

Units are the engine's: positions and sizes in world units (Y down), times in seconds, angles in radians (0 points right, along +X; math.pi / 2 points down).

engine.assets.particle

engine.assets.particle({ ... }) builds an effect and returns its id. Only name is needed: every other key has a default, and an effect with only a name emits nothing. The id is the one of the name, so effect = "game.sparks" in a component means the same effect.

Spawning

Key Type Default Meaning
name string required What the effect is known by
rate number 0 Particles per second while the emitter plays
bursts list none Particles emitted at once, see below
duration number 1 Seconds of one cycle
loop boolean true true: a new cycle starts after duration; false: the effect plays once
capacity whole number 1024 Most particles alive at once; more are not spawned
shape string or table "point" Where particles spawn, see below

A burst is { count, time, cycles, interval }: count particles (required) at time seconds into the cycle (default 0), cycles times (default 1), interval seconds apart (default 0). An explosion is a burst and loop = false; a trail is a rate and loop = true.

The shape is "point", { type = "circle", radius = 8 } (edgeOnly = true spawns on the circle only, as a ring) or { type = "rect", size = { x = 64, y = 4 } }, centred on the emitter and turned and scaled with it.

Each particle

A range is a number (always that value) or { min = , max = }, picked per particle.

Key Type Default Meaning
lifetime range 1 Seconds; above 0
speed range 0 World units per second, along the angle
angle range { min = 0, max = 2 * math.pi } Direction it goes, in radians: every way by default
rotation range 0 Of the quad, in radians, clockwise on screen
angularVelocity range 0 Of the quad, in radians per second
size range 1 Width and height of the quad, in world units
color { r, g, b, a } { 1, 1, 1, 1 } Tints the texture; the alpha may be left out and is then 1
gravity { x, y } { x = 0, y = 0 } World units per second squared; +Y is down
drag number 0 Slows particles down; 0 never does

Over a particle's life

Each list is a list of keys in order of t, from 0 (birth) to 1 (death). Between two keys the value goes in a straight line; before the first and after the last it stays. Two keys at the same t make it jump.

Key One key Meaning
colorOverLife { t = , color = { r, g, b, a } } Multiplies color: fade the alpha to 0 to fade out
sizeOverLife { t = , value = } Multiplies size
speedOverLife { t = , value = } Multiplies the speed

How it looks

Key Type Default Meaning
texture texture id none From engine.assets.texture
source { position, size } the whole texture The part of the texture to show, in pixels
flipbook { columns, rows, frames, cycles } one frame Frames of source in a grid, played over each life: frames is how many (0: every cell), cycles how many times
blend string "additive" "additive" (glows: sparks, fire), "alpha" (smoke, dust) or "cutout"
alignment string "fixed" "fixed", or "velocity": each quad turns along its motion (the texture's +X forward)
stretch number 0 With "velocity": the quad grows longer by speed × stretch
material material id the default one From engine.assets.material, for a shader of your own
space string "world" "world": particles stay where they spawned (trails); "local": they follow the emitter (a shield's glow)
sortByAge boolean false Draws the oldest first; always on with "alpha"
simulation string "auto" "auto", "gpu" or "cpu": where particles are computed. Leave it to "auto"

Playing an effect

Once, at a point

Send rtype.SpawnParticles: the plugin spawns an emitter there, plays its effect once and removes it.

Field Type Default Meaning
effect effect id or name none The effect
position { x, y } { x = 0, y = 0 } In world units
layer integer 0 Draw order among the sprites

Use an effect with loop = false here. A looping one never ends, so it would stay forever.

On an entity

Give the entity an rtype.ParticleEmitter and an rtype.Transform. It plays while the component is there and moves with the entity.

Field Type Default Meaning
effect effect id or name none The effect; changing it restarts the emitter
playing boolean true false stops emitting; living particles finish their life
layer integer 0 Draw order among the sprites
rateScale number 1 Multiplies the effect's rate: more smoke as a ship gets damaged
seed whole number 0 The same seed gives the same particles; 0 picks one
material material id none Replaces the effect's material
overrideSimulation, simulation boolean, number false, 0 true replaces the effect's simulation with this one: 0 auto, 1 GPU, 2 CPU
local effects = require("@scripts/client/effects_assets")

engine.ecs.system("game.ShipTrail", {
    phase = "Update",
    side = "client",
    query = { with = { "game.Ship" }, without = { "rtype.ParticleEmitter" } },
    run = function(ctx)
        for ship in ctx.query do
            ctx.commands:add(ship, "rtype.ParticleEmitter", { effect = effects.trail, layer = -1 })
        end
    end,
})

The ship entity is replicated from the server, but rtype.ParticleEmitter is the client's own: a client system may add it. Remove it, or set playing = false, to stop the trail.

Knowing when it is over

rtype.ParticlesFinished (entity) is sent once an emitter whose effect does not loop has emitted everything and its last particle has died. Read it under events = { read = { "rtype.ParticlesFinished" } }.

Errors

The form checks its whole table and names the part that is wrong:

Message Cause
engine.assets.particle: expected a 'name' No name, or an empty one
engine.assets.particle: unexpected 'colour', expected ... A key the form does not know
engine.assets.particle: 'lifetime': expected a number or a table { min = , max = } A range of the wrong type
engine.assets.particle: 'color': expected a colour { r, g, b } or { r, g, b, a } A colour with too few or too many numbers
engine.assets.particle: burst 1: expected a 'count' A burst without its count
engine.assets.particle: 'sizeOverLife' key 1: expected a 't' A key without its t
... Unknown blend 'glow' (expected 'additive', 'alpha', 'cutout') A name of no known choice, for blend, alignment, space, simulation or the shape type
... Particle effect 'a': ... The effect is invalid, the reason follows: a min above its max, a lifetime of 0, keys out of order or outside 0 to 1

Building an effect twice with the same name keeps the first one.

Only on the client

rtype.ParticleEmitter, rtype.SpawnParticles and rtype.ParticlesFinished exist only where rtype.Particle is, on the client. Declare the systems that name them with side = "client", in files only the client entry requires (see Systems).

See also

  • Setup forms: textures and materials an effect uses.
  • Systems: events, commands and sides.
  • Components: the engine's components and client-only data.