utils

Small stateless helpers used across the builtin module set: parse a vec3-shaped value into the canonical { x, y, z } map, normalise an id list from string or table input, and coerce a checkbox-shaped value into a strict boolean. No engine dependencies, no module state.

Exports

• M.parseVec3(value: Vec3Like) -> Vec3Map? — parse vec3 from array or map form, returns nil if unrecognised.
• M.normalizeIds(value: IdListInput) -> IdList? — turn a comma/space-separated string or array into { string }.
• M.parseCheckboxValue(data: CheckboxValue, fallback: boolean) -> boolean — coerce bool/string/number/nil to a boolean.

Types:

• Vec3Map = { x: number, y: number, z: number }
• Vec3Like = Vec3Map | { number } — accepted input shape for parseVec3.
• IdList = { string }
• IdListInput = string | IdList — accepted input shape for normalizeIds.
• CheckboxValue = boolean | string | number | nil

Usage

local Utils = require("@builtin::modules.utils")

local v   = Utils.parseVec3({ 1, 2, 3 })           -- { x = 1, y = 2, z = 3 }
local ids = Utils.normalizeIds("a, b, c")          -- { "a", "b", "c" }
local on  = Utils.parseCheckboxValue("true", false) -- true

Notes

• Pure functions — no side effects, no engine calls. Safe to call at module load time or from any context.
• parseVec3 always returns the map form ({ x, y, z }) regardless of whether the input was an array or a map. Callers downstream that expect a particular shape should rely on the map form.
• normalizeIds returns the input table unchanged when it is already a table — it does not validate that each entry is a string.