Log inGet started
Package

zui.module

Newest version

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

README.md

zui

Deprecated for authoring content. zui predates the engine's CSS-parity ui.* surface and writes unlike CSS, producing flatter results. Author screens as raw widget trees ({ type, style, props, children }) styled with ui.*, and read @builtin::examples.ui.* for complete worked screens. zui remains in use internally by the editor; it will be rebuilt on the CSS-parity core.

Convenience UI library on top of the engine's ui.* Rust bindings. Ships Layer 1 (per-widget builders), Layer 2 (theme tokens), Layer 3 (app lifecycle), router with unhandled-warning, pre-built shells, and debug overlay. The engine's Rust UI surface is the substrate — zui is one library on top of it. Any third-party Lua UI library can build on the same primitives; the engine has no concept of "the zui library", only widget types and a stable contract. See docs/specs/ui-v3-architecture.md.

Exports

Layer 1 (widget builders) — short aliases on Z.*:

  • Z.lbl, Z.btn, Z.icon, Z.iconBtn, Z.iconButton, Z.chip, Z.badge, Z.card, Z.colorSwatch, Z.dialogueBox, Z.kbd, Z.input, Z.codeEditor, Z.slider, Z.dragValue, Z.checkbox, Z.toggle, Z.dropdown, Z.datePicker, Z.radioGroup, Z.selectableList, Z.image, Z.viewport, Z.progressBar, Z.richText, Z.fader, Z.knob, Z.meter, Z.healthBar, Z.hotbar, Z.minimap, Z.hbox, Z.vbox, Z.grid, Z.split, Z.sides, Z.panel, Z.section, Z.scroll, Z.collapsible, Z.window, Z.modal, Z.popup, Z.contextMenu, Z.scene, Z.area, Z.anchor, Z.topPanel, Z.bottomPanel, Z.leftPanel, Z.rightPanel, Z.centralPanel, Z.spacer, Z.flex, Z.sep, Z.plot, Z.graph, Z.dndList, Z.canvas, Z.tabs, Z.tree, Z.filterRow, Z.statRow, Z.statusLabel, Z.node
  • Z.lsp — LSP composite-widget namespace.
  • Z.fs — Filesystem composite-widget namespace.
  • Z.widget — full widget namespace (for explicit access).

Layer 2 (theme tokens):

  • Z.theme — active default token table.
  • Z.themeWith(overrides) — derive a theme with token overrides.
  • Z.themeNames() — list known token names.
  • Z.Theme — the underlying module.

Shared utils (re-exported):

  • Z.round, Z.fmt, Z.fmtVec3, Z.id, Z.eventValue, Z.map, Z.when, Z.compact, Z.Utils.

Layers 3-7 (app lifecycle + advanced features):

  • Z.app(name, builder) — App lifecycle wrapper (Z.App.create).
  • Z.dynamic(list, fn) — one-screen-per-list-item bucket.
  • Z.dataSource(fetchFn, opts) — TTL + gated cached fetcher.
  • Z.highlight — syntax-highlighting dispatch and per-language modules.
  • Z.shell — pre-built shell shapes (docked, canvas, inspector).
  • Z.tags, Z.screens — Luau-owned screen tag registry + lifecycle helpers.
  • Z.defineWidget(name, fn) / Z.unregisterWidget(name) — register Luau builders for raw { type = name, ... } widget tables.
  • Z.widgetState(id, key, default) / Z.widgetState.set(id, key, value) — per-widget reactive state.
  • Z.VERSION, Z.SPEC — version string and spec link.

Usage

local Z = require("@builtin::modules.zui")
local C = Z.theme

local function tree()
    return Z.centralPanel({
        Z.topPanel({
            Z.hbox({
                Z.lbl("◈ MY APP", { color = C.accent, fontSize = 14, bold = true }),
                Z.flex(),
                Z.btn("Save", "save:click", { bg = C.accent, color = C.bg, bold = true }),
            }, { style = { gap = 8, padding = { 6, 12, 6, 12 } } }),
        }),
        Z.section("CONTROLS", {
            Z.slider("vol", 0.5, 0, 1, { onChange = "vol:set" }),
            Z.btn("Reset", "vol:reset"),
        }, { bg = C.panel, border = C.border, padding = { 8, 12, 8, 12 } }),
    })
end

ui.registerScreen("my-app", tree(), 0)
ui.showScreen("my-app")

Notes

  • This module's surface is mostly re-exports: every Z.* widget alias is Widget.* (see widget.module/), every theme alias is Theme.*, every util is Utils.*. The aliases exist for ergonomics only — explicit access via Z.widget, Z.Theme, Z.Utils, etc. works the same way.
  • The module registers a handful of ui.defineWidget handlers at load time (tabs, card, sides, badge, colorSwatch, separator, progressBar, iconButton, dialogueBox, hotbar) so raw { type = "<name>", ... } widget tables in existing demos and editor tools keep rendering after their Rust-side definitions were deleted. Re-running registration on hot-reload is safe — the engine replaces the previous closure.
  • Z.defineWidget requires the engine ui global; off-host execution raises a clear error.
  • Z.widgetState is a callable read path with a .set write sub-method — no metatables on the caller side. Returns the default when the engine global is missing.
  • The library is built on a stable Rust substrate (ui.registerScreen, ui.getToken, ui.defineWidget, etc.). Other Lua UI libraries can build on the same substrate and coexist with zui; the engine has no concept of a privileged library.
  • See docs/specs/ui-v3-architecture.md for the full layered design, Rust binding gaps, and follow-up roadmap.

Tall content inside an anchored panel

A Z.anchor("Center", ...) { Z.panel(rows) } whose rows exceed the viewport will silently clip top + bottom — the player has no scrollbar and no way to reach the off-screen entries. Opt into in-place scrolling on the panel:

Z.anchor("Center", {}, {
    Z.panel(rows, { scroll = true, maxHeight = 480 }),
})

scroll = true wraps the children in a scrollArea so overflow stays reachable. Without scroll = true, maxHeight only clips. See the panel README for scrollMaxHeight, header/footer pinning, and the full pattern (closes #3270).