ui

INFO

Сам справочник на английском: он создаётся автоматически из WIT-файлов.

Mod UI on the client (IG-HUD, IG-ModUI): HUD widgets, toasts, notices and dialogs. Mods send data, the loader draws it with its own kit: mods cannot restyle it, place widgets freely or take focus away from the game. Needs no permission, and players can hide any mod's widgets. Server-side hosts and clients without a UI return api-error::unsupported. Added in 0.3. Dialog results arrive as a custom event named <mod-id>:ui-action (subscribe with events.subscribe-custom), delivered to the mod that opened the dialog only; the payload is a types.value map {"dialog": u32, "button": u32, "text": string or null} (button counts from 0, null text when the dialog has no field). Closing the dialog from the loader side (back, the game leaving the world) is button 4294967295.

Package blockheads:api@0.3.1 · Lua table bh.ui · WIT source

Uses: types.{api-error}

Types

slot enum

Where a HUD widget goes. The loader stacks the widgets of a slot, keeps the game's own HUD and the screen cutout clear and hides what does not fit.

Case	Description
top-left	Under the game's HUD, top left.
top-right	Top right.

widget-kind enum

What a HUD widget looks like.

Case	Description
text	One line of text (with an optional icon).
counter	An icon and a number: text holds the number.
panel	A small panel: title and up to four lines of text (split on newlines).

widget record

One HUD widget. Updating a widget with the same id replaces it.

Field	Type	Description
slot	slot
kind	widget-kind
icon	option<string>	A kit icon name: coin, heart, info, warn, check, cross, bell or clock (more are added over time). Unknown names draw no icon.
title	option<string>	The panel title (ignored by the other kinds).
text	string	The text, at most 256 bytes.

notice-level enum

How a notice looks.

Case	Description
info
warning
success
error

button-kind enum

How a dialog button looks.

Case	Description
primary
secondary
danger

dialog-button record

One dialog button.

Field	Type	Description
label	string	At most 24 bytes.
kind	button-kind

field record

The single text field of a dialog.

Field	Type	Description
placeholder	string
initial	string
max-length	u32	At most 200.

dialog record

A dialog: title, text, an optional field and one to three buttons.

Field	Type	Description
title	string	At most 64 bytes.
text	string	At most 512 bytes.
field	option<field>
buttons	list<dialog-button>

Functions

set-widget function

set-widget: func(id: string, widget: widget) -> result<_, api-error>;

Shows or updates a widget. id is 1 to 32 characters of a-z0-9_.-, unique within the mod; a mod has up to 16 widgets.

remove-widget function

remove-widget: func(id: string) -> bool;

Removes a widget. Returns false if it did not exist.

toast function

toast: func(text: string) -> result<_, api-error>;

A short message that stacks bottom right (at most three visible, about four seconds each). text is at most 200 bytes.

notice function

notice: func(text: string, level: notice-level) -> result<_, api-error>;

A notice in the top centre, one at a time (a new one replaces the last). text is at most 200 bytes.

show-dialog function

show-dialog: func(dialog: dialog) -> result<u32, api-error>;

Opens a dialog (one at a time per mod) and returns its id. The answer comes as a <mod-id>:ui-action event.

close-dialog function

close-dialog: func(id: u32) -> bool;

Closes a dialog of the mod without an answer. Returns false if it was not open.