Luawe All pages

Colors

A color is a value, like a number or a piece of text. A script makes one, keeps it in a variable, gives it to a thing, finds the color between two of them, and asks it what it is made of. Wherever the editor has a color (a thing's color, a text's outline, a gradient's keypoints, a particle's color, the camera's flash), a script gives a color value.

Making a color

There are three ways to make one. Here they make the same orange:

local a = color.rgb(255, 136, 0)   -- how much red, green and blue: each from 0 to 255
local b = color.hex("#FF8800")     -- written as a color picker writes it
local c = color.hsv(32, 100, 100)  -- hue, saturation and value

print(a, b, c)
print(a == b, b == c)

It prints

color.rgb(255, 136, 0) color.rgb(255, 136, 0) color.rgb(255, 136, 0)
true true
  • color.rgb(r, g, b) mixes light: all three at 0 is black, all three at 255 is white.
  • color.hex(text) takes what a color picker shows. The # can be left out, and a short one works too: "#F80" is "#FF8800".
  • color.hsv(h, s, v) is the color wheel. The hue h is the place on the wheel, from 0 to 360: red, then yellow, green, cyan, blue, purple, and red again. The saturation s is how strong the color is, from 0 (gray) to 100 (full). The value v is how bright, from 0 (black) to 100. A hue past the end goes round: 392 is the same as 32.

Two colors with the same red, green and blue are equal: == says so, as it does for numbers.

The named colors

The common ones have a name, so there is nothing to type:

WrittenIs
color.whitecolor.rgb(255, 255, 255)
color.blackcolor.rgb(0, 0, 0)
color.graycolor.rgb(128, 128, 128)
color.redcolor.rgb(255, 0, 0)
color.orangecolor.rgb(255, 136, 0)
color.yellowcolor.rgb(255, 255, 0)
color.greencolor.rgb(0, 255, 0)
color.cyancolor.rgb(0, 255, 255)
color.bluecolor.rgb(0, 0, 255)
color.purplecolor.rgb(136, 0, 255)
color.pinkcolor.rgb(255, 102, 204)

Coloring a thing

A thing's color is a color. Read it, or set it:

local door = things.find("door")
local label = things.find("label")

door.color = color.red
label.color = color.hex("#FFD65C")
label.outlineColor = color.black

things.new takes a color the same way, and tween glides from one color to another:

local square = things.new(cat.Kind.decoration, { centerX = 4, centerY = 0, width = 1, height = 1, color = color.orange })
square:tween({ color = color.blue }, 1.5)

A text has a second one, label.outlineColor. A child's colors are reached through the child: ghost.particles.colors, lamp.picture.tint. Rest the mouse on a row in the editor to see what a script calls it.

A color's parts

A color knows its red, green and blue, and it can say what it is in each of the three ways it can be made:

local orange = color.rgb(255, 136, 0)

print(orange.r, orange.g, orange.b)
print(orange:toHex())
print(orange:toRGB())
print(orange:toHSV())

It prints

255 136 0
#FF8800
255 136 0
32 100 100

toRGB and toHSV give three numbers, so they are read into three variables: local h, s, v = orange:toHSV().

local orange = color.rgb(255, 136, 0)
local teal = color.rgb(0, orange.g, orange.b) -- the same green and blue, no red
print(teal)

local part = "r"
print(pcall(function() orange[part] = 0 end))

It prints

color.rgb(0, 136, 0)
false door.luawe:6: a color can't be changed: make a new one, like color.rgb(255, c.g, c.b)

A color between two

a:lerp(b, t) is a color between two: at t = 0 it is a, at t = 1 it is b, and at 0.5 it is half way. A t outside 0 to 1 is held to the nearest end. color.lerp(a, b, t) is the same thing written the other way round.

print(color.red:lerp(color.blue, 0.5))
print(color.lerp(color.black, color.white, 0.25))
print(color.red:lerp(color.blue, 7))

It prints

color.rgb(128, 0, 128)
color.rgb(64, 64, 64)
color.rgb(0, 0, 255)

lerp is the same idea for numbers, colors, gradients and ranges: Gradients and ranges has them side by side.

A color between two is how a color changes with the music. This lamp is red on the first beat of a bar and yellow on the last:

local lamp = things.find("lamp")

level.beat:connect(function(beat)
    lamp.color = color.red:lerp(color.yellow, (beat % 4) / 3)
end)

Colors in a gradient, or in particles

A gradient holds colors along a line, each with its alpha. It is a value of its own, made with gradient.new, and the colors are spread evenly from the start to the end. To put one at a place of its own, give the place from 0 (the start) to 1 (the end) and the color with its alpha:

local sign = things.find("sign")
local colors = gradient.new({ [0] = color.red, [0.75] = color.blue, [1] = color.green })
sign:addChild(cat.Child.gradient, { colors = colors })
print(sign.gradient.colors:colorAt(0.75))

A particle gives its colors over its life the same way: colors = gradient.new({ color.white, color.orange, color.red }) is a spark that cools from white to red (Particles has more). Gradients and ranges is the whole page about them.

Colors that follow the theme

Many colors in a level are not set by hand: the floor, the water and the blocks take the level's theme, and change when the theme does. The theme's colors have names in two places, and they are not the same thing:

WrittenIs
cat.Theme.waterA link: the thing's color follows the theme's water from then on
theme.waterA copy of the water's color as it is right now
color.theme(cat.Theme.water)The same copy, asked for with the item

cat.Theme has water, floorA, floorB, block, blockLight, glow, waterDeep, waterTops and shadowColor. Give a thing the link and it changes with the theme. Give it the copy and it stays the color the theme was when the script asked:

local sea = things.find("sea")
local rock = things.find("rock")

sea.color = cat.Theme.water  -- follows the theme
rock.color = theme.water     -- the water's color now, and it stays
print(sea.color, rock.color)

A thing that follows the theme reads back as the item (cat.Theme.water), and the item reads like the color it is now: sea.color.r, sea.color:toHex() and sea.color:lerp(color.white, 0.5) work as they do on any color, with the water's color at that moment. It is still the item, so sea.color == cat.Theme.water is true. A gradient's keypoint can follow the theme too: Gradients and ranges.

theme.water = color.hex("#204060") sets the theme's own color. The theme's other rows (its patterns and styles, theme.pattern) are in the camera and the theme.

How solid a color is

A color has no alpha. A color is only red, green and blue; asking for orange.a is refused. How solid a thing looks is the thing's own alpha, from 0 (not there) to 1 (fully there). It works for any color:

local door = things.find("door")
door.color = color.red
door.alpha = 0.5 -- a red you can see through

A gradient's keypoints are the one place a color travels with an alpha: each keypoint has both, and they are two numbers side by side, not one value.

The rules

  • A color is made with color.rgb, color.hex or color.hsv, or has a name, like color.red.
  • c.r, c.g and c.b read its parts, and c:toHex(), c:toRGB() and c:toHSV() say what it is as text or as numbers.
  • a:lerp(b, t) gives one between two.
  • A color can't be changed: make a new one. It has no alpha: use the thing's alpha.
  • Where the editor has a color, a script sets a color value: thing.color = color.red.
  • cat.Theme.water follows the theme; theme.water is a copy taken now.
  • shader.gray is something else: it is how bright a color is inside a shader.