screens

Derived screen-lifecycle helpers on top of the ui.* capability surface. Every operation is computed from ui.listScreens() + ui.hideScreen / ui.showScreen; the module owns no engine state of its own. Deliberately does NOT wrap ui.registerScreen / ui.updateScreen / ui.unregisterScreen — those are capabilities the engine needs to manage directly.

Exports

• M.exists(name: string) -> boolean — does the screen exist in the current snapshot?
• M.visible(name: string) -> boolean — does it exist AND is it currently shown?
• M.toggle(name: string) — flip a visible screen hidden, or a hidden screen visible. Unknown screens are no-ops.
• M.list() -> { ScreenEntry } — pass-through to ui.listScreens().
• M.byName() -> { [string]: ScreenEntry } — same data, map shape.
• M.hideAll() — hide every currently-visible screen.

Types:

• ScreenEntry = { name: string, visible: boolean, layer: number?, hasRoot: boolean? }

Usage

local Screens = require("@builtin::modules.zui.screens")
if Screens.visible("hud") then Screens.toggle("hud") end

Notes

• The screen snapshot is one frame behind on register/update commands — a freshly registered screen returns false from exists until the next frame.
• toggle is a state-driven flip, not a flag write — it reads the current state before deciding to show or hide.
• All operations are safe when the ui global is unavailable; they no-op or return empty values.