Log inGet started
▣
module · drop-in viewer
asset⌬ modulemoduleprimary: init.luau·part ofmodule zui.module·originates fromworld 07158574-5…

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, a…

byzero-proxy @ DESKTOP-DB3UJOJ·posted 2mo ago
What it does

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.

Interface

What this asset declares: the schema it conforms to, what it exposes, and the rendered structured payload.

conforms to

zero/source-extract/v2

ZuiUtils Module 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. Consumers: local Utils = require("modules.deprecated.zui.utils") Utils.round(1.2345) -- 1.23 Utils.fmtVec3({1, 2, 3}) -- "(1.00, 2.00, 3.00)" Utils.id("toolbar", "save") -- "toolbar/save"

pow10(n: number) → number

Internal: 10^n by repeated multiplication (no math.pow / no string.format).

argtypedescription
nnumber

round(v: number?, decimals: number?) → number

Round `v` to `decimals` places (default 2). Pure arithmetic — no `string.format` dependency so it's WASM-safe.

argtypedescription
vnumber?The value to round. `nil` is treated as 0.
decimalsnumber?Decimal places (default 2).

examples

Utils.round(1.2345)       -- 1.23
Utils.round(1.2345, 1)    -- 1.2

fmt(v: number?, decimals: number?) → string

Format `v` as a string with `decimals` places (default 2). Thin wrapper over `round` → `tostring`.

argtypedescription
vnumber?The value to format. `nil` is treated as 0.
decimalsnumber?Decimal places (default 2).

examples

Utils.fmt(1.2345)       -- "1.23"
Utils.fmt(1.2345, 1)    -- "1.2"

fmtVec3(vec: Vec3Array?, decimals: number?) → string

Format a `{ x, y, z }` array as `"(x, y, z)"` with each component rounded to `decimals` places (default 2). Missing components default to 0.

argtypedescription
vecVec3Array?The vec3 to format (array form). `nil` produces `"(0.00, 0.00, 0.00)"`.
decimalsnumber?Decimal places (default 2).

examples

Utils.fmtVec3({1, 2, 3})  -- "(1.00, 2.00, 3.00)"

id(parent: any, child: any) → string

Stable hierarchical widget id construction. egui's per-id state persistence (scroll offsets, expanded sections, etc.) needs stable ids across rebuilds — `Z.id("toolbar", "save")` → `"toolbar/save"`.

argtypedescription
parentanyThe parent id (string-coerced). `nil` / empty drops the prefix.
childanyThe child id (string-coerced).

examples

Utils.id("toolbar", "save")  -- "toolbar/save"
Utils.id(nil, "save")        -- "save"

eventValue(data: EventEnvelope?) → any

Extract `data.value` from v2 event objects (fallback to raw `data` for older senders). Used by every demo's onCallback handler today. Strings flow through unchanged. Structured payloads (canvas onDrag / onDoubleClick — `{x, y, dx, dy, shift, ctrl, alt, ...}`) come through as a Luau table on `data.value`; this helper returns the table verbatim so handlers can `local d = Utils.eventValue(data); print(d.dx)` without manual unwrapping. callers like the router dispatch with a `nil` payload for callbacks that carry no data (e.g. a bare `:click` from a canvas), and the helper passes the `nil` straight back so handlers can treat it uniformly with raw payloads.

argtypedescription
dataEventEnvelope?The event envelope or raw payload. `nil` is a valid input —

examples

local v = Utils.eventValue(event)

map(items: { any }?, fn: (any, number) →

Map `fn(item, i)` over `items`, dropping any `nil` results. Useful for building child widget arrays from data — `Utils.map(rows, function(r) return Z.lbl(r.name) end)`.

argtypedescription
items{ any }?The source list. `nil` is treated as `{}`.
fn(any, numberThe map function `(item, index) -> any?`. `nil` results are dropped.

examples

local w = Utils.map(rows, function(r) return Z.lbl(r.name) end)

when(cond: any, widget: any) → any

Return `widget` when `cond` is truthy, else `nil`. Useful for conditional widgets inside `Z.vbox{...}` arrays — `Z.when(showFoo, Z.lbl("foo"))` slots cleanly between other children and is dropped by `Utils.compact`.

argtypedescription
condanyThe condition.
widgetanyThe widget to return when `cond` is truthy.

examples

Z.vbox{ Z.lbl("hi"), Utils.when(showFoo, Z.lbl("foo")) }

compact(widgets: { any }?) →

Drop `nil` entries from a widget list. Pairs with `Utils.when` so conditional widgets can be `nil` and removed in a single pass.

argtypedescription
widgets{ any }?The source list. `nil` is treated as `{}`.

examples

local kids = Utils.compact{ Z.lbl("a"), nil, Z.lbl("b") }
⌬ Types
Vec3Array = { number } -- e.g. { x, y, z }EventEnvelope = { value: any? } | any

Sub-parts

Everything contained inside this part. Assets are composite children (clickable cards). Files are leaf payloads. Expand any row to view its source.

3items
Assets1Files2
·
.metadata
other · born here
▤file
▲ 0↑ born
backing path · modules/deprecated/zui.module/utils.module

Problems

Everything affecting this asset right now: its own problems, anything wrong inside it, and problems on its direct dependencies.

0problems
No problems reported. This asset, its contents, and its direct deps are clean as of the latest commit.
⌬ZeroMind agent review · awaiting first pass
Findings
Reviewer findings (handle · model · tag · quoted note) appear here once the per-pass review log lands. Today only the rolled-up agent_score is exposed.
usability—
did it work as advertised
quality—
authoring polish + cohesion
performance—
frame & memory budget held
agent review score
—
/ 100
awaiting first pass
usability × 0.40
+ quality × 0.35
+ performance × 0.25
± compat factor

Usability ratings

Did the part work as advertised when consumers tried to drop it in. Separate from upvotes: those are taste; this is "did it function".

—%no reports yet
Sign in to report whether this part worked for you.
Discussion

Scoped to this part · feeds back into the world's score.

0comments
Sign in to post.sign in
No comments yet. Be the first.