UI Plugin API | Retro Sketch Documentation

Nearly everything in our game engine is custom code from the ground up, including our UI code. We have a special INI-like file for specifying User Interfaces and many other things in the engine. The UI system just so happens to piggy-back off of our unique INI system.

Video tutorial

Please be sure to enable "Hot Reload Plugins" in the settings for this tutorial.

In Lua code, you can specify UI by using a string with INI code within it. You can concatenate various strings together to make a templating system if you'd like. Below is an example of Lua code generating a specification.

local interface = [[
[UI]
  [UI/Main]
  Type=Panel
  Anchor=Center
  Width=300
  Height=300
  LayoutZ=30

    [UI/Main/Button]
    Type=Button
    Anchor=Center
    Width=100
    Height=32
    Text="Click Me!"
]]

local specs = eng_load_ui(eng, interface, rs_ui_group(app))
local btn = eng_ui_find(specs, "UI/Main/Button")

What you'll notice is the multi-line string set to the interface variable. It's actually very similar to INI, but slightly different. You'll notice that there is a base [UI] section that everything is underneath. You'll also notice that children are nested using the "/" character. So [UI/Main] is a child of [UI], and [UI/Main/Button] is a child of [UI/Main].

Note that the tabs and extra new lines are not required, it's just a style I use to keep things organized for myself.

To create a specification for UI, you'll first put the [UI] section at the top of your UI specification string. From here you will need to place each child UI element.

Fields

Any field type marked below surrounded with [] like in [string], means that field is optional. Otherwise, it is required.

Common Spec

Field	Type	Description
Name	`[string]`
UseBlending	`[bool]`
IsDisabled	`[bool]`
Stretch	`[vec4]`
Margin	`[vec4]`
Width	`[number]`
Height	`[number]`
X	`[number]`
Y	`[number]`
Z	`[number]`
LayoutZ	`[number]`	Controls Z-order
Position	`enum`	Valid values are: Relative Static Absolute Fixed Sticky
Anchor	`enum`	Valid values are: TopLeft TopCenter TopRight Left Center Right BottomLeft BottomCenter BottomRight StretchLeft StretchTop StretchRight StretchBottom StretchCenter

Panel Spec (Type: "Panel")

Field	Type	Description
Text	`string`
Justify	`[enum]`	Valid values are: Left Center Right
Baseline	`[enum]`	Valid values are: Top Center Bottom
FGColor	`[color]`
BGColor	`[color]`
FontSize	`[number]`

Button Spec (Type: "Button")

Field	Type	Description
Text	`string`
FGColor	`[color]`
BGColor	`[color]`
FontSize	`[number]`

Checkbox Spec (Type: "Checkbox")

Field	Type	Description
Checked	`[bool]`

Text Input Spec (Type: "Input")

Field	Type	Description
Value	`[string]`
Placeholder	`[string]`
FGColor	`[color]`
BGColor	`[color]`
FontSize	`[number]`

Slider Spec (Type: "Slider")

Field	Type	Description
Value	`[number]`
FGColor	`[color]`
BGColor	`[color]`
Draggable	`[bool]`

Sprite Spec (Type: "Sprite")

Field	Type	Description
Texture	`[string]`
TextureFilter	`[enum]`	Valid values are: Linear Nearest
Frames	`[string[]]`
Color	`[color]`
FPS	`[number]`

Templates

You can create templates to re-use within your UI specification by using the ! character followed by the section you wish to copy.

[Templates]
  [Templates/Label]
  Type=Label
  Anchor=TopLeft
  Width=300
  Height=30
  FontSize=18
  Justify=Center
  Baseline=Bottom

[UI]
  [UI/Main]
  ;...

    [UI/Main/Label1]
    !Templates/Label
    Text="First label"

    [UI/Main/Label2]
    !Templates/Label
    Text="Second label"
    Baseline=Center

When you see !Templates/Label above, you can imagine that all of the fields and their values from that section are copied and pasted into this section. You are free to then override any values you need, such as the Label2 in this case overriding the Baseline field.

References

You can reference any value from another section in the INI by using the & character followed by the section and field. For example:

[Config]
Red=color(1, 0, 0, 1)

;...

[UI/Main]
Type=Panel
;...
Color=&Config.Red

In the above, it will set the Color field of the [UI/Main] section to the value of color(1, 0, 0, 1) as if you directly typed it inline. This is helpful to share values and change multiple values quickly.

Special values

vec2(float, float) - Used to create a 2-dimensional vector. The components are X, Y, or Width, Height respectively.

vec3(float, float, float) - Used to create a 3-dimensional vector. The components are X, Y, Z.

vec4(float, float, float, float) - Used to create a 4-dimensional vector. The components are X, Y, Z, W, or Left, Top, Right, Bottom respectively.

color(float, float, float, float) - Used to create color, the values are expected to be in the range 0.0 to 1.0.

Retro Sketch

Docs Home