Appearance
User Interface Beta
Build 2D panels – labels, sliders, buttons, stacks – from a script, place them in the scene or pin them to the screen, and drive them from your logic. For text that tracks a variable live, see Live labels below.
Panels built in the editor's UI editor are the same kind of object: a script can find their views by name and change them exactly as described here. For the layout model, the panel settings and how panels render on each device, see the editor's User Interface section.
Build and place a panel
Compose a view tree with the UI.* builders, wrap it with createPanel(...), and instantiate it with scene.createEntity:
javascript
var panel = createPanel(
UI.vStack({
spacing: 12,
children: [
UI.label({ text: 'Volume' }),
UI.slider({ name: 'vol', value: 0.5, range: [0, 1], sizing: { width: 'fill' } })
]
}),
{ panelSize: [320, 160], material: 'system' }
).name('controls');
var entity = await scene.createEntity(
panel.anchor(Anchor.screenSpace({ alignment: 'bottom', insets: 24 }))
);Anchor.screenSpace(...) pins the panel to a screen edge or corner; anchor it in the world instead (e.g. Anchor.position(...)) for a panel that lives in the scene.
Panel options
createPanel(content, options) takes:
| Option | Values | Default |
|---|---|---|
panelSize | 'auto' (hug the content), 'fill' (whole screen, screen-space only), or a size in points: [width, height] or { width, height } | 'auto' |
material | 'system', 'transparent', a hex colour string or { r, g, b } for a solid colour, or { prominence: 'standard' | 'expressive' } for the system material with a prominence | 'system' |
cornerRadius | points | 8 |
isScrollable | true to scroll content taller than the panel; needs a fixed panelSize | false |
In the world, about 1360 points make one metre, so [400, 240] is roughly 29 × 18 cm.
Builders
| Builder | Options (besides the common ones below) |
|---|---|
UI.label | text (or pass the text as a string), lineLimit (default 1; null wraps freely), textTransform ('uppercase', 'lowercase', 'capitalize') |
UI.button | title, icon |
UI.slider | value (default 0.5), range: [min, max] or min / max (default 0–1), numberType ('float' or 'integer'), step (0 = continuous) |
UI.stepper | value (default 0), range or min / max (default 0–100), step (default 1), label |
UI.textField | text, placeholder |
UI.segmentedControl | segments (array of titles), selectedIndex (default 0) |
UI.progressView | progress from 0 to 1; omit it for a spinner |
UI.divider | thickness (default 0.5) |
UI.shape | shape (default a rounded rectangle with radius 8) |
UI.spacer | minLength |
UI.vStack, UI.hStack | children, alignment ('leading', 'center', 'trailing', 'top', 'bottom', 'fill'; default 'center'), distribution ('fill' or 'fillEqually'), spacing (default 8) |
UI.zStack | children, alignment ('center', 'top', 'bottom', 'leading', 'trailing', 'topLeading', 'topTrailing', 'bottomLeading', 'bottomTrailing') |
Every builder also takes:
name– for lookup withfindViewsizing–'auto','fill', a number in points,[width, height], or{ width, height, maxWidth, maxHeight }to set each axispadding– a number,{ horizontal, vertical }, or{ top, leading, bottom, trailing }. Sliders, progress views, dividers and spacers can't apply padding; wrap them in a stackoffset,style,accessibility,isHidden,isEnabled
In style, font has a shorthand: a number for the size, or { size, weight, family }. The other style properties (colours, shape, border, shadow, opacity) are passed through in the format the scene stores them in. For styled panels, design the panel in the editor and change it from a script with findView.
Labels built in a script default to a single line (lineLimit: 1), while labels added in the editor wrap. Pass lineLimit: null for wrapping text.
UI.toggle
UI.toggle is not usable in this runtime version: the panel it is part of fails to load. Build toggles in the editor and reach them from a script with findView.
Find and update views
Name a view, then reach it later through the object's representation to read or change it:
javascript
var view = entity.representation.findView({ name: 'vol' });
view.setProperty('value', 0.8);
// or, with the accessor shorthand:
view.value = 0.8;findView also accepts a view ID as a string or { id }. The editor copies a view's ID with Copy Development ID.
These keys can be read and written:
| View | Keys |
|---|---|
| any view | isHidden, isEnabled, opacity |
| label | text |
| button | title |
| toggle (Switch style) | isOn |
| slider | value, minimumValue, maximumValue |
| text field | text, placeholder |
| segmented control | selectedIndex |
| progress view | progress |
Stepper, image, shape, divider, spacer, web view and the stacks have only the keys every view has. Setting a key a view doesn't have does nothing and logs a warning to the script console.
A few details:
isEnabled = falsestops a view taking touches but doesn't dim it. Setopacityas well if it should look disabled.- Setting a label's
textshows the text as given, without markdown. If the label's authored text contains a${variable}, the next change to that variable draws the authored text again. To update a label continuously, give it a${variable}and change the variable.
React to input
Subscribe to a view's events:
javascript
entity.representation.findView({ name: 'vol' }).on('valueChanged', function(e) {
console.log('slider is now', e.uiValue);
});
entity.representation.findView({ name: 'save' }).on('tap', function() {
scene.setVariable('saved', true);
});| Event | Views | e.uiValue |
|---|---|---|
tap | button | – |
valueChanged | slider, segmented control | the number, or the selected index |
toggled | toggle (Switch style) | true or false |
textChanged | text field | the text |
Every listener receives { uiNodeId, uiInteractionKind, uiValue }.
Taps on labels, images and shapes, and stepper changes, reach a script through an editor event instead: add a UI Interaction event on the object with a Run Script action, and read scriptContext.sourceEvent.uiValue. See Interaction.
Bind a control to a variable
bind connects a view's value to a variable:
javascript
entity.representation.findView({ name: 'vol' }).bind('value', 'volume');For input controls the binding works both ways: the control writes the variable as the user changes it, and the view updates if the variable changes elsewhere. That covers a slider's value, a toggle's isOn, a text field's text and a segmented control's selectedIndex.
For display views it works one way, from the variable to the view: a label's text, a button's title and a progress view's progress. A label or button binding needs a text variable.
Bindings last as long as the panel. Call unbind(property) to remove one sooner. Pass { scope: 'experience' } as the third argument to bind to an experience variable instead of a scene variable.
Pair a bound control with a live label (below) to show its value.
Live labels
Label text supports inline variable references that resolve live – the label re-renders automatically whenever the referenced variable changes. No scene.on('variableChange', …) wiring needed.
javascript
UI.label({ text: 'vol = ${vol}' })${vol} is read from the current scene's variables. If vol is unset, the label renders vol = UNDEFINED.
Scopes
| Form | Reads from |
|---|---|
${name} | Scene variable (default) – set with scene.setVariable(name, value) |
${g:name} | Experience variable, kept across scenes – set with experience.setVariable(name, value) |
Filters
Pipe the value through a formatter with |filter or |filter(arg):
| Filter | Use | Example output (input 0.6789) |
|---|---|---|
|fixed(N) | Trim a float to N decimals (default 2) | 0.68 |
|percent(N) | Multiply ×100, append % (default 0 decimals) | 68% |
|time | Seconds → m:ss (or h:mm:ss ≥ 1h) | (for 185) 3:05 |
|int | Truncate toward zero | 0 |
|signed(N) | Always-signed, N decimals (default 0) | +1 |
Filters are numeric – applied to a non-numeric variable, they pass the raw value through unchanged. An unknown filter name does the same.
Markdown
Label text also supports inline markdown: **bold**, *italic* and `code`. It is applied after variables are filled in, so **${score}** shows the score in bold. Headings, lists, links and strikethrough are not drawn. See Text & Variables.
Example: bound slider with live readout
The slider drives the variable; the label reads from it – no subscription code, the label re-renders on every change automatically:
javascript
// Attach to: On Experience Start
scene.setVariable('vol', 0.5);
var panel = createPanel(
UI.vStack({
spacing: 12,
padding: 16,
children: [
UI.label({ text: 'Volume: ${vol|fixed(2)}' }),
UI.slider({ name: 'volume', value: 0.5 })
]
}),
{ panelSize: [400, 160] }
);
var entity = await scene.createEntity(panel);
entity.representation.findView({ name: 'volume' }).bind('value', 'vol');A single label can mix any number of references and plain text; each reference subscribes independently, so any one variable changing re-renders with the current values of all of them:
javascript
UI.label({ text: 'Score: ${g:score|int} , Timer: ${countdown|time}' })Sizing panels with dynamic labels
An auto-sized panel re-measures itself when its content changes, so a label that starts empty and later fills in with a wider value makes the panel grow to fit. You can seed a readout with a placeholder and replace it once real data arrives without the text being cut off.
A fixed size is still worth choosing when you want the panel to stay put:
javascript
createPanel(content, { panelSize: [340, 200] });A live readout whose value changes width – a counter gaining digits, a place name, a temperature – will otherwise resize its panel each time, which can read as restless if the panel sits in a fixed spot next to other content. Fixed sizing also gives labels room to grow within a stable outline, and is required if you want the panel to be scrollable (isScrollable: true).