UI¶

NexusScript can build and drive a Unity uGUI interface at runtime: a canvas, panels, labels, buttons, sliders, toggles, and input fields. There are two ways in — build it from script with the UI.Create* helpers, or drive existing controls you've placed in the scene and dragged into public fields.

This is screen UI, and it's local

These helpers create a screen‑space overlay on the local player's screen. It's per‑client and not networked — ideal for HUDs, menus, scoreboards, and prompts. To show shared state (everyone's score), read it from an authoritative source (Storage / an NPC action) and render it locally.

Build a UI from script¶

Every UI lives under a Canvas. Create one, then add children to it. Builders return a handle you keep and pass to the control wrappers.

using UnityEngine;
using NexusVM.Unity;

class ScoreHud : NexusBehaviour
{
    Text scoreLabel;

    protected override void Start()
    {
        UI.EnsureEventSystem();                          // needed once for clicks to register
        GameObject canvas = UI.CreateCanvas();           // screen-space overlay

        // CreateLabel(parent, name, text, fontSize, posX, posY, sizeX, sizeY, r,g,b,a)
        scoreLabel = UI.CreateLabel(canvas, "Score", "Score: 0", 28, 0, 400, 300, 60);
        Text.SetColor(scoreLabel, Color.white);

        // CreateButton(parent, name, label, posX, posY, sizeX, sizeY, r,g,b,a)
        Button start = UI.CreateButton(canvas, "Start", "New Game", 0, -300, 200, 60);
        Button.AddClickListener(start, "OnStartClicked");  // calls this script's OnStartClicked()
    }

    public void OnStartClicked()      // public, matched by name
    {
        Debug.Log("Start pressed");
    }

    public void SetScore(int n)
    {
        Text.SetText(scoreLabel, "Score: " + n);
    }
}

Builder	Signature → returns
`UI.CreateCanvas()`	new screen‑space canvas → GameObject
`UI.CreatePanel(parent, name, r,g,b,a)`	colored background Image
`UI.CreateImage(parent, name)`	white Image (set color/sprite after)
`UI.CreateLabel(parent, name, text, fontSize, posX, posY, sizeX, sizeY, r,g,b,a)`	Text
`UI.CreateButton(parent, name, label, posX, posY, sizeX, sizeY, r,g,b,a)`	Button (with child label)
`UI.CreateText(parent)`	bare Text (defaults)
`UI.CreateChild(parent, name)`	empty RectTransform GameObject
`UI.EnsureEventSystem()`	adds an EventSystem so buttons receive input

Positioning & layout helpers: UI.SetRect(comp, posX, posY, sizeX, sizeY), UI.SetAnchors(comp, minX, minY, maxX, maxY, pivotX, pivotY), UI.Stretch(comp), UI.SetParent, UI.SetActive, UI.SetButtonColors, UI.AddRectMask2D.

Coordinates

posX/posY are anchored‑position offsets from the element's anchor (the builders center‑anchor by default, so 0,0 is screen center, +y is up). Sizes are in canvas units against a 1920×1080 reference that scales to the player's screen.

Drive controls you placed in the scene¶

If you'd rather lay UI out visually, expose the controls as public fields, drag them in, and drive them:

public Button fireButton;
public Slider volume;
public Toggle muted;
public Text status;

protected override void Start()
{
    Button.AddClickListener(fireButton, "OnFire");
    Slider.SetValue(volume, 0.8f);
}
public void OnFire() { Text.SetText(status, "Fired!"); }

You can also look controls up by name under a root: UI.FindButton(root, "Fire"), UI.FindText(root, "Status"), UI.GetButton/GetText/GetImage.

The controls¶

Each control is reached through its wrapper class, passing the handle first.

Control	Read / write
Button	`Button.AddClickListener(b, "Method")` · `RemoveAllListeners` · `interactable`
Text	`Text.SetText` / `GetText` · `fontSize` · `color` · `alignment`
Image	`Image.SetColor` / `GetColor` · `fillAmount` (0..1 — health bars, radial fills)
Slider	`value` · `minValue` · `maxValue` · `wholeNumbers` · `interactable` · `onValueChanged`
Toggle	`isOn` · `interactable` · `onValueChanged`
Dropdown	`value` (selected index) · `interactable` · `onValueChanged`
InputField	`text` · `characterLimit` · `readOnly` · `onEndEdit` · `onValueChanged`
ScrollRect	`horizontal` / `vertical` · `horizontalNormalizedPosition` · `verticalNormalizedPosition`
Scrollbar	`value` · `size` · `numberOfSteps` · `interactable`
CanvasGroup	`alpha` (fade a whole panel) · `interactable` · `blocksRaycasts`

// A value-changed handler: the callback name is wired via the control's onValueChanged
public void OnVolumeChanged(float v) { AudioListener.set_volume(v); }  // see Audio guide

// Fade a panel out
CanvasGroup grp = panel.GetComponent<CanvasGroup>();
grp.alpha = Mathf.Lerp(grp.alpha, 0f, Time.deltaTime * 4f);
grp.blocksRaycasts = false;

Layout groups¶

To auto‑arrange children (lists, rows of buttons) instead of hand‑placing them, add a layout group + sizing in the editor and tune from script:

HorizontalLayoutGroup / VerticalLayoutGroup — spacing, childControlWidth/Height, childForceExpandWidth/Height.
LayoutElement — per‑child minWidth/Height, preferredWidth/Height, flexibleWidth/Height, ignoreLayout.
ContentSizeFitter — horizontalFit / verticalFit to size a container to its contents (scrolling lists).

Quick reference¶

Group	Calls
Build	`UI.CreateCanvas` · `CreatePanel` · `CreateImage` · `CreateLabel` · `CreateButton` · `CreateText` · `CreateChild` · `EnsureEventSystem`
Place	`UI.SetRect` · `SetAnchors` · `Stretch` · `SetParent` · `SetActive` · `SetButtonColors` · `AddRectMask2D`
Find	`UI.FindButton` · `FindText` · `GetButton` · `GetText` · `GetImage`
Controls	`Button` · `Text` · `Image` · `Slider` · `Toggle` · `Dropdown` · `InputField` · `ScrollRect` · `Scrollbar` · `CanvasGroup`
Layout	`HorizontalLayoutGroup` · `VerticalLayoutGroup` · `LayoutElement` · `ContentSizeFitter`

→ See the Score HUD recipe for a complete build‑from‑script HUD. Pair with Input & time for keyboard/mouse and Rendering for sprites and colors.