The scene builder

A scene is a HUD you lay out visually. It is saved on the macro, the same way a function or a recording is, so it travels with the macro and any Overlay action can show it by name.

You reach the builder from an Overlay action, through Open the scene builder or Manage scenes. The scenes list is where you add, rename and reorder them; a macro can hold as many as you like.

The canvas

You are drawing on top of your actual screen, at actual size, so what you see is what the macro will draw. Drag widgets to move them, and use the toolbar for undo and redo. The toolbar itself can be dragged out of the way.

Three panels hang off it: Add for new widgets, Properties for the selected one, and Layers for everything in the scene.

Other screen sizes are handled automatically, so you only place widgets once.

The widgets

Add offers ten:

• Text, a label.
• Panel, a filled box. Usually the background everything else sits on.
• Button, a tappable label.
• Image, one of this macro's templates.
• Progress bar, horizontal or vertical.
• Gauge, an arc dial.
• Sparkline, a rolling line chart that scales itself to whatever numbers you give it.
• Circle and Arrow, simple shapes. The arrow points right; use Rotation to aim it.
• Group, a frame you put other widgets inside.

Making it live

Type a %variable% into a field and the widget follows it while the macro runs. Put %score% in a Text widget's text and it updates whenever the variable changes. The same works for a progress bar's Value, for colours, and for width and height.

Width and height also take 50%, auto, or a %token%, so a bar can be sized from a variable as well as filled from one.

Interaction

Under Interaction, which only applies while the macro runs:

• Tappable, makes the widget accept presses. This is what an Overlay action's Wait mode reads.
• On tap, set variable and to value. The variable is set as soon as the widget is pressed, even mid-macro. The value can be a number, a word, or a sum like %score% + 1 for a counter button.
• Draggable by user and Resizable by user. Where the user leaves it is what the macro reads back. Resizable widgets show a grip in their bottom-right corner while the macro runs.

A widget that responds to touch cuts off its own drop shadow and outside border. Turn off Tappable, Draggable by user and Resizable by user if you need those to show.

Groups

Drag a widget onto a group to add it, or off to remove it. Children are positioned relative to the group, so moving or hiding the group affects them all.

Clip contents cuts off anything sticking out past the group's edge. A group can also be made draggable, and it carries its children with it.

Layout and styling

• Position and size, typed as x, y, width, height, plus Rotation which you can also drag by the handle above the widget.
• Lock in place, a locked widget still shows and runs, but taps and drags in the builder pass through it. Useful for background panels.
• Text, size, colour, alignment, weight, font, italic, line height, letter spacing, max lines and an ellipsis.
• Appearance, a background that is None, Solid or a multi-stop Gradient, plus corner radius, padding and opacity.
• Effects, border width and colour, whether the border sits inside or outside the widget's box, and a shadow. On a text widget the shadow falls on the glyphs, which is what keeps light text readable over a bright game.

Colours are #RRGGBB, or #AARRGGBB for transparency. If something looks see-through unexpectedly, the builder tells you why.

Layers

The Layers panel lists everything in the scene, groups folded. From here you can select, reorder front to back, hide, lock, copy, paste and delete widgets, including ones hidden under others.

Naming

Every widget has a Name (id), and that is what an Overlay action or a script uses to reach it. Names must be unique within a scene and cannot be blank.