Overlay Scenes

A scene is a HUD you lay out visually in the scene builder. It is saved on the macro, the same way a function or a recording is, so a script shows one by name instead of rebuilding it widget by widget.

Ui.Overlay.showScene("hud");
Ui.Overlay.showScene("hud", true);           // keep it up after the macro ends
Ui.Overlay.showScene("hud", { keep: true }); // same thing, spelled out

// Scene.show(...) and showScene(...) are aliases.
Scene.show("hud");
showScene("hud");

// Once it is up, widgets answer to the name they were given in the builder.
Ui.Overlay.ref("score").setText("Score: " + getVar("score"));

Ui.Overlay.hideScene("hud");   // one scene
Ui.Overlay.hideScene();        // every scene this macro drew

`Ui.Overlay.showScene(name, keepOrOpts?)`

Draw a designed scene. A bare true is the keep switch; an object takes { keep }.

Ui.Overlay.showScene('demo', 'demo');

`Ui.Overlay.hideScene(name?)`

Remove one scene, or every scene this macro drew when the name is omitted. An unknown name warns and returns false.

Ui.Overlay.hideScene('demo');

`Ui.Overlay.sceneExists(name)`

Whether this macro has a scene by that name.

let result = Ui.Overlay.sceneExists('demo');
console.log(result);

`Ui.Overlay.scenes()`

Every scene as [{ name, widgets }].

let result = Ui.Overlay.scenes();
console.log(result);

`Ui.Overlay.sceneNames()`

Just the names.

let result = Ui.Overlay.sceneNames();
console.log(result);

`Scene.show/hide/exists/list/names`

Aliases of the five above.

Scene.show/hide/exists/list/names;

Notes

The name is case-insensitive and matches what the scene is called in the builder.
On showScene, an unknown name throws and lists the macro's scenes. A scene with no widgets logs a warning and returns false.
hideScene with an unknown name only warns and returns false, like the Overlay action's Hide mode.
Scenes are per-macro: a script only ever reaches scenes belonging to the macro it runs in.
Scene widgets can be reached with ref(id) and get(id), and clearAll() removes them too.
%variable% bindings in a scene shown inside a function can read that function's local variables.