Particles
Sparks, smoke, rain, confetti: a thing with a Particles child lets particles go. You can set every part of them in the editor (the Particles child, under Children) and from a script. The child's Presets button gives a ready-made look to start from: Sparkles, Smoke, Fire, Rain, Confetti, Explosion, Sparks, Snow or Shockwave.
Examples first
Sparks that burst out when the character is hit, then shrink and fade away:
local sparks = things.new(cat.Kind.decoration, { centerX = 0, centerY = 0, width = 0.3, height = 0.3, alpha = 0 })
sparks:addChild(cat.Child.particles, {
manual = true, rate = 0, spread = 180, drag = 3, glow = 1,
lifetime = range2.new(0.6, 1.2),
speed = range2.new(3, 9),
colors = gradient.new({ color.white, color.rgb(255, 90, 90), { color.rgb(255, 40, 60), 0 } }),
size = curve.new({ [0] = { 0.28, 0.1 }, [0.5] = { 0.17, 0.06 }, [1] = 0 }),
})
player.hurt:connect(function()
sparks.centerX, sparks.centerY = player.x, player.y
sparks:emit(26)
end)Smoke that swells as it rises, then thins out:
local chimney = world.Chimney
chimney.particles.size = curve.new({ [0] = { 0.4, 0.1 }, [1] = { 1.3, 0.25 } })
chimney.particles.colors = gradient.new({ [0] = { color.rgb(214, 214, 224), 0 }, [0.2] = { color.rgb(190, 190, 200), 0.45 }, [1] = { color.rgb(112, 112, 124), 0 } })
chimney.particles.lifetime = range2.new(3, 4)Make the fire grow over two seconds:
world.Fire:tween({ ["particles.size"] = curve.new({ [0] = 0.4, [0.25] = { 1, 0.2 }, [1] = 0.1 }) }, 2)Ranges: each particle is a little different
Some numbers are a range, a min and a max: lifetime (beats it lives), speed (tiles a beat it sets off at), rotation (degrees it is turned when it is let go), rotationSpeed (degrees a beat it spins) and orbit (degrees a beat it swings round the middle of its area). Each particle takes its own number between the two ends. Make both ends the same and every particle has that number.
In the editor a range is one row with two boxes: min on the left, max on the right. In a script it is a range2 value, and it is the thing's own:
local spark = world.Spark
print(spark.particles.lifetime) --> range2.new(1, 2)
spark.particles.lifetime.max = 3 -- the longest a particle lives is now 3 beats
spark.particles.speed = range2.new(2, 6)
spark.particles.rotation = 0 -- a number sets both ends: no particle is turnedColor over its life: a gradient
colors is a gradient, the same as a Gradient child's: its colors along the bottom of the bar and its alpha (how solid it is: 1 solid, 0 gone) along the top. Left is when a particle is let go, right is when it goes. A single color is the same all its life. A color can follow the theme, as everywhere else.
local spark = world.Spark
spark.particles.colors = gradient.new({ [0] = { color.yellow, 0 }, [0.1] = color.orange, [1] = { color.red, 0 } })Gradients and ranges says more about gradient values.
Size over its life: a curve
size is a curve: a number over a particle's life, from 0 (let go) to 1 (gone), made of keypoints. Each keypoint has a time, a value (the size in tiles) and an envelope: how much bigger or smaller each particle may be there. A particle that is a little bigger than the others stays a little bigger all its life.
In the editor the curve is a small graph: drag a point to move it, double-click to add one, right-click one to take it out. The band around the line is the envelope. The Shapes button has ready-made curves: Constant, Grow, Shrink, Grow then shrink and Pulse.
In a script, curve.new takes keypoints by their time, each a value or { value, envelope }. A plain list is spread evenly:
local grow = curve.new({ 0, 1 }) -- from nothing to 1 tile
local swell = curve.new({ [0] = 0.2, [0.3] = { 0.8, 0.2 }, [1] = 0 })
print(swell:valueAt(0.3), swell:envelopeAt(0.3)) --> 0.8 0.2
print(swell:reverse())
print(grow:lerp(swell, 0.5)) -- half way between the two
for _, k in swell.keys do
print(k.time, k.value, k.envelope)
endA curve can't be changed: make a new one. Like a gradient, it can also be a thing's attribute or a marker's value.
Glow
glow goes from 0 to 1. At 0 particles are drawn like paint; at 1 they are drawn like light, their colors adding up where they overlap (bright fire, magic). In between, they are a bit of both. At 1 they glow whatever the thing's blend mode is.
Keys and Set property
Every number of a particle can be keyed and set by a Set property node: a range's ends are particles.lifetime.min and particles.lifetime.max, the color keypoints particles.color1.r and particles.alpha1.value (the first keypoint is 1), the size keypoints particles.size1.value and particles.size1.envelope. A key counts for the particles let go from then on: a particle that is already out keeps what it was let go with. The glow, and every switch and choice, changes all the particles out there at once.
Every particle setting
| In the editor | In a script | What it does |
|---|---|---|
| Per beat | rate | Particles let go each beat. |
| Burst | burst | Particles let go all at once when it appears. |
| Lifetime | lifetime | How long each lives, in beats (a range). |
| Most at once | max | The most out at once. |
| Only when told | manual | Nothing flows by itself: only thing:emit(count) or an Emit node lets particles go. |
| Quick start | quickStart | Already flowing when it appears. |
| When it goes | end | cat.ParticleEnd.finish: they live out their life; cat.ParticleEnd.cut: they all go with it. |
| Seed | seed | Another number, another pattern. |
| Area x, y | areaX, areaY | Where they start: its width and height times this. |
| Area shape | from | cat.ParticleArea.box or cat.ParticleArea.oval. |
| From its edge | edge | 0: anywhere in the area; 1: only on its edge. |
| They set off | aim | cat.Aim.direction or cat.Aim.outward (away from the middle). |
| Direction | direction | Degrees: -90 up, 0 right, 90 down. |
| Spread | spread | Plus or minus this many degrees. |
| Speed | speed | Tiles a beat (a range). |
| Gravity x, y | gravityX, gravityY | Tiles a beat gained every beat. |
| Drag | drag | How quickly they lose their speed. |
| Orbit | orbit | Degrees a beat they swing round the middle (a range). |
| Sway, Sway speed | sway, swaySpeed | How far they wander off their way, and how often they change it. |
| Keep its movement | inherit | How much of the thing's own movement they set off with. |
| Move with it | local | They move and turn with the thing. |
| Shape | shape | cat.ParticleShape.square, circle, sparkle or ring. |
| Color over its life | colors | A gradient. |
| Size over its life | size | A curve. |
| Rotation | rotation | Degrees when let go (a range). |
| Rotation speed | rotationSpeed | Degrees a beat (a range). |
| Faces its way | faceMotion | Turned the way it is going. |
| Stretch | stretch | Longer along its way the faster it goes. |
| Glow | glow | 0 paint, 1 light. |
| Lighter and darker | shade | Each particle a little lighter or darker than the next. |
| Behind it | behind | Drawn just behind the thing. |
| Picture | file (in addChild), frames, columns, rows, play, frameRate, overLife, randomStart, sharp | Particles made of a picture, as a Picture child's. |
| Collisions, Hitbox | collideWater, collidePath, collideBlocks, collideCustom, onHit, bounce, hitbox | What they bounce off, and how: the page Particles that bounce. |