Gradients and ranges
Three kinds of value that hold more than a number: a gradient (colors along a line, each with its alpha), a range (numbers between a min and a max, like a health bar) and a curve (a number along a line, like a particle's size as it ages).
Gradients
A gradient is made from its keypoints. Each keypoint has a time from 0 to 1 (the Time row of a keypoint in the editor), a color and an alpha (1 is solid, 0 is gone, as a thing's alpha). It is written [time] = { color, alpha }.
local sunset = gradient.new({
[0] = { color.yellow, 1 },
[0.5] = { color.orange, 1 },
[1] = { color.purple, 0.5 },
})
print(sunset:colorAt(0.25), sunset:alphaAt(1))It prints
color.rgb(255, 196, 0) 0.5A color alone is a keypoint with alpha 1, and a plain list of colors is spread evenly from 0 to 1:
print(gradient.new({ color.red, color.blue }))It prints
gradient.new({ [0] = { color.rgb(255, 0, 0), 1 }, [1] = { color.rgb(0, 0, 255), 1 } })A gradient has 16 keypoints at most, as in the editor. Printed, it is the code that makes it again.
A gradient can't be changed
A gradient is a value, like a number or a color: it can't be changed. Its functions give new gradients.
g:reverse()is the same keypoints the other way round.g:lerp(other, t)is a gradient between the two (t from 0 to 1). With as many keypoints as each other, each keypoint glides to the other's, its time too.gradient.keysis a list of its keypoints, each a table withtime,colorandalpha(a new list each time):for _, key in sunset.keys do ... end.
On a thing
A Gradient child's colors are one gradient value, thing.gradient.colors, and particles' colors over their life are another, thing.particles.colors:
local door = world.Door
door:addChild(cat.Child.gradient, { colors = gradient.new({ color.white, { color.white, 0 } }) })
door.gradient.colors = gradient.new({ color.red, color.blue })
door:tween({ ["gradient.colors"] = gradient.new({ color.blue, color.red }) }, 2)The child's other properties (rotation, shape, size...) stay its own, as before.
Following the theme
A keypoint's color can be an item of cat.Theme: the keypoint then follows that color of the theme, as a keypoint set to "follow the theme" in the editor does. A color value (theme.water, color.theme(cat.Theme.water)) is a copy, and stays as it is.
local sea = gradient.new({ [0] = { cat.Theme.water, 1 }, [1] = { cat.Theme.waterDeep, 1 } })Ranges
range2.new(min, max) is a number range; range3.new(min, current, max) also has a number inside it. Given the wrong way round, the ends are put in order: range2.new(6, 1) is 1 to 6.
local health = range3.new(0, 100, 100)
health.current -= 20
print(health, health.fraction)
health.current -= 500
print(health.current)It prints
range3.new(0, 80, 100) 0.8
0A range has its numbers by name: range2.min and range2.max (a range3 has them too, as range3.min and range3.max, and a third, range3.current). range3.current always stays from min to max. Setting min past max moves max with it (and the other way round).
r:lerp(t)is the number t of the way from min to max, asmath.lerp.r:clamp(x)is x kept inside the range;r:contains(x)says whether x is inside it.r:random()is a random number inside it.range3.fractionis how far current is, from 0 to 1 (a health bar's width:bar.width = health.fraction * 4). Set it to put current there.range2.changedandrange3.changedare events that happen when one of the range's numbers changes:health.changed:connect(function() print(health.current) end).
A range can be changed
Unlike a color or a gradient, a range can be changed, like a table. Two names for one range see the same one:
local a = range2.new(0, 10)
local b = a
b.max = 20
print(a.max)It prints
20Curves
A curve is a number that changes along a line. The line goes from 0 to 1, and the curve says what the number is at each place on it. A particle's size over its life is one: the size at 0 is when it is let go, the size at 1 is when it goes.
A curve is made from its keypoints, like a gradient. Each keypoint has a time from 0 to 1, a value and an envelope: how far a value may stray from the line, up or down, from one particle to the next. It is written [time] = { value, envelope }, or [time] = value when there is no envelope.
local swell = curve.new({ [0] = 0.2, [0.3] = { 0.8, 0.2 }, [1] = 0 })
print(swell)
print(swell:valueAt(0.3), swell:envelopeAt(0.3))
print(swell:valueAt(0.65), swell:envelopeAt(0.65))It prints
curve.new({ [0] = { 0.2, 0 }, [0.3] = { 0.8, 0.2 }, [1] = { 0, 0 } })
0.8 0.2
0.4 0.1Between two keypoints the curve goes in a straight line, and so do the envelopes. At 0.65 this one is half way down from 0.8 to 0, so its value is 0.4 and its envelope 0.1.
A plain list is spread evenly from 0 to 1, as with a gradient:
print(curve.new({ 0, 1, 0 }))It prints
curve.new({ [0] = { 0, 0 }, [0.5] = { 1, 0 }, [1] = { 0, 0 } })A curve has 16 keypoints at most, as in the editor. Printed, it is the code that makes it again.
A curve can't be changed
A curve is a value, like a gradient: it can't be changed, and its functions give new ones.
c:reverse()is the same keypoints the other way round.c:lerp(other, t)andcurve.lerp(a, b, t)are a curve between the two (t from 0 to 1).curve.keysis a list of its keypoints, each a table withtime,valueandenvelope(a new list each time).curve:valueAt(time)andcurve:envelopeAt(time)say what the curve's value and envelope are at a place on its line:swell:valueAt(0.3).
local grow = curve.new({ 0, 1 })
local swell = curve.new({ [0] = 0.2, [0.3] = { 0.8, 0.2 }, [1] = 0 })
print(swell:reverse())
print(curve.lerp(grow, curve.new({ 2, 3 }), 0.5))
for _, key in swell.keys do
print(key.time, key.value, key.envelope)
endIt prints
curve.new({ [0] = { 0, 0 }, [0.7] = { 0.8, 0.2 }, [1] = { 0.2, 0 } })
curve.new({ [0] = { 1, 0 }, [1] = { 2, 0 } })
0 0.2 0
0.3 0.8 0.2
1 0 0On a thing
A particle's size over its life is one curve value, thing.particles.size. In the editor it is a small graph: drag a point to move it, and the band round the line is the envelope. A script sets the whole curve at once, or glides to another with tween:
local fire = world.Fire
fire.particles.size = curve.new({ [0] = 0.4, [0.25] = { 1, 0.2 }, [1] = 0.1 })
fire:tween({ ["particles.size"] = curve.new({ 0.2, 0.6 }) }, 2)The page Particles shows what each particle does with it. A curve can also be an attribute of a thing or the value of a marker, as a gradient can.
lerp
lerp is the same idea everywhere: from the first value (t = 0) to the second (t = 1).
math.lerp(a, b, t) | numbers (t past 0 or 1 goes past them) |
color.lerp(a, b, t), c:lerp(other, t) | colors (t kept from 0 to 1) |
gradient.lerp(a, b, t), g:lerp(other, t) | gradients (t kept from 0 to 1) |
curve.lerp(a, b, t), c:lerp(other, t) | curves (t kept from 0 to 1) |
r:lerp(t) | a range's min to its max |