0xDocs 0x.limo

Docs / Scripting

UI: panels, toasts, HUD, titles and sounds

Partly live

The ui capability: action bars, titles, sounds, particles, sidebars, panels, toasts and the HUD.

#UI: panels, toasts, HUD, titles and sounds

Capability ui. Typings: Ui, Panel, PanelCard, PanelResult, Hud (packages/script/v1/ui.d.ts).

ts
import { Ui } from "@x1/script";

const r = await Ui.ShowAsync(player, {
  id: "market", title: "Fish market", subtitle: "Sell your catch",
  stat: { label: "Wallet", value: `${balance} SCRIP` },
  tabs: [{ id: "sea", label: "Sea" }, { id: "lake", label: "Lake" }],
  cards: catch.map((f) => ({ id: f.id, title: f.name, icon: "cod", detail: [`${f.kg} kg`], price: f.price, qty: { max: f.count }, tab: f.water })),
  buttons: [{ id: "sell", label: "Sell", style: "primary" }, { id: "close", label: "Close" }],
});
if (r?.button === "sell") sell(player, r.card!, r.qty!);
Ui.Toast(player, "Sold 3 pike for 27 SCRIP", "success");
Ui.Hud(player, { title: "Tournament", lines: ["Your best: 4.2 kg"], progress: 0.6 });

#Declarative, never HTML

A panel is data: a header, tabs, item cards and footer buttons.

  • Web players get the web client's own panel. It has the experience's name in the header, tabs, cards with a picture, details, a price and a badge, a quantity stepper with − + Max and the total, a primary button that waits for a selection, and keys (Esc, Enter, arrows, + −).
  • Java players get the same panel as a chest GUI:
    • tabs in the top row and an info book (title, lines, stat, whose panel);
    • cards as items, 36 a page with page arrows;
    • a quantity screen for cards with a stepper (−10 −5 −1, +1 +5 +10, Max, OK);
    • the buttons in the bottom row.

Every string is plain text. Formatting codes, controls, bidi overrides and resource-pack glyphs are removed, and the web client writes text with textContent only. Every panel, HUD box and toast says which experience sent it. A script can't draw anything that looks like the world's or 0x's own interface.

Panels resolve when the player acts:

  • Ui.ShowAsync → {button, card?, qty?}, or undefined when closed, timed out (timeoutS, default 60, at most
    1. or replaced;
  • Ui.Panel → the button id.

A panel with cards and no buttons resolves with button: "card" when a card is chosen. The host checks the answer against the panel it showed, so a forged answer from a modified client is dropped. That covers an unknown button, a disabled card, or a quantity outside the stepper or off its step.

#The rest

CallWebJava
ActionBar, Titlethe action bar, a titlethe same
Toast(player, text, kind)a toast naming the experiencethe action bar, coloured by kind
Hud(player, hud | null)a HUD box per experience (title, up to 6 lines, a progress bar)a boss bar
Sidebar(player, title, lines)a box per experiencethe scoreboard sidebar (only while no other plugin owns the player's scoreboard)
Sound(player, key)the soundthe same
Particles(kind, at, count)particlesthe same, only inside your regions

Sounds must be in the grant's sounds and particles in its particles; each kind of call must be in the grant's kinds.

#Limits

  • 10 UI calls per second per player per sandbox.
  • 1 title per second per player.
  • 2 panels per second per player per sandbox.
  • One open panel per player: a newer one, from any experience, closes the older one, which resolves undefined.
  • At most 54 cards, 8 tabs, 6 buttons and 12 lines per panel.
  • Each player sees at most 3 HUD boxes and 4 toasts at a time.