color

The color namespace — 67 functions.

globals/color/coerce

color.coerce(value: any?) -> Color?

Read a value written in any of the shapes a colour is authored in — a hex string, an {r=,g=,b=,a=} map, or an {r,g,b,a} array — as an sRGB color table. Returns nil when the value does not describe a colour, so a caller can name the value it was handed instead of substituting one. Channels absent from a map or array read as 0; alpha absent reads as 1.

Parameters

• value any (optional) — Value to read as a colour.

Returns Color? — sRGB color table, or nil when value is not a colour.

local c = color.coerce("#5a5a62") or color.coerce({ 0.2, 0.7, 0.2 })

globals/color/complementary

color.complementary(c: Color) -> Color

Complementary color — rotate hue 180° in Oklch space.

Parameters

• c Color — Input color.

Returns Color — Complementary sRGB color.

local accent = color.complementary(primary)

globals/color/darken

color.darken(c: Color, amount: number) -> Color

Decrease the lightness of a color in Oklch perceptual space.

Parameters

• c Color — Input color.
• amount number — Lightness decrease 0-1.

Returns Color — Darkened sRGB color.

local pressed = color.darken(base, 0.1)

globals/color/desaturate

color.desaturate(c: Color, amount: number) -> Color

Decrease the chroma (saturation) of a color in Oklch space.

Parameters

• c Color — Input color.
• amount number — Chroma decrease (typically 0-0.2).

Returns Color — Less saturated sRGB color.

local muted = color.desaturate(base, 0.05)

globals/color/hex

color.hex(hexString: string) -> Color?

Parse a hex color string into an sRGB color table. Accepts 3, 4, 6, or 8 hex digits with or without a leading # (e.g. "#f00", "f00f", "#ff0000", "ff000080"). Returns nil on parse failure.

Parameters

• hexString string — Hex color string.

Returns Color? — sRGB color table or nil.

local fromCss = color.hex("#ff8800")

globals/color/hsl

color.hsl(h: number, s: number, l: number) -> Color

Build a color from HSL (h: 0-360, s: 0-1, l: 0-1). Returned as sRGB.

Parameters

• h number — Hue (degrees, 0-360).
• s number — Saturation (0-1).
• l number — Lightness (0-1).

Returns Color — sRGB color table { r, g, b, a = 1 }.

local teal = color.hsl(180, 0.5, 0.5)

globals/color/hsla

color.hsla(h: number, s: number, l: number, a: number) -> Color

Build a color from HSLA, returned as sRGB.

Parameters

• h number — Hue (0-360).
• s number — Saturation (0-1).
• l number — Lightness (0-1).
• a number — Alpha (0-1).

Returns Color — sRGB color table { r, g, b, a }.

local fadedTeal = color.hsla(180, 0.5, 0.5, 0.3)

globals/color/hsv

color.hsv(h: number, s: number, v: number) -> Color

Build a color from HSV (h: 0-360, s: 0-1, v: 0-1).

Parameters

• h number — Hue (0-360).
• s number — Saturation (0-1).
• v number — Value / brightness (0-1).

Returns Color — sRGB color table { r, g, b, a = 1 }.

local primary = color.hsv(220, 0.7, 0.9)

globals/color/lighten

color.lighten(c: Color, amount: number) -> Color

Increase the lightness of a color in Oklch perceptual space.

Parameters

• c Color — Input color.
• amount number — Lightness increase 0-1.

Returns Color — Lightened sRGB color.

local hover = color.lighten(base, 0.1)

globals/color/linear

color.linear(r: number, g: number, b: number, a: number?) -> Color

Build a color from linear RGB values (not gamma-corrected), output converted to sRGB. Useful for GPU-correct blending. Alpha defaults to 1.

Parameters

• r number — Linear red (0-1).
• g number — Linear green (0-1).
• b number — Linear blue (0-1).
• a number (optional) — Alpha (0-1, default 1).

Returns Color — sRGB color table { r, g, b, a }.

local gpuBlue = color.linear(0.0, 0.0, 1.0)

globals/color/mix

color.mix(c1: Color, c2: Color, t: number) -> Color

Perceptually blend two colors in Oklch space — better than RGB mixing for gradients.

Parameters

• c1 Color — First color.
• c2 Color — Second color.
• t number — Blend factor 0-1 (0 = c1, 1 = c2).

Returns Color — Blended sRGB color.

local mid = color.mix(color.rgb(255, 0, 0), color.rgb(0, 0, 255), 0.5)

globals/color/mixRgb

color.mixRgb(c1: Color, c2: Color, t: number) -> Color

Linearly blend two colors in sRGB space — simple, but not perceptually uniform. Prefer color.mix for natural gradients.

Parameters

• c1 Color — First color.
• c2 Color — Second color.
• t number — Blend factor 0-1.

Returns Color — Blended sRGB color.

local plain = color.mixRgb(a, b, 0.5)

globals/color/oklch

color.oklch(l: number, c: number, h: number) -> Color

Build a color from Oklch perceptual color space (l: 0-1, c: 0-0.4, h: 0-360). Ideal for perceptually uniform gradients and color manipulation.

Parameters

• l number — Lightness (0-1).
• c number — Chroma / saturation (0-0.4).
• h number — Hue (0-360).

Returns Color — sRGB color table { r, g, b, a = 1 }.

local accent = color.oklch(0.7, 0.15, 30)

globals/color/rgb

color.rgb(r: number, g: number, b: number) -> Color

Build an sRGB color from CSS-style 0-255 RGB channels. Alpha defaults to 1. Channels are normalised to 0-1 on the way out so the result composes with every other color helper.

Parameters

• r number — Red channel (0-255).
• g number — Green channel (0-255).
• b number — Blue channel (0-255).

Returns Color — sRGB color table { r, g, b, a = 1 }, normalised to 0-1.

local red = color.rgb(255, 0, 0)

globals/color/rgba

color.rgba(r: number, g: number, b: number, a: number) -> Color

Build an sRGB color from CSS-style 0-255 RGB channels with explicit alpha. RGB are normalised to 0-1; alpha is taken as-is in the 0-1 range.

Parameters

• r number — Red channel (0-255).
• g number — Green channel (0-255).
• b number — Blue channel (0-255).
• a number — Alpha (0-1).

Returns Color — sRGB color table { r, g, b, a }.

local halfRed = color.rgba(255, 0, 0, 0.5)

globals/color/rotateHue

color.rotateHue(c: Color, degrees: number) -> Color

Rotate the hue of a color by a given number of degrees in Oklch space.

Parameters

• c Color — Input color.
• degrees number — Hue rotation (positive or negative).

Returns Color — Hue-rotated sRGB color.

local triadic = color.rotateHue(base, 120)

globals/color/saturate

color.saturate(c: Color, amount: number) -> Color

Increase the chroma (saturation) of a color in Oklch space.

Parameters

• c Color — Input color.
• amount number — Chroma increase (typically 0-0.2).

Returns Color — More saturated sRGB color.

local pop = color.saturate(base, 0.05)

globals/color/toHex

color.toHex(c: Color) -> string

Convert a color to a hex string. Returns "#rrggbb" or "#rrggbbaa" if alpha is not 1.

Parameters

• c Color — Input color.

Returns string — Hex color string.

print(color.toHex(color.rgb(255, 136, 0))) -- "#ff8800"

globals/color/toHsl

color.toHsl(c: Color) -> HslColor

Convert a color to HSL.

Parameters

• c Color — Input color.

Returns HslColor — HSL color table { h, s, l, a } (h: 0-360, s/l: 0-1).

local hsl = color.toHsl(base)

globals/color/toLinear

color.toLinear(c: Color) -> Color

Convert a color from sRGB to linear RGB space — useful for GPU calculations that need linear-space values.

Parameters

• c Color — Input sRGB color.

Returns Color — Linear RGB color table.

local gpu = color.toLinear(base)

globals/color/toOklch

color.toOklch(c: Color) -> OklchColor

Convert a color to Oklch perceptual color space.

Parameters

• c Color — Input color.

Returns OklchColor — Oklch color table { l, c, h, a } (l: 0-1, c: 0-0.4, h: 0-360).

local okl = color.toOklch(base)

globals/color/withAlpha

color.withAlpha(c: Color, a: number) -> Color

Return a copy of a color with a different alpha value.

Parameters

• c Color — Input color.
• a number — New alpha (0-1).

Returns Color with modified alpha.

local ghost = color.withAlpha(base, 0.3)

modules/color/README

require("@builtin/modules/api/engine/color") -- color (also available as global 'color')

Color construction, conversion, and perceptual ops (RGB / HSL / HSV / Oklch / hex). Public Luau surface over the __color Internal FFI namespace.

Usage: local color = require("@builtin/modules/api/engine/color") Also available as global: color

modules/color/coerce

coerce(value: any): Color?

Read a value written in any of the shapes a colour is authored in — a hex string, an {r=,g=,b=,a=} map, or an {r,g,b,a} array — as an sRGB color table. Returns nil when the value does not describe a colour, so a caller can name the value it was handed instead of substituting one. Channels absent from a map or array read as 0; alpha absent reads as 1.

Parameters

• value any (optional) — Value to read as a colour.

local c = color.coerce("#5a5a62") or color.coerce({ 0.2, 0.7, 0.2 })

modules/color/complementary

complementary(c: Color): Color

Complementary color — rotate hue 180° in Oklch space.

Parameters

• c Color — Input color.

local accent = color.complementary(primary)

modules/color/darken

darken(c: Color, amount: number): Color

Decrease the lightness of a color in Oklch perceptual space.

Parameters

• c Color — Input color.
• amount number — Lightness decrease 0-1.

local pressed = color.darken(base, 0.1)

modules/color/desaturate

desaturate(c: Color, amount: number): Color

Decrease the chroma (saturation) of a color in Oklch space.

Parameters

• c Color — Input color.
• amount number — Chroma decrease (typically 0-0.2).

local muted = color.desaturate(base, 0.05)

modules/color/hex

hex(hexString: string): Color?

Parse a hex color string into an sRGB color table. Accepts 3, 4, 6, or 8 hex digits with or without a leading # (e.g. "#f00", "f00f", "#ff0000", "ff000080"). Returns nil on parse failure.

Parameters

• hexString string — Hex color string.

local fromCss = color.hex("#ff8800")

modules/color/hsl

hsl(h: number, s: number, l: number): Color

Build a color from HSL (h: 0-360, s: 0-1, l: 0-1). Returned as sRGB.

Parameters

• h number — Hue (degrees, 0-360).
• s number — Saturation (0-1).
• l number — Lightness (0-1).

local teal = color.hsl(180, 0.5, 0.5)

modules/color/hsla

hsla(h: number, s: number, l: number, a: number): Color

Build a color from HSLA, returned as sRGB.

Parameters

• h number — Hue (0-360).
• s number — Saturation (0-1).
• l number — Lightness (0-1).
• a number — Alpha (0-1).

local fadedTeal = color.hsla(180, 0.5, 0.5, 0.3)

modules/color/hsv

hsv(h: number, s: number, v: number): Color

Build a color from HSV (h: 0-360, s: 0-1, v: 0-1).

Parameters

• h number — Hue (0-360).
• s number — Saturation (0-1).
• v number — Value / brightness (0-1).

local primary = color.hsv(220, 0.7, 0.9)

modules/color/lighten

lighten(c: Color, amount: number): Color

Increase the lightness of a color in Oklch perceptual space.

Parameters

• c Color — Input color.
• amount number — Lightness increase 0-1.

local hover = color.lighten(base, 0.1)

modules/color/linear

linear(r: number, g: number, b: number, a: number?): Color

Build a color from linear RGB values (not gamma-corrected), output converted to sRGB. Useful for GPU-correct blending. Alpha defaults to 1.

Parameters

• r number — Linear red (0-1).
• g number — Linear green (0-1).
• b number — Linear blue (0-1).
• a number? (optional) — Alpha (0-1, default 1).

local gpuBlue = color.linear(0.0, 0.0, 1.0)

modules/color/mix

mix(c1: Color, c2: Color, t: number): Color

Perceptually blend two colors in Oklch space — better than RGB mixing for gradients.

Parameters

• c1 Color — First color.
• c2 Color — Second color.
• t number — Blend factor 0-1 (0 = c1, 1 = c2).

local mid = color.mix(color.rgb(255, 0, 0), color.rgb(0, 0, 255), 0.5)

modules/color/mixRgb

mixRgb(c1: Color, c2: Color, t: number): Color

Linearly blend two colors in sRGB space — simple, but not perceptually uniform. Prefer color.mix for natural gradients.

Parameters

• c1 Color — First color.
• c2 Color — Second color.
• t number — Blend factor 0-1.

local plain = color.mixRgb(a, b, 0.5)

modules/color/oklch

oklch(l: number, c: number, h: number): Color

Build a color from Oklch perceptual color space (l: 0-1, c: 0-0.4, h: 0-360). Ideal for perceptually uniform gradients and color manipulation.

Parameters

• l number — Lightness (0-1).
• c number — Chroma / saturation (0-0.4).
• h number — Hue (0-360).

local accent = color.oklch(0.7, 0.15, 30)

modules/color/rgb

rgb(r: number, g: number, b: number): Color

Build an sRGB color from CSS-style 0-255 RGB channels. Alpha defaults to 1. Channels are normalised to 0-1 on the way out so the result composes with every other color helper.

Parameters

• r number — Red channel (0-255).
• g number — Green channel (0-255).
• b number — Blue channel (0-255).

local red = color.rgb(255, 0, 0)

modules/color/rgba

rgba(r: number, g: number, b: number, a: number): Color

Build an sRGB color from CSS-style 0-255 RGB channels with explicit alpha. RGB are normalised to 0-1; alpha is taken as-is in the 0-1 range.

Parameters

• r number — Red channel (0-255).
• g number — Green channel (0-255).
• b number — Blue channel (0-255).
• a number — Alpha (0-1).

local halfRed = color.rgba(255, 0, 0, 0.5)

modules/color/rotateHue

rotateHue(c: Color, degrees: number): Color

Rotate the hue of a color by a given number of degrees in Oklch space.

Parameters

• c Color — Input color.
• degrees number — Hue rotation (positive or negative).

local triadic = color.rotateHue(base, 120)

modules/color/saturate

saturate(c: Color, amount: number): Color

Increase the chroma (saturation) of a color in Oklch space.

Parameters

• c Color — Input color.
• amount number — Chroma increase (typically 0-0.2).

local pop = color.saturate(base, 0.05)

modules/color/toHex

toHex(c: Color): string

Convert a color to a hex string. Returns "#rrggbb" or "#rrggbbaa" if alpha is not 1.

Parameters

• c Color — Input color.

print(color.toHex(color.rgb(255, 136, 0))) -- "#ff8800"

modules/color/toHsl

toHsl(c: Color): HslColor

Convert a color to HSL.

Parameters

• c Color — Input color.

local hsl = color.toHsl(base)

modules/color/toLinear

toLinear(c: Color): Color

Convert a color from sRGB to linear RGB space — useful for GPU calculations that need linear-space values.

Parameters

• c Color — Input sRGB color.

local gpu = color.toLinear(base)

modules/color/toOklch

toOklch(c: Color): OklchColor

Convert a color to Oklch perceptual color space.

Parameters

• c Color — Input color.

local okl = color.toOklch(base)

modules/color/withAlpha

withAlpha(c: Color, a: number): Color

Return a copy of a color with a different alpha value.

Parameters

• c Color — Input color.
• a number — New alpha (0-1).

local ghost = color.withAlpha(base, 0.3)

typed/builtin//modules/api/engine/color/color/coerce

color.coerce(value: any?) -> Color?

Read a value written in any of the shapes a colour is authored in — a hex string, an {r=,g=,b=,a=} map, or an {r,g,b,a} array — as an sRGB color table. Returns nil when the value does not describe a colour, so a caller can name the value it was handed instead of substituting one. Channels absent from a map or array read as 0; alpha absent reads as 1.

Parameters

• value any (optional) — Value to read as a colour.

Returns Color? — sRGB color table, or nil when value is not a colour.

local c = color.coerce("#5a5a62") or color.coerce({ 0.2, 0.7, 0.2 })

typed/builtin//modules/api/engine/color/color/complementary

color.complementary(c: Color) -> Color

Complementary color — rotate hue 180° in Oklch space.

Parameters

• c Color — Input color.

Returns Color — Complementary sRGB color.

local accent = color.complementary(primary)

typed/builtin//modules/api/engine/color/color/darken

color.darken(c: Color, amount: number) -> Color

Decrease the lightness of a color in Oklch perceptual space.

Parameters

• c Color — Input color.
• amount number — Lightness decrease 0-1.

Returns Color — Darkened sRGB color.

local pressed = color.darken(base, 0.1)

typed/builtin//modules/api/engine/color/color/desaturate

color.desaturate(c: Color, amount: number) -> Color

Decrease the chroma (saturation) of a color in Oklch space.

Parameters

• c Color — Input color.
• amount number — Chroma decrease (typically 0-0.2).

Returns Color — Less saturated sRGB color.

local muted = color.desaturate(base, 0.05)

typed/builtin//modules/api/engine/color/color/hex

color.hex(hexString: string) -> Color?

Parse a hex color string into an sRGB color table. Accepts 3, 4, 6, or 8 hex digits with or without a leading # (e.g. "#f00", "f00f", "#ff0000", "ff000080"). Returns nil on parse failure.

Parameters

• hexString string — Hex color string.

Returns Color? — sRGB color table or nil.

local fromCss = color.hex("#ff8800")

typed/builtin//modules/api/engine/color/color/hsl

color.hsl(h: number, s: number, l: number) -> Color

Build a color from HSL (h: 0-360, s: 0-1, l: 0-1). Returned as sRGB.

Parameters

• h number — Hue (degrees, 0-360).
• s number — Saturation (0-1).
• l number — Lightness (0-1).

Returns Color — sRGB color table { r, g, b, a = 1 }.

local teal = color.hsl(180, 0.5, 0.5)

typed/builtin//modules/api/engine/color/color/hsla

color.hsla(h: number, s: number, l: number, a: number) -> Color

Build a color from HSLA, returned as sRGB.

Parameters

• h number — Hue (0-360).
• s number — Saturation (0-1).
• l number — Lightness (0-1).
• a number — Alpha (0-1).

Returns Color — sRGB color table { r, g, b, a }.

local fadedTeal = color.hsla(180, 0.5, 0.5, 0.3)

typed/builtin//modules/api/engine/color/color/hsv

color.hsv(h: number, s: number, v: number) -> Color

Build a color from HSV (h: 0-360, s: 0-1, v: 0-1).

Parameters

• h number — Hue (0-360).
• s number — Saturation (0-1).
• v number — Value / brightness (0-1).

Returns Color — sRGB color table { r, g, b, a = 1 }.

local primary = color.hsv(220, 0.7, 0.9)

typed/builtin//modules/api/engine/color/color/lighten

color.lighten(c: Color, amount: number) -> Color

Increase the lightness of a color in Oklch perceptual space.

Parameters

• c Color — Input color.
• amount number — Lightness increase 0-1.

Returns Color — Lightened sRGB color.

local hover = color.lighten(base, 0.1)

typed/builtin//modules/api/engine/color/color/linear

color.linear(r: number, g: number, b: number, a: number?) -> Color

Build a color from linear RGB values (not gamma-corrected), output converted to sRGB. Useful for GPU-correct blending. Alpha defaults to 1.

Parameters

• r number — Linear red (0-1).
• g number — Linear green (0-1).
• b number — Linear blue (0-1).
• a number (optional) — Alpha (0-1, default 1).

Returns Color — sRGB color table { r, g, b, a }.

local gpuBlue = color.linear(0.0, 0.0, 1.0)

typed/builtin//modules/api/engine/color/color/mix

color.mix(c1: Color, c2: Color, t: number) -> Color

Perceptually blend two colors in Oklch space — better than RGB mixing for gradients.

Parameters

• c1 Color — First color.
• c2 Color — Second color.
• t number — Blend factor 0-1 (0 = c1, 1 = c2).

Returns Color — Blended sRGB color.

local mid = color.mix(color.rgb(255, 0, 0), color.rgb(0, 0, 255), 0.5)

typed/builtin//modules/api/engine/color/color/mixRgb

color.mixRgb(c1: Color, c2: Color, t: number) -> Color

Linearly blend two colors in sRGB space — simple, but not perceptually uniform. Prefer color.mix for natural gradients.

Parameters

• c1 Color — First color.
• c2 Color — Second color.
• t number — Blend factor 0-1.

Returns Color — Blended sRGB color.

local plain = color.mixRgb(a, b, 0.5)

typed/builtin//modules/api/engine/color/color/oklch

color.oklch(l: number, c: number, h: number) -> Color

Build a color from Oklch perceptual color space (l: 0-1, c: 0-0.4, h: 0-360). Ideal for perceptually uniform gradients and color manipulation.

Parameters

• l number — Lightness (0-1).
• c number — Chroma / saturation (0-0.4).
• h number — Hue (0-360).

Returns Color — sRGB color table { r, g, b, a = 1 }.

local accent = color.oklch(0.7, 0.15, 30)

typed/builtin//modules/api/engine/color/color/rgb

color.rgb(r: number, g: number, b: number) -> Color

Build an sRGB color from CSS-style 0-255 RGB channels. Alpha defaults to 1. Channels are normalised to 0-1 on the way out so the result composes with every other color helper.

Parameters

• r number — Red channel (0-255).
• g number — Green channel (0-255).
• b number — Blue channel (0-255).

Returns Color — sRGB color table { r, g, b, a = 1 }, normalised to 0-1.

local red = color.rgb(255, 0, 0)

typed/builtin//modules/api/engine/color/color/rgba

color.rgba(r: number, g: number, b: number, a: number) -> Color

Build an sRGB color from CSS-style 0-255 RGB channels with explicit alpha. RGB are normalised to 0-1; alpha is taken as-is in the 0-1 range.

Parameters

• r number — Red channel (0-255).
• g number — Green channel (0-255).
• b number — Blue channel (0-255).
• a number — Alpha (0-1).

Returns Color — sRGB color table { r, g, b, a }.

local halfRed = color.rgba(255, 0, 0, 0.5)

typed/builtin//modules/api/engine/color/color/rotateHue

color.rotateHue(c: Color, degrees: number) -> Color

Rotate the hue of a color by a given number of degrees in Oklch space.

Parameters

• c Color — Input color.
• degrees number — Hue rotation (positive or negative).

Returns Color — Hue-rotated sRGB color.

local triadic = color.rotateHue(base, 120)

typed/builtin//modules/api/engine/color/color/saturate

color.saturate(c: Color, amount: number) -> Color

Increase the chroma (saturation) of a color in Oklch space.

Parameters

• c Color — Input color.
• amount number — Chroma increase (typically 0-0.2).

Returns Color — More saturated sRGB color.

local pop = color.saturate(base, 0.05)

typed/builtin//modules/api/engine/color/color/toHex

color.toHex(c: Color) -> string

Convert a color to a hex string. Returns "#rrggbb" or "#rrggbbaa" if alpha is not 1.

Parameters

• c Color — Input color.

Returns string — Hex color string.

print(color.toHex(color.rgb(255, 136, 0))) -- "#ff8800"

typed/builtin//modules/api/engine/color/color/toHsl

color.toHsl(c: Color) -> HslColor

Convert a color to HSL.

Parameters

• c Color — Input color.

Returns HslColor — HSL color table { h, s, l, a } (h: 0-360, s/l: 0-1).

local hsl = color.toHsl(base)

typed/builtin//modules/api/engine/color/color/toLinear

color.toLinear(c: Color) -> Color

Convert a color from sRGB to linear RGB space — useful for GPU calculations that need linear-space values.

Parameters

• c Color — Input sRGB color.

Returns Color — Linear RGB color table.

local gpu = color.toLinear(base)

typed/builtin//modules/api/engine/color/color/toOklch

color.toOklch(c: Color) -> OklchColor

Convert a color to Oklch perceptual color space.

Parameters

• c Color — Input color.

Returns OklchColor — Oklch color table { l, c, h, a } (l: 0-1, c: 0-0.4, h: 0-360).

local okl = color.toOklch(base)

typed/builtin//modules/api/engine/color/color/withAlpha

color.withAlpha(c: Color, a: number) -> Color

Return a copy of a color with a different alpha value.

Parameters

• c Color — Input color.
• a number — New alpha (0-1).

Returns Color with modified alpha.

local ghost = color.withAlpha(base, 0.3)