UI - Spurdoverse

Your script’s own window in the menu. Declare pages and controls once, the menu builds real widgets and saves their values into the user’s configs.

import ui from "@native/ui";

Two ideas carry the whole module:

Every control is a signal. fov.value is tracked, so a control can feed computed, effect or another control’s prop directly: visible: enabled.
Any prop can be reactive. Give label, visible, items, min, tooltip and friends a value, a function, or a signal / control / hotkey, and it follows.

Declare at the top level, not in tick or render. Everything goes away when the script unloads.

Overview

Layout

page, group, section, row, stack, each.

Controls

switch, slider, range, combo, multi, selector, list, color, input, bind.

Everything else

button, text, separator, image, canvas, menus, tooltips.

Reactivity

signal, computed, effect, batch, untrack.

Hotkeys

key, mode, active, press / release.

Window and dialogs

open, confirm, prompt, snapshot, JSX.

const aim = ui.page("Aim", { icon: "target" }).group("General", { toggle: true, key: "hold" });
const fov = aim.slider("FOV", { min: 1, max: 30, default: 5, unit: "°" });
aim.slider("Smooth", { min: 1, max: 20, visible: () => fov.value > 10 });

on("tick", () => {
    if (aim.value && aim.key?.active) console.log(fov.value);
});

Layout

page

ui.page(title, options?: { id?, icon?, order?, visible? }, build?: (page) => void): Page

A tab. Asking for the same title (or id) again returns the same page; build runs every time. icon is a Tabler icon name, tabs sort by order. page.show() brings it to the front.

ui.page("Main", { icon: "target" }, (page) => {
    page.switch("Enabled");
});

group

container.group(title, options?: GroupOptions, build?: (group) => void): Group

A panel, get-or-create like pages. Without column, a page’s groups split down the middle.

Option
`column`	`"left"` or `"right"`.
`toggle`	A switch in the header: `group.value`, `group.on("change")`, `group.reset()`.
`default`, `persist`, `key`, `onChange`	Like on a switch. Only with `toggle`.

section

container.section(title, options?: { icon?, collapsed?, onToggle? }, build?): Section

A collapsible block with a header. It adds nothing to paths, so moving controls into a section keeps their saved values. section.expanded is readable, writable and reactive.

row, stack

container.row(options?, build?): Row
container.stack(options?, build?): Stack

Children side by side, or one below the other with no chrome. Neither adds to paths.

each

container.each(items: Reactive<T[]>, render: (item, index) => void, options?: { key? }): Stack

Follows a list. render declares an item’s nodes on the same container (they land in the block); items that leave take their nodes with them, new ones render, moved ones move. A string or number key also scopes the item’s paths, so per-item values save.

const players = ui.signal<string[]>([]);
main.each(players, (name) => main.switch(name, { id: name }));
players.value = ["s1mple", "ZywOo"];

Controls

Every container has the same builders. The first argument is the label.

Option	Default
`id`	the label, slugified	The path segment. See paths.
`visible`, `disabled`	`true`, `false`	Reactive.
`tooltip`		Shown on hover. Reactive.
`menu`		A right-click menu, see menus.
`persist`	`true`	`false` keeps the value, and its hotkey, out of configs.
`onChange`		`(value, previous) => void`.

A control has:

Member
`value`	Tracked read; writing updates the menu and the store, then fires `change`.
`peek()`	The value without tracking it.
`default`, `reset()`	The declared default, and going back to it.
`on("change", (value, previous) => ...)`	Also `subscribe(fn)` and `addEventListener`.
`key`	The hotkey, or `null`.
`id`, `alive`, `dispose()`	Path, liveness, removal.

switch

container.switch(label, options?: { default?, style?: "checkbox" | "toggle", key? }): Control<boolean>

const enabled = main.switch("Enabled", { default: true, style: "toggle", key: { key: 0x05, mode: "toggle" } });

slider, range

container.slider(label, options?: { min?, max?, step?, default?, unit?, precision? }): Slider
container.range(label, options?: { min?, max?, step?, default?: [lo, hi], unit?, precision? }): Range

precision: 0 (the default) makes an integer slider. min, max and unit are reactive; the value follows a narrowed range. A range has two handles and a [low, high] value.

const delay = main.range("Delay", { min: 0, max: 300, default: [20, 80], unit: " ms" });
const [low, high] = delay.value;

combo, multi, selector

container.combo(label, items, options?): ListControl
container.multi(label, items, options?): MultiControl
container.selector(label, items, options?: { multi?, layout?: "auto" | "equal" | "wrap" })

The value is the item text (a multi’s: the picked items, in list order); writing takes items or indices. The items type the value: combo("Mode", ["Legit", "Rage"]) is "Legit" | "Rage". items is reactive. A selector draws the same thing as chips.

const mode = main.selector("Mode", ["Legit", "Rage"]);
const bones = main.multi("Bones", ["Head", "Chest", "Pelvis"], { default: ["Head"] });

list

container.list(label, items, options?: { default? }): OrderControl

Chips the user drags into an order; the value is every item, in that order. New items append, the order of the rest is kept.

const priority = main.list("Priority", ["Head", "Neck", "Chest"]);

color, input, bind

container.color(label, options?: { default?: ColorLike, key? }): ColorControl
container.input(label, options?: { default?, placeholder?, maxLength?, filter?: "digits" | "hex" }): Input
container.bind(label, options?: { key?, mode?, onPress?, onRelease? }): Bind

A color reads as a fresh Color. bind is a hotkey on a row of its own; its value is whether it’s active, so visible: panic works.

Buttons, text, images

container.button(label, options?: { style?: "normal" | "accent" | "danger" | "dashed" | "ghost", icon?, onClick? }): Button
container.text(text: Reactive<string>, options?: { tone?, align?, size? }): Text
container.separator(): Separator
container.image(texture: Texture, options?: { width?, height?, rounding?, tint? }): Image

button.click() runs the listeners like a real click. A text never saves.

main.text(() => `FOV ${fov.value}°`, { tone: "muted" });

canvas

container.canvas(options: { height?, width?, animate? }, draw: (g, info) => void): Canvas

A widget you draw yourself. g is render’s API in canvas-local pixels. It redraws when something draw read changes, or every tick with animate: true. info has width, height, hovered, pressed, pointer and time, all tracked. Pointer input comes as events: pointerdown, pointerup, pointermove, pointerenter, pointerleave and wheel, with x, y, button and deltaY.

const level = ui.signal(0.4);
const meter = main.canvas({ height: 24 }, (g, { width, height }) => {
    g.rectFilled([0, 0], [width, height], "#ffffff10", { rounding: 6 });
    g.rectFilled([0, 0], [width * level.value, height], "#e4733f", { rounding: 6 });
});
meter.on("pointerdown", (e) => (level.value = e.x / meter.width));

menus

Any node takes a right-click menu: items with label, icon, danger, disabled, onClick and items for a submenu, and "-" for a separator. Assign null to remove it.

fov.menu = [
    { label: "Reset", icon: "refresh", onClick: () => fov.reset() },
    "-",
    { label: "Presets", items: [{ label: "Legit", onClick: () => (fov.value = 3) }] },
];

Reactivity

A computed, effect or reactive prop re-runs when a value it read changes: a control’s, a signal’s, a hotkey’s active, a section’s expanded, ui.isOpen. It’s glitch-free: one re-run per change, never a half-updated state.

const kills = ui.signal(0);
const deaths = ui.signal(0);
const ratio = ui.computed(() => kills.value / Math.max(deaths.value, 1)); // lazy
ui.effect(() => {
    const timer = setInterval(() => console.log(ratio.value), 1000);
    return () => clearInterval(timer); // cleanup before the next run, and on stop
});
ui.batch(() => { kills.value++; deaths.value++; }); // one re-run, not two
ui.untrack(() => fov.value); // read without tracking

signal.subscribe((value, previous) => ...) listens without an effect. Exceptions in handlers and reactive functions go to the global error event.

Hotkeys

A switch, color or toggle group declared with key has a KeyBind at control.key.

Member
`key`	Win32 virtual-key code, `0` when unbound.
`mode`	`"hold"`, `"toggle"` or `"always"`.
`active` / `value`	Whether it’s active right now. Tracked.
`on("press", fn)`, `on("release", fn)`	When it becomes active and when it stops.

The key option (true, a key code, a mode or { key, mode }) is only a default: once the user binds or clears the key, theirs wins.

Paths and persistence

Saved values are keyed by path: the parent’s path plus the id option or the slugified label. ui.page("Aim").group("Main").slider("FOV") is aim/main/fov. Rows, stacks and sections add nothing.

Two controls on one path throw EEXIST. Give one an id.
Renaming a label moves the path and loses the saved value. Set id when the label may change.
persist: false keeps a value for the session only.
After dispose(), reads and writes throw ESTALE; alive and id still answer.

Window and dialogs

Call
`ui.open()`, `ui.close()`	Opens (once there’s a page) or closes the window.
`ui.isOpen`	A signal: `ui.isOpen.value`.
`ui.title`	The window title, the script’s name until you set it.
`ui.on("open" \| "close" \| "config", fn)`	`config` fires after a config loaded and its changes fired.
`ui.find(path)`, `ui.pages`	Look nodes up. Containers also have `children`, `find()` and iterate.
`ui.snapshot()`, `ui.restore(data)`	Every saved value by path, and back. Presets in one line.
`ui.reset()`	Every control to its default.

Dialogs are the menu’s own modal, as promises. Closing one any other way than OK is a no.

if (await ui.confirm("Reset every setting?", { tone: "danger" })) ui.reset();
const name = await ui.prompt("Preset name", { default: "legit" }); // null when cancelled

JSX

In a .tsx file (the template’s tsconfig already sets "jsxImportSource": "@native/ui") the same tree reads like markup. It’s the same builders underneath.

import ui, { Show, For } from "@native/ui";

const fov = ui.signal(5);
ui.mount(
    <page title="Aim" icon="target">
        <group title="Main" toggle key="hold">
            <slider label="FOV" min={1} max={30} model={fov} />
            <Show when={() => fov.value > 10}>
                <slider label="Smooth" min={1} max={20} />
            </Show>
            <button style="accent" onClick={() => ui.reset()}>Reset</button>
        </group>
    </page>,
);

model binds a control to a signal both ways, ref hands you the node, <For each> is each().

Example

A crosshair with its settings and a live preview.

import ui from "@native/ui";
import render from "@native/render";

const main = ui.page("Crosshair", { icon: "crosshair" }).group("Crosshair", { toggle: true, default: true });
const style = main.selector("Style", ["Cross", "Dot", "Circle"]);
const size = main.slider("Size", { min: 2, max: 40, default: 8, unit: " px" });
const gap = main.slider("Gap", { min: 0, max: 20, default: 3, visible: () => style.value === "Cross" });
const color = main.color("Color", { default: "#40ff40" });

function draw(g: typeof render, x: number, y: number) {
    const s = size.value, d = gap.value, c = color.value;
    if (style.value === "Dot") g.circleFilled([x, y], s / 4, c);
    else if (style.value === "Circle") g.circle([x, y], s, c, { thickness: 1.5 });
    else {
        g.line([x - s - d, y], [x - d, y], c);
        g.line([x + d, y], [x + s + d, y], c);
        g.line([x, y - s - d], [x, y - d], c);
        g.line([x, y + d], [x, y + s + d], c);
    }
}

main.canvas({ height: 90 }, (g, { width }) => draw(g, width / 2, 45));

on("render", () => {
    if (!main.value) return;
    const { x, y } = render.screenSize.scale(0.5);
    draw(render, x, y);
});

Overview

Modules

Types

UI

Overview

Layout

Controls

Everything else

Reactivity

Hotkeys

Window and dialogs

Layout

page

group

section

row, stack

each

Controls

switch

slider, range

combo, multi, selector

list

color, input, bind

Buttons, text, images

canvas

menus

Reactivity

Hotkeys

Paths and persistence

Window and dialogs

JSX

Example