rgbm

The rgbm type is the standard color primitive in CSP, consisting of r, g, and b channels plus a mult (multiplier) channel that serves different roles depending on context.

Multiplier Semantics

In UI contexts such as windows and buttons, the mult value typically behaves like an alpha channel in the range 0.0 to 1.0. In lighting or emissive contexts, it represents intensity and may exceed 1.0 to produce HDR bloom or glow effects.

Usage Patterns

Constructors

Initialize a color with specific values or from a hex string.

-- black (0, 0, 0) with mult=0
local c1 = rgbm()

-- solid red (1, 0, 0) with full opacity (1)
local c2 = rgbm(1, 0, 0, 1)

-- create from a hex string
local c3 = rgbm("#FF5500")

Predefined Colors

Access the built-in color palette for quick styling.

local aqua = rgbm.colors.aqua
local black = rgbm.colors.black
local blue = rgbm.colors.blue
local cyan = rgbm.colors.cyan
local fuchsia = rgbm.colors.fuchsia
local gray = rgbm.colors.gray
local green = rgbm.colors.green
local lime = rgbm.colors.lime
local maroon = rgbm.colors.maroon
local navy = rgbm.colors.navy
local olive = rgbm.colors.olive
local orange = rgbm.colors.orange
local purple = rgbm.colors.purple
local red = rgbm.colors.red
local silver = rgbm.colors.silver
local teal = rgbm.colors.teal
local transparent = rgbm.colors.transparent
local white = rgbm.colors.white
local yellow = rgbm.colors.yellow

Component Access

Extract specific channels or convert to other primitives.

local myColor = rgbm(1, 0.5, 0, 1)

local r = myColor.r
local alpha = myColor.mult

-- get the 3-channel rgb version
local base = myColor.rgb

Description

The rgbm type is highly flexible and optimized via FFI. It supports standard mathematical operators (+, -, *, /) and equality checks (==).

Multiplying an rgbm by a number scales all four components, while multiplying by another rgbm performs per-channel multiplication. Like vec3, these are C-style structures; for high-frequency updates, use in-place methods such as :setLerp() instead of arithmetic operators to reduce allocations.

Properties

Property	Type	Description
r	number	Red channel (typically 0–1).
g	number	Green channel (typically 0–1).
b	number	Blue channel (typically 0–1).
mult	number	Multiplier (Alpha or Intensity).
rgb	rgb	Returns the standard 3-channel rgb component.

Common Methods

Method	Description
:luminance()	Returns the perceived brightness of the color.
:hex()	Returns a CSS-style hex string (e.g., #AARRGGBB).
:hsv()	Converts the color to an hsv primitive.
:set(rgb, mult)	Updates the color values in place.
:setLerp(c1, c2, m)	Smoothly blends between two colors in place.

Examples

UI Fading

Using the multiplier as an alpha channel to pulse the opacity of a rectangle.

local myColor = rgbm.colors.blue:clone()

function script.update()
    -- pulse the alpha (mult) between 0.0 and 1.0
    myColor.mult = math.sin(ac.getSim().gameTime) * 0.5 + 0.5
    ui.drawRectFilled(vec2(10, 10), vec2(60, 60), myColor)
end

HDR Lighting

Setting an emissive intensity much higher than 1.0 to create a glow.

local meshes = ac.findMeshes("LIGHT_GLOW")

-- mult of 20.0 makes the color significantly brighter than a standard monitor pixel
local glow = rgbm(1, 0.8, 0.2, 20.0)

meshes:setMaterialProperty("ksEmissive", glow)