UI: panels, toasts, HUD, titles and sounds
Partly liveThe 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).
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?}, orundefinedwhen closed, timed out (timeoutS, default 60, at most- 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
| Call | Web | Java |
|---|---|---|
ActionBar, Title | the action bar, a title | the same |
Toast(player, text, kind) | a toast naming the experience | the 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 experience | the scoreboard sidebar (only while no other plugin owns the player's scoreboard) |
Sound(player, key) | the sound | the same |
Particles(kind, at, count) | particles | the 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.
