Skip to content

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:

OptionValuesDefault
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'
cornerRadiuspoints8
isScrollabletrue to scroll content taller than the panel; needs a fixed panelSizefalse

In the world, about 1360 points make one metre, so [400, 240] is roughly 29 × 18 cm.

Builders ​

BuilderOptions (besides the common ones below)
UI.labeltext (or pass the text as a string), lineLimit (default 1; null wraps freely), textTransform ('uppercase', 'lowercase', 'capitalize')
UI.buttontitle, icon
UI.slidervalue (default 0.5), range: [min, max] or min / max (default 0–1), numberType ('float' or 'integer'), step (0 = continuous)
UI.steppervalue (default 0), range or min / max (default 0–100), step (default 1), label
UI.textFieldtext, placeholder
UI.segmentedControlsegments (array of titles), selectedIndex (default 0)
UI.progressViewprogress from 0 to 1; omit it for a spinner
UI.dividerthickness (default 0.5)
UI.shapeshape (default a rounded rectangle with radius 8)
UI.spacerminLength
UI.vStack, UI.hStackchildren, alignment ('leading', 'center', 'trailing', 'top', 'bottom', 'fill'; default 'center'), distribution ('fill' or 'fillEqually'), spacing (default 8)
UI.zStackchildren, alignment ('center', 'top', 'bottom', 'leading', 'trailing', 'topLeading', 'topTrailing', 'bottomLeading', 'bottomTrailing')

Every builder also takes:

  • name – for lookup with findView
  • sizing – 'auto', 'fill', a number in points, [width, height], or { width, height, maxWidth, maxHeight } to set each axis
  • padding – a number, { horizontal, vertical }, or { top, leading, bottom, trailing }. Sliders, progress views, dividers and spacers can't apply padding; wrap them in a stack
  • offset, 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:

ViewKeys
any viewisHidden, isEnabled, opacity
labeltext
buttontitle
toggle (Switch style)isOn
slidervalue, minimumValue, maximumValue
text fieldtext, placeholder
segmented controlselectedIndex
progress viewprogress

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 = false stops a view taking touches but doesn't dim it. Set opacity as well if it should look disabled.
  • Setting a label's text shows 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);
});
EventViewse.uiValue
tapbutton–
valueChangedslider, segmented controlthe number, or the selected index
toggledtoggle (Switch style)true or false
textChangedtext fieldthe 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 ​

FormReads 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):

FilterUseExample 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%
|timeSeconds → m:ss (or h:mm:ss ≥ 1h)(for 185) 3:05
|intTruncate toward zero0
|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).