The color util in my engine code

color.lua

--[[
    Copyright 2026 Sheepolution

    Permission is hereby granted, free of charge, to any person obtaining a copy
    of this software and associated documentation files (the “Software”), to deal
    in the Software without restriction, including without limitation the rights
    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
    copies of the Software, and to permit persons to whom the Software is
    furnished to do so, subject to the following conditions:
	
    The above copyright notice and this permission notice shall be included in
    all copies or substantial portions of the Software.
	
    THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
    WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
    CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

    Example usage:

    -- require
    local Color = require "color"

    -- Draw red
    love.graphics.setColor(Color.red)

    -- Draw translucent red
    love.graphics.setColor(Color.red:alpha(.5))

    -- Convert color to hex
    local hex = Color.red:toHex()

    -- Add a color
    Color.addColors({
        health = {55, 166, 33},
        damage = "#8c0707"
    })

    love.graphics.setColor(Color.health)

    -- Convert colors
    local my_color = Color.toHex(Color.from255(26, 100, 173))
    local r, g, b, a = Color.to255(Color.fromHex("#1a64ad", true))
]]

local palette = {
    red = { 255, 0, 0 },
    blue = { 0, 0, 255 },
    green = { 0, 255, 0 },
    pink = { 255, 0, 255 },
    cyan = { 0, 255, 255 },
    yellow = { 255, 255, 0 },
    orange = { 255, 255 / 2, 0 },
    cyangreen = { 0, 255, 255 / 2 },
    lime = { 255 / 2, 255, 0 },
    purple = { 255 / 2, 0, 255 },
    hotpink = { 255, 0, 255 / 2 },
    lightred = { 255, 100, 100 },
    darkred = { 100, 24, 24 },
    lightgreen = { 100, 255, 100 },
    lightblue = { 100, 100, 255 },
    white = { 255, 255, 255 },
    lightgray = { 200, 200, 200 },
    gray = { 255 / 2, 255 / 2, 255 / 2 },
    darkgray = { 24, 24, 24 },
    black = { 0, 0, 0 },
    transparent = { 0, 0, 0, 0 },
}

local ColorMeta = {}

local PaletteColorMeta = {}

function PaletteColorMeta:__newindex(k)
    if #k == 1 and ("rgba"):find(k) then
        error(string.format("Color '%s' is read-only.", k))
    end

    error("Can't assign new properties to color.")
end

function PaletteColorMeta:__index(c)
    if c == "r" then
        return self[1]
    elseif c == "g" then
        return self[2]
    elseif c == "b" then
        return self[3]
    elseif c == "a" then
        return self[4] or 1
    elseif PaletteColorMeta[c] then
        return PaletteColorMeta[c]
    end

    error(string.format("Color '%s' does not exist.", c))
end

function PaletteColorMeta:__call(r, g, b, a, unpacked)
    if not r then
        return self[1], self[2], self[3], self[4] or 1
    end

    if r == true then
        return self[1] or r, self[2] or g, self[3] or b, self[4] or a
    elseif unpacked then
        return self[1] or r, self[2] or g, self[3] or b, self[4] or a
    else
        return { self[1], self[2], self[3], self[4] or 1 }
    end
end

function PaletteColorMeta:red(v, unpacked)
    if unpacked then
        return v, self[2], self[3], self[4] or 1
    end

    return { v, self[2], self[3], self[4] or 1 }
end

function PaletteColorMeta:green(v, unpacked)
    if unpacked then
        return self[1], v, self[3], self[4] or 1
    end

    return { self[1], v, self[3], self[4] or 1 }
end

function PaletteColorMeta:blue(v, unpacked)
    if unpacked then
        return self[1], self[2], v, self[4] or 1
    end

    return { self[1], self[2], v, self[4] or 1 }
end

function PaletteColorMeta:alpha(v, unpacked)
    if unpacked then
        return self[1], self[2], self[3], v
    end

    return { self[1], self[2], self[3], v }
end

function PaletteColorMeta:toHex()
    return ColorMeta.toHex(self[1], self[2], self[3], self[4])
end

function PaletteColorMeta:to255()
    return ColorMeta.to255(self[1], self[2], self[3], self[4])
end

function PaletteColorMeta:clone()
    return setmetatable({ self[1], self[2], self[3], self[4] or 1 }, PaletteColorMeta)
end

local unpack_colors = function(r, g, b, a)
    local unpacked = type(r) == "number"
    if unpacked then
        return r, g, b, a, true
    end

    return unpack(r)
end

function ColorMeta:__index(k)
    local color = palette[k]
    assert(color, string.format("Color '%s' does not exist.", k))

    return color
end

function ColorMeta:__call(r, g, b, a)
    if type(r) == "string" then
        return ColorMeta.fromHex(r)
    end

    return ColorMeta.from255(r, g, b, a)
end

function ColorMeta.toHex(r, g, b, a)
    r, g, b, a = unpack_colors(r, g, b, a)

    if a then
        return string.format("#%02x%02x%02x%02x", r * 255, g * 255, b * 255, a * 255)
    end

    return string.format("#%02x%02x%02x", r * 255, g * 255, b * 255)
end

function ColorMeta.fromHex(hex, unpacked)
    local r, g, b, a =
        tonumber(hex:sub(2, 3), 16),
        tonumber(hex:sub(4, 5), 16),
        tonumber(hex:sub(6, 7), 16),
        tonumber(hex:sub(8, 9), 16)

    assert(r and g and b, string.format("Invalid hex '%s'", hex))
    if a == nil then a = 255 end

    r, g, b, a = r / 255, g / 255, b / 255, a / 255
    if unpacked then
        return r, g, b, a
    end

    return { r, g, b, a }
end

function ColorMeta.to255(r, g, b, a)
    local unpacked
    r, g, b, a, unpacked = unpack_colors(r, g, b, a)
    r, g, b, a = r * 255, g * 255, b * 255, a and a * 255 or nil
    if unpacked then
        return r, g, b, a
    end

    return { r, g, b, a }
end

function ColorMeta.from255(r, g, b, a)
    local unpacked
    r, g, b, a, unpacked = unpack_colors(r, g, b, a)
    r, g, b, a = r / 255, g / 255, b / 255, a and a / 255 or nil
    if unpacked then
        return r, g, b, a
    end

    return { r, g, b, a }
end

function ColorMeta.addColors(colors)
    for k, color in pairs(colors) do
        if type(color) == "string" then
            color = ColorMeta.fromHex(color)
        end

        for i, n in ipairs(color) do
            color[i] = n / 255
        end

        color[4] = color[4] or 1

        palette[k] = setmetatable(color, PaletteColorMeta)
    end
end

function ColorMeta.addColor(name, color)
    ColorMeta.addColors({ [name] = color })
end

ColorMeta.addColors(palette)

return setmetatable({
    to255 = ColorMeta.to255,
    from255 = ColorMeta.from255,
    toHex = ColorMeta.toHex,
    fromHex = ColorMeta.fromHex,
    addColors = ColorMeta.addColors,
}, ColorMeta)