Put a variable on screen with the HUD
How to add HUD widgets and panels so the player can see story state, and what each widget kind does.
The HUD is the layer of chips over the stage: a gold count, a suspicion meter, a bag of clues. Each widget binds to one declared variable and shows its live value. Nothing else can go on the HUD, so if you want the player to see it, it has to be a variable first.
Open the right dock, choose the Project tab, then the HUD sub-tab.
Add a widget
Declare the variable
Add it in the Variables sub-tab if it does not exist yet. A meter needs a
number. A list widget needs a list or a multiple-options variable.
Add the widget
Press Add widget. You get a new text widget bound to the first variable
that fits.
Fill in the fields
label is what the player reads beside the value ("Sparks"). type picks the widget kind. source is the bound variable, and the dropdown only offers variables that type is allowed to read.
Finish the type's own field
A meter also asks for range min and range max. An icon-counter asks for an icon, chosen from the built-in catalog.
Check it in the player
Open a preview and watch the value move as Set beats run. See preview.
The widget kinds
| Type | Shows | Binds to |
|---|---|---|
text | the label and the value as plain text | any variable, including a list |
meter | a filled gauge plus the value | anything except a list |
icon-counter | an icon, the label, the value | anything except a list |
list | the label and one row per entry | a list or a multiple-options variable |
A meter fills against its range: at min the bar is empty, at max it is
full, and values outside the range clamp. A zero-width range reads as empty. A
list widget with nothing in the list shows the word "empty" rather than a bare
label.
The widget's source dropdown will not offer a binding the compiler refuses, and if there is no suitable variable at all it says so ("no list variables") rather than letting you type a name. A binding that arrived some other way and does not fit stays visible, marked "(wrong type)".
Show a widget only sometimes
Every widget has a visible when condition, edited with the usual condition editor. Leave it empty and the widget is always on screen. Set it and the widget appears and disappears as the condition flips, checked on every render.
A common shape: bind a meter to suspicion, and set its visible when to
visited("s-heist-briefing"), so the bar only exists once the story has a
reason to show it.
Group widgets into a panel
Anchored chips are for one or two numbers you always want visible. For an
inventory screen or a clue journal, press Add panel, give it a title, then
Add widget to panel. Panel widgets are ordinary widgets, edited the same
way. A fresh one starts as a list widget if the project has a list to bind.
In the player, each panel becomes a backpack button in the control strip, named by the panel's title (the title is the button's tooltip and its accessible name). Pressing it opens the panel over the stage as a dialog; pressing it again closes it. Only one panel is open at a time.
How widgets update
There is no refresh step and no polling. The player renders from the same variable snapshot the runtime advances, so a Set beat that changes the bound variable changes the chip on the next rendered beat. Meter range endpoints resolve the same way, so a meter whose max is bound to a variable rescales as that variable moves.
Two fields exist in the published bundle that the HUD panel does not expose
today: a widget's anchor (which corner it sits in, defaulting to top left) and
its format (raw, integer or percent, defaulting to raw). Meter range
endpoints can be variable-bound in the bundle, but the panel edits them as plain
numbers. See the bundle format.
When it does not compile
The HUD is a common source of compile errors because a widget can be half-configured while you are editing it. The checks that will stop a publish:
- a meter with no range, or an icon-counter with no icon (
INVALID_HUD_WIDGET) - a widget bound to a variable that was never declared (
UNDECLARED_VARIABLE) - a
listwidget bound to something that is not a collection, or a meter or icon-counter bound to one (LIST_TYPE_MISMATCH) - a list-bound widget formatted as
integerorpercent, which would print0forever (INVALID_HUD_WIDGET)
Deleting a variable that a widget binds does not delete the widget. The delete confirmation in the Variables panel counts "a HUD widget" among the uses that will break.