Log inGet started
Package

utils.module

Newest version

This package holds more than this page lists. See all of its files in its world.

README.md

utils

Formatting and dispatch helpers shared across zui layers. Anything domain-agnostic and useful both inside zui and to library consumers goes here — numeric formatting (WASM-safe, no string.format dependency), stable hierarchical widget id construction, callback payload unwrap, and small list comprehensions.

Exports

  • M.round(v: number?, decimals: number?) -> number — round to decimals places (default 2). nil → 0.
  • M.fmt(v: number?, decimals: number?) -> string — tostring(round(v, decimals)).
  • M.fmtVec3(vec: Vec3Array?, decimals: number?) -> string — format {x, y, z} as "(x, y, z)".
  • M.id(parent: any, child: any) -> string — stable widget id ("parent/child"); empty parent drops the prefix.
  • M.eventValue(data: EventEnvelope?) -> any — unwrap data.value from v2 event envelopes; pass through raw payloads (nil returns nil).
  • M.map(items: { any }?, fn: (any, number) -> any?) -> { any } — map and drop nils.
  • M.when(cond: any, widget: any) -> any — widget if cond, else nil. Pairs with compact.
  • M.compact(widgets: { any }?) -> { any } — drop nil entries.

Types:

  • Vec3Array = { number } — array form, { x, y, z }.
  • EventEnvelope = { value: any? } | any

Usage

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

Utils.round(1.2345)         -- 1.23
Utils.fmt(1.2345, 1)        -- "1.2"
Utils.fmtVec3({1, 2, 3})    -- "(1.00, 2.00, 3.00)"
Utils.id("toolbar", "save") -- "toolbar/save"

local rows = Utils.map(items, function(r) return Z.lbl(r.name) end)
local kids = Utils.compact{ Z.lbl("a"), Utils.when(showFoo, Z.lbl("foo")) }

Notes

  • Pure module — no engine calls, no module state. Safe to call from any context.
  • round / fmt / fmtVec3 are WASM-safe; they avoid string.format for the rounding step and use repeated multiplication for 10^n.
  • eventValue is the canonical onCallback unwrap — preferred over manual data.value access because it transparently handles the older raw-payload flow too.
  • map / compact / when are the canonical list comprehensions; demos rely on the nil filtering for conditional widgets.