ui Module

Public Luau surface over the __ui Internal FFI namespace — the egui-backed UI system's full Luau-facing surface.

Purpose

Wrap the raw __ui.* FFI namespace in a typed Luau table that gets auto-injected as _G.ui via the prelude. Covers screens, styles, themes, widget introspection, input simulation, scroll / area / layout, per-widget responses, focus, validation, custom-widget builders, and per-widget cross-frame state.

Higher-level Luau libraries (zui, Z.tags, Z.theme, ...) build composable surfaces on top of these primitives.

Usage

-- Register a screen
ui.registerScreen("hud", {
    type = "panel",
    children = {
        { type = "label", props = { text = "Score: 0" }, id = "score" },
    },
})

-- Read responses + drive focus
local r = ui.response("score")
if r and r.clicked then ui.focus("score-input") end

-- Themes + styles
ui.setTheme("dark")
ui.defineStyle("button.primary", { bg = "#3b82f6", padding = 8 })

-- Custom widget kinds
ui.defineWidget("badge", function(props, children)
    return { type = "label", props = { text = "[" .. props.text .. "]" } }
end)

-- Per-widget state (cross-frame, screen-scoped)
ui.widgetStateSet("filterBar", "active", true)
print(ui.widgetState("filterBar", "active"))

Exports

• Screens: registerScreen, updateScreen, showScreen, hideScreen, unregisterScreen / removeScreen, listScreens, getScreenTree, screen, captureWindow.
• Styles + themes: defineStyle, defineStyles, useStyles, setTheme, getTheme, listThemes, registerTheme, getToken, getTokens.
• Widget introspection: getWidgetTypes, getWidgetProps.
• Input simulation: click, scroll.
• Background shaders: registerBackgroundShader, setShaderUniforms.
• Scroll / area / layout: setScrollPosition, getAreaPos, setAreaPos, getLayoutInfo.
• Dock arrangement: getDockLayout, getPersistentDockLayout, setDockWindowRect.
• Responses + focus: response, focus, blur, focusedWidget.
• Validation: lastValidation.
• Custom widgets + state: defineWidget, unregisterWidget, widgetState, widgetStateSet, widgetStateClear.