Skip to content

Color

The Color class represents an RGBA color with components in the 0-255 range. Color instances are accepted everywhere a color option is accepted, alongside the other formats described below.

Color Formats

Wherever a color option is accepted in the Nutshell API, the following formats are all valid:

Format Example Description
Color instance Color(255, 0, 0) A Color class instance.
Named table { r=255, g=0, b=0, a=255 } RGBA components in 0–255 range. a defaults to 255.
Flat array [255, 0, 0] or [255, 0, 0, 128] RGB or RGBA as a positional list. Alpha defaults to 255.
Hex string "#FF0000" or "#FF000080" 6-digit RGB or 8-digit RGBA hex string. Short forms "#F00" and "#F008" are also accepted.
Hex integer 0xFF0000 or 0xFF000080 24-bit RGB (alpha=255) or 32-bit RGBA integer.

Synopsis

Constructor

Static Methods

Instance Members

Member Type Description
r int Red component, 0-255.
g int Green component, 0-255.
b int Blue component, 0-255.
a int Alpha component, 0-255.

Instance Methods

Static Members

Constructor

Color()                       // white: Color(255, 255, 255, 255)
Color(r, g, b)                // opaque color from components
Color(r, g, b, a)             // color with explicit alpha
Color("#FF6400")              // from 6-digit hex string
Color("#FF640080")            // from 8-digit hex string (with alpha)
Color("#F64")                 // from 3-digit shorthand
Color(0xFF6400)               // from RGB hex integer (alpha = 255)
Color(0xFF640080)             // from RGBA hex integer
Color({ r=255, g=100, b=0 })  // from table
Color([255, 100, 0])          // from flat array
Color(otherColor)             // copy from another Color instance

The constructor accepts any of the formats listed in Color Formats as well as separate r, g, b[, a] components.

Static Methods

Color.from_hsv(h, s, v[, a])

Creates a Color from HSV (Hue, Saturation, Value) coordinates.

Parameters:

Parameter Type Required Description
h float Yes Hue, 0-360 degrees.
s float Yes Saturation, 0.0-1.0.
v float Yes Value (brightness), 0.0-1.0.
a int No Alpha, 0-255. Default: 255.
  • Returns: Color

Instance Methods

color.lerp(other, t)

Returns a new Color linearly interpolated between this color and other.

Parameters:

Parameter Type Required Description
other color value Yes The target color. Accepts any color format.
t float Yes Blend factor, 0.0 (this color) to 1.0 (other color).
  • Returns: Color

color.with_alpha(a)

Returns a new Color identical to this one but with a different alpha value.

Parameters:

Parameter Type Required Description
a int Yes New alpha component, 0-255.
  • Returns: Color

color.to_hex()

Returns a hex string representation of the color. Alpha is included only when it is not 255.

  • Returns: string "#RRGGBB" or "#RRGGBBAA"

Static Members

Color Constants

Constant Type Description
Color.AliceBlue string
Color.AntiqueWhite string
Color.Aqua string
Color.Aquamarine string
Color.Azure string
Color.Beige string
Color.Bisque string
Color.Black string
Color.BlanchedAlmond string
Color.Blue string
Color.BlueViolet string
Color.Brown string
Color.BurlyWood string
Color.CadetBlue string
Color.Chartreuse string
Color.Chocolate string
Color.Coral string
Color.CornflowerBlue string
Color.Cornsilk string
Color.Crimson string
Color.Cyan string
Color.DarkBlue string
Color.DarkCyan string
Color.DarkGoldenRod string
Color.DarkGray string
Color.DarkGreen string
Color.DarkGrey string
Color.DarkKhaki string
Color.DarkMagenta string
Color.DarkOliveGreen string
Color.DarkOrange string
Color.DarkOrchid string
Color.DarkRed string
Color.DarkSalmon string
Color.DarkSeaGreen string
Color.DarkSlateBlue string
Color.DarkSlateGray string
Color.DarkSlateGrey string
Color.DarkTurquoise string
Color.DarkViolet string
Color.DeepPink string
Color.DeepSkyBlue string
Color.DimGray string
Color.DimGrey string
Color.DodgerBlue string
Color.FireBrick string
Color.FloralWhite string
Color.ForestGreen string
Color.Fuchsia string
Color.Gainsboro string
Color.GhostWhite string
Color.Gold string
Color.GoldenRod string
Color.Gray string
Color.Green string
Color.GreenYellow string
Color.Grey string
Color.HoneyDew string
Color.HotPink string
Color.IndianRed string
Color.Indigo string
Color.Ivory string
Color.Khaki string
Color.Lavender string
Color.LavenderBlush string
Color.LawnGreen string
Color.LemonChiffon string
Color.LightBlue string
Color.LightCoral string
Color.LightCyan string
Color.LightGoldenRodYellow string
Color.LightGray string
Color.LightGreen string
Color.LightGrey string
Color.LightPink string
Color.LightSalmon string
Color.LightSeaGreen string
Color.LightSkyBlue string
Color.LightSlateGray string
Color.LightSlateGrey string
Color.LightSteelBlue string
Color.LightYellow string
Color.Lime string
Color.LimeGreen string
Color.Linen string
Color.Magenta string
Color.Maroon string
Color.MediumAquaMarine string
Color.MediumBlue string
Color.MediumOrchid string
Color.MediumPurple string
Color.MediumSeaGreen string
Color.MediumSlateBlue string
Color.MediumSpringGreen string
Color.MediumTurquoise string
Color.MediumVioletRed string
Color.MidnightBlue string
Color.MintCream string
Color.MistyRose string
Color.Moccasin string
Color.NavajoWhite string
Color.Navy string
Color.OldLace string
Color.Olive string
Color.OliveDrab string
Color.Orange string
Color.OrangeRed string
Color.Orchid string
Color.PaleGoldenRod string
Color.PaleGreen string
Color.PaleTurquoise string
Color.PaleVioletRed string
Color.PapayaWhip string
Color.PeachPuff string
Color.Peru string
Color.Pink string
Color.Plum string
Color.PowderBlue string
Color.Purple string
Color.RebeccaPurple string
Color.Red string
Color.RosyBrown string
Color.RoyalBlue string
Color.SaddleBrown string
Color.Salmon string
Color.SandyBrown string
Color.SeaGreen string
Color.SeaShell string
Color.Sienna string
Color.Silver string
Color.SkyBlue string
Color.SlateBlue string
Color.SlateGray string
Color.SlateGrey string
Color.Snow string
Color.SpringGreen string
Color.SteelBlue string
Color.Tan string
Color.Teal string
Color.Thistle string
Color.Tomato string
Color.Transparent string
Color.Turquoise string
Color.Violet string
Color.Wheat string
Color.White string
Color.WhiteSmoke string
Color.Yellow string
Color.YellowGreen string

Examples

// Construct from various formats
local red    = Color(Color.Red)
local orange = Color(0xFF6400)
local custom = Color(100, 200, 255, 180)

// Modify alpha at runtime
local faded = red.with_alpha(80)

// Lerp between two colors over time
local blended = Color(Color.Blue).lerp(Color.Red, elapsed_time)

// HSV rainbow cycle
local hue = (elapsed_time * 60.0) % 360.0
local rainbow = Color.from_hsv(hue, 1.0, 1.0)

// Use directly wherever a color is accepted
Canvas.fill_rect(0, 0, 100, 100, { color = rainbow })
font.draw(10, 10, "Hello", { color = faded })

// Convert back to hex string
print(custom.to_hex())  // "#64C8FFB4"