ui

The ui namespace — 47 functions.

globals/ui/blur

globals/ui/blur()

Surrender keyboard focus from whichever widget currently holds it.

globals/ui/bringAreaToFront

globals/ui/bringAreaToFront(id: string)

Raise a movable area to the top of the window stacking order — the programmatic equivalent of clicking it. egui orders overlapping areas by interaction, so bumping a screen layer alone will NOT bring an unclicked window forward; call this when a taskbar button, focus change, or app launch should bring its window to the front.

globals/ui/captureWindow

globals/ui/captureWindow(screen: string, window: string, opts: CaptureOpts?) -> CaptureResult?

Render a single Window widget to its own offscreen texture and write the result as PNG at /runtime/render_surfaces/<rtHandle>.png. The screen does NOT need to be visible. Returns { rtHandle, texturePath } or nil on invalid inputs (width/height clamped to [1, 8192], defaults 600x400).

globals/ui/click

globals/ui/click(callbackId: string, value: any?)

Simulate a widget click / interaction by its callback id.

globals/ui/defineStyle

globals/ui/defineStyle(name: string, style: StyleProps)

Define a named style. Style keys follow <widgetType>.<className> (e.g. "label.h1", "button.primary") or bare <className> to apply across widget types. Widgets reference styles via the classes (or class) prop.

globals/ui/defineStyles

globals/ui/defineStyles(styles: { [string]: StyleProps })

Define multiple named styles at once.

globals/ui/defineWidget

globals/ui/defineWidget(name: string, builderFn: (WidgetTree, { WidgetTree }) -> WidgetTree)

Register a custom widget kind. When a tree contains { type = name, props = ..., children = ... }, the decoder calls builderFn(props, children) at register / update time and substitutes the returned widget table in place. Errors surface through ui.lastValidation() with codes widget-builder-error / widget-builder-bad-return / decode-recursion-depth-exceeded.

globals/ui/focus

globals/ui/focus(widgetId: string)

Programmatically request keyboard focus on a widget. Queued as a one-shot; the next render of the matching widget calls response.request_focus().

globals/ui/focusedWidget

globals/ui/focusedWidget() -> string?

Return the widget id of whichever widget currently holds keyboard focus, or nil. Snapshotted post-render each frame.

globals/ui/getAreaPos

globals/ui/getAreaPos(id: string) -> AreaPos?

Read the current pivot position of an area widget, including any user drag deltas. Returns { x, y } or nil if the area didn't render this frame.

globals/ui/getAreaSize

globals/ui/getAreaSize(id: string) -> AreaSize?

Read the measured size of an area widget, including any user resize-grip drags if the area is resizable. Returns { w, h } or nil if the area didn't render this frame.

globals/ui/getDockLayout

globals/ui/getDockLayout(id: string) -> string?

Read the current serialized layout (split/tab arrangement) of a dockArea widget as a JSON string. Returns nil if the dockArea didn't render this frame. Persist the string and pass it back via the dockArea's layout prop to restore the arrangement.

globals/ui/getLayoutInfo

globals/ui/getLayoutInfo(widgetId: string?) -> LayoutInfo?

Get layout info (position, size, content bounds) for UI containers. If widgetId is given, returns info for that widget only; otherwise returns all.

globals/ui/getScreenTree

globals/ui/getScreenTree(screenName: string) -> WidgetTree?

Return the last widget tree table passed to registerScreen / updateScreen for screenName.

globals/ui/getTheme

globals/ui/getTheme() -> string

Get the name of the currently active theme.

globals/ui/getToken

globals/ui/getToken(name: string) -> string?

Look up a single design token value from the active theme.

globals/ui/getTokens

globals/ui/getTokens() -> { [string]: string }

Get all design tokens from the active theme as a key-value map.

globals/ui/getWidgetProps

globals/ui/getWidgetProps(typeName: string) -> { WidgetPropDescriptor }?

Get the property definitions for a widget type.

globals/ui/getWidgetTypes

globals/ui/getWidgetTypes() -> { string }

Get all available widget type names that can be used in widget trees.

globals/ui/hideScreen

globals/ui/hideScreen(name: string)

Hide a registered screen.

globals/ui/lastRegistration

globals/ui/lastRegistration() -> { name: string, layer: number? }?

The name and layer passed to the most recent ui.registerScreen call, recorded synchronously at call time. A host that mounts a nested app reads this immediately after the mount to learn which screen the nested code registered, without intercepting the ui table.

globals/ui/lastValidation

globals/ui/lastValidation(screenName: string?) -> any

Validation diagnostics produced at the most recent registerScreen / updateScreen. With no args returns a { [screen] = entry } map; with a name returns that screen's entry or nil. Validation gated by world setting ui.validation = "off" | "warn" | "strict" (default "warn").

globals/ui/listScreens

globals/ui/listScreens() -> { ScreenSummary }

List every registered screen with its current visibility, layer, and whether the screen has a populated root widget tree. Sorted by layer ascending, then name.

globals/ui/listThemes

globals/ui/listThemes() -> { string }

List all registered theme names.

globals/ui/registerBackgroundShader

globals/ui/registerBackgroundShader(shaderHandle: any, width: number?, height: number?)

Register a shader for UI backgrounds. Accepts an asset handle from asset.load(), or legacy (name, wgslSource, width?, height?) for inline source.

globals/ui/registerScreen

globals/ui/registerScreen(name: string, widgetTree: WidgetTree, layer: number?)

Register a named UI screen with a widget tree. Optional layer controls z-ordering (higher = on top). Tag-based grouping lives in Z.tags (Z.tags.set(name, { "editor" }) after register).

globals/ui/registerTheme

globals/ui/registerTheme(name: string, theme: ThemeDefinition)

Register a theme from a flat Luau table. Most callers should use Z.theme.register(name, table) which runs the cascade for them.

globals/ui/removeScreen

globals/ui/removeScreen(name: string)

Alias for ui.unregisterScreen.

globals/ui/resetAreaSize

globals/ui/resetAreaSize(id: string)

Clear a resizable area's remembered size (from a grip drag or ui.setAreaSize) so its declared — or content — size takes over again.

globals/ui/response

globals/ui/response(widgetId: string) -> WidgetResponse?

Per-widget interaction snapshot for the most recent frame. Returns { clicked, hovered, focused, changed, value } where clicked / changed mark transitions and hovered / focused mark current state.

globals/ui/screen

globals/ui/screen(name: string) -> { [string]: any }?

Get a screen proxy with methods like setResolution and rasterize.

globals/ui/screenSize

globals/ui/screenSize() -> { width: number, height: number }

The UI coordinate space as { width, height } (logical points). This is the space area pos, anchors, and getLayoutInfo rects use — and it is NOT the pixel size of a capture screenshot, which may be downscaled. Use this for absolute area positioning (e.g. pinning a menu above a bottom taskbar) instead of guessing the size from a capture image.

globals/ui/scroll

globals/ui/scroll(deltaX: number, deltaY: number)

Simulate a mouse-wheel scroll event on the UI.

globals/ui/setAreaPos

globals/ui/setAreaPos(id: string, x: number, y: number)

Programmatically move a movable area widget to (x, y). Applied for one frame; subsequent frames let drag tracking take over.

globals/ui/setAreaSize

globals/ui/setAreaSize(id: string, w: number, h: number)

Programmatically set a resizable area's size (the user-size override) — for maximize / restore / tile. Persists until the area's declared width/height changes or ui.resetAreaSize(id) clears it.

globals/ui/setScreenRenderLayer

globals/ui/setScreenRenderLayer(name: string, mask: number)

Set a screen's render-layer membership bitmask. A screen draws into a camera or capture only when this mask intersects the camera's include mask — the same rule geometry follows. Content UI defaults to the ui bit; the editor places its chrome on EditorUI so agent captures can drop it. Masks come from __renderLayers.bit(name).

globals/ui/setScrollPosition

globals/ui/setScrollPosition(widgetId: string, offsetY: number)

Set the scroll offset of a scrollArea widget.

globals/ui/setShaderUniforms

globals/ui/setShaderUniforms(name: string, uniforms: { [string]: number })

Set uniform values on a registered background shader.

globals/ui/setTheme

globals/ui/setTheme(name: string)

Switch the active global theme by name.

globals/ui/showScreen

globals/ui/showScreen(name: string)

Make a registered screen visible.

globals/ui/unregisterScreen

globals/ui/unregisterScreen(name: string)

Remove a screen from the registry entirely. Unlike hideScreen, this deletes the entry so it no longer appears in listScreens or render iteration.

globals/ui/unregisterWidget

globals/ui/unregisterWidget(name: string)

Drop a registered custom widget kind. Subsequent references produce an unknown-widget-type diagnostic.

globals/ui/updateScreen

globals/ui/updateScreen(name: string, widgetTree: WidgetTree)

Replace the widget tree of an already-registered screen.

globals/ui/useStyles

globals/ui/useStyles(themeName: string)

Apply a registered style file's classes additively without changing the active theme.

globals/ui/widgetState

globals/ui/widgetState(widgetId: string, key: string, default: any?) -> any

Read per-widget cross-frame state. Returns the value previously written via widgetStateSet, or default (or nil). State is keyed by widget id and persists across re-renders within a screen's lifetime; cleared automatically when the owning screen is unregistered.

globals/ui/widgetStateClear

globals/ui/widgetStateClear(widgetId: string, key: string)

Remove a per-widget state entry.

globals/ui/widgetStateSet

globals/ui/widgetStateSet(widgetId: string, key: string, value: any)

Write per-widget cross-frame state. Replaces any existing value under (widgetId, key). Tables are stored by reference.