area

Free-positioned area. Root-only — must be the top-level widget of its registered screen. The pos field is at the widget root level (not inside props) because that's what the engine's area decoder expects. Pass movable = true to let the user drag the area; the dragged position is held in egui's persistent memory.

Exports

This module returns the widget factory directly. There is no returned table.

• area(children: { Node }?, opts: AreaOpts?) -> Node — build a free-positioned area node.

Types:

• Pos = { number } — { x, y } in screen pixels.
• Pivot = string — engine-defined anchor name ("center", "topleft", ...).
• Node = { [string]: any } — opaque widget node.
• AreaOpts = { id: string?, pos: Pos?, pivot: Pivot?, movable: boolean?, interactable: boolean?, style: { [string]: any }? }

Usage

local area = require("@builtin::modules.zui.widget.area")

local hud = area({
    Z.btn("Drag me"),
}, {
    pos = { 100, 100 },
    movable = true,
    interactable = true,
})
ui.registerScreen("draggable", hud)

Notes

• The widget MUST be the top-level node of its registered screen.
• pos, pivot, movable, interactable, style are written at the widget root level (NOT inside props) — the engine's area decoder reads them from there.
• Lua-side read-back of dragged position for movable areas is a planned Rust extension; today the dragged position is held in egui's persistent memory and is not exposed back to Luau.
• Each nil field is omitted from the resulting node so the engine sees only the fields the caller explicitly set.