Server experience: UI

cinnabar:server-experience/ui@1.5.0

Host-owned JSON-UI widgets and the bundle’s signed modal screens. Player mods import this interface’s types; its functions are available only to client parts.

Grants: The signed client bundle’s ui permission for widgets and modal_ui for modal mutations; modal-size reads the current admitted modal.

Types

value

A value bound into a screen property, in the forms the JSON-UI engine’s bindings read: numbers carries arrays such as a colour [r, g, b, a] or an offset [x, y].

variant value {
    boolean(bool),
    integer(s64),
    number(f64),
    text(string),
    numbers(list<f64>),
}

gui-size

The size the open modal lays out in, as the vanilla screens’ root does: width and height in GUI units, and scale, the window’s logical pixels per GUI unit (the GUI scale).

record gui-size {
    width: f64,
    height: f64,
    scale: f64,
}

scroll-range

What a scroll view shows along its scrolling axis, in GUI units: how far its content is scrolled (offset, from 0 to content - viewport), the length of its viewport, and the length of its content.

record scroll-range {
    offset: f64,
    viewport: f64,
    content: f64,
}

Functions

set-widget

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

Sets one declared widget’s plain text under this bundle’s UI permission.

open-screen

open-screen: func(template: option<string>) -> result<_, string>;

Opens (or switches to) a template the manifest indexes under templates, as a modal over gameplay; none closes the modal.

close-screen

close-screen: func() -> result<_, string>;

Closes this bundle’s modal screen without selecting another template.

set-collection

set-collection: func(name: string, rows-json: list<u8>) -> result<_, string>;

Replaces a collection’s rows: a JSON array of objects mapping a #binding name to a value ({"type":"bool|integer|number|text|numbers","value":…}).

set-value

set-value: func(name: string, value: value) -> result<_, string>;

Binds one #binding name for the whole screen.

Types: value.

modal-size

modal-size: func() -> option<gui-size>;

This bundle’s open modal’s size, once it has been drawn; none while it is closed or not drawn yet. modal-resized reports each change.

Types: gui-size.

set-text

set-text: func(control: string, text: string) -> result<_, string>;

Sets the text of the open modal’s edit boxes (text_edit_box) whose text_box_name is control, as typing would leave it but cut to the box’s max_length; it does not deliver text-changed. The text holds no control characters other than line breaks.