Reference

ui global

The retained Menu and HUD and their primitives, generated from the shipped declarations.

Generated from the declarations in @disko-game/build/types. See Menus & HUD for a guide.

The `ui` global

The retained Menu and HUD.

declare const ui: Disko.Ui;

UI

Disko.UiStyle

A frozen style created by ui.style.

interface UiStyle {
    readonly kind: "ui-style";
    readonly declarations: UiStyleDeclarations;
}

Disko.UiStyleDeclarations

Style declarations: sizes in pixels or CSS-like strings, colors as tokens or hex.

interface UiStyleDeclarations {
    readonly [property: string]: string | number | boolean | undefined;
}

Disko.UiTheme

A frozen theme created by ui.theme.

interface UiTheme {
    readonly kind: "ui-theme";
    readonly [token: string]: unknown;
}

Disko.UiRequest

A request to the game when a control is used, created by ui.request.

interface UiRequest {
    readonly __uiRequest: never;
}

Disko.UiLocalCommand

A local client-side command such as ui.open(modal).

interface UiLocalCommand {
    readonly __uiLocalCommand: never;
}

Disko.UiSwap

A content replacement pushed with ui.push.

interface UiSwap {
    readonly __uiSwap: never;
}

Disko.UiNode

A retained UI node.

interface UiNode {
    readonly id: number;
    readonly kind: string;
    readonly options: {
        readonly [option: string]: unknown;
    };
    readonly children: readonly UiNode[];
}

Disko.UiContent

Content accepted wherever children are.

type UiContent = UiNode | readonly UiNode[];

Disko.UiTrigger

A semantic trigger, independent of the input device.

type UiTrigger = "activate" | "submit" | "input" | "change" | "commit" | "drop";

Disko.UiTargetReference

A node, or a target relative to the source: itself, its nearest form or slot.

type UiTargetReference = UiNode | "this" | "form" | "slot";

Disko.UiValue

A value carried by UI controls and local commands.

type UiValue = JsonValue;

Disko.UiRequirement

Gates a node on a permission. Recipients without it do not receive the node and its subtree (denied: "hide", the default), or receive them disabled and without server requests (denied: "disable").

type UiRequirement = Permission | {
    readonly permission: Permission;
    readonly denied?: "hide" | "disable";
};

Disko.UiOptions

Options shared by every UI primitive.

interface UiOptions {
    readonly key?: string;
    readonly style?: UiStyle | UiStyleDeclarations;
    readonly accessibleName?: string;
    readonly children?: UiContent;
    readonly on?: {
        readonly [Trigger in UiTrigger]?: UiRequest | UiLocalCommand;
    };
    readonly requires?: UiRequirement;
    readonly text?: string;
    readonly label?: string;
    readonly name?: string;
    readonly alt?: string;
    readonly asset?: PackageAsset | string;
    readonly heading?: number;
    readonly enabled?: boolean;
    readonly visible?: boolean;
    readonly selected?: boolean;
    readonly checked?: boolean;
    readonly open?: boolean;
    readonly dismiss?: "local";
    readonly value?: UiValue;
    readonly drag?: {
        readonly kind: string;
        readonly value?: UiValue;
    };
    readonly drop?: {
        readonly accept: string;
        readonly value?: UiValue;
    };
    readonly [option: string]: unknown;
}

Member	Description
`requires`	Hides or disables this node for players without the permission.
`name`	Form field name.
`alt`	Alternative text of an image.
`[index]`	Direct style properties are accepted beside `style`.

Disko.UiPlayerOptions

Options of a primitive that shows one player.

interface UiPlayerOptions extends UiOptions {
    readonly player: Player;
}

Disko.UiValueSchema

The closed schema of the values a request carries.

type UiValueSchema = {
    readonly type: "null";
} | {
    readonly type: "boolean";
} | {
    readonly type: "integer" | "number";
    readonly minimum: number;
    readonly maximum: number;
} | {
    readonly type: "text";
    readonly maximumBytes: number;
    readonly choices?: readonly string[];
} | {
    readonly type: "list";
    readonly items: UiValueSchema;
    readonly maximumItems: number;
} | {
    readonly type: "record";
    readonly fields: readonly {
        readonly name: string;
        readonly optional?: boolean;
        readonly schema: UiValueSchema;
    }[];
};

Disko.UiSwapMethod

How the response content is placed at the target.

type UiSwapMethod = "replace" | "children" | "append" | "prepend" | "before" | "after" | "remove";

Disko.UiConcurrencyPolicy

type UiConcurrencyPolicy = "drop" | "replace" | "parallel" | "queue";

Disko.UiRequestOptions

Options of ui.request.

interface UiRequestOptions {
    readonly event: string;
    readonly target?: UiTargetReference;
    readonly swap?: UiSwapMethod;
    readonly values?: "none" | "control" | "form";
    readonly triggerPolicy?: "immediate" | {
        readonly type: "immediate";
    } | {
        readonly type: "debounce" | "throttle";
        readonly millis: number;
    };
    readonly concurrency?: UiConcurrencyPolicy | {
        readonly type: UiConcurrencyPolicy;
        readonly limit?: number;
    };
    readonly payloadSchema?: UiValueSchema;
    readonly requires?: Permission;
}

Member	Description
`event`	The `ui-request` event name the game receives.
`target`	Where the response goes; defaults to the source (`"this"`).
`swap`	Defaults to `"replace"`.
`values`	Values collected by the client; defaults to `"none"`.
`concurrency`	Defaults to `"queue"` with a limit of one.
`payloadSchema`	Defaults to `{ type: "null" }`.
`requires`	Only players with this permission can use the request; for the others the control is disabled and carries no request.

Disko.UiPrimitive

A UI primitive constructor.

type UiPrimitive = (options?: UiOptions) => UiNode;

Disko.Ui

The retained UI API: Menu, HUD and their primitives.

interface Ui {
    fragment(...children: UiNode[]): UiNode;
    request(options: UiRequestOptions): UiRequest;
    swap(options: {
        readonly target: UiNode;
        readonly method?: UiSwapMethod;
        readonly content?: UiContent;
    }): UiSwap;
    style(declarations?: UiStyleDeclarations): UiStyle;
    theme(tokens?: {
        readonly [token: string]: unknown;
    }): UiTheme;
    menu(content: UiContent, options?: {
        readonly placement?: "viewport-center";
    }): UiNode;
    hud(content: UiContent): UiNode;
    push(swaps: UiSwap | readonly UiSwap[]): void;
    push(player: Player, swaps: UiSwap | readonly UiSwap[]): void;
    remove(target: UiNode): UiSwap;
    show(target?: UiTargetReference): UiLocalCommand;
    hide(target?: UiTargetReference): UiLocalCommand;
    open(target?: UiTargetReference): UiLocalCommand;
    close(target?: UiTargetReference): UiLocalCommand;
    focus(target?: UiTargetReference): UiLocalCommand;
    blur(target?: UiTargetReference): UiLocalCommand;
    reset(target?: UiTargetReference): UiLocalCommand;
    transition(target: UiTargetReference | undefined, value: UiValue): UiLocalCommand;
    box: UiPrimitive;
    stack: UiPrimitive;
    row: UiPrimitive;
    grid: UiPrimitive;
    overlay: UiPrimitive;
    scroll: UiPrimitive;
    slot: UiPrimitive;
    spacer: UiPrimitive;
    text: UiPrimitive;
    richtext: UiPrimitive;
    image: UiPrimitive;
    icon: UiPrimitive;
    shape: UiPrimitive;
    button: UiPrimitive;
    link: UiPrimitive;
    form: UiPrimitive;
    input: UiPrimitive;
    area: UiPrimitive;
    toggle: UiPrimitive;
    slider: UiPrimitive;
    select: UiPrimitive;
    option: UiPrimitive;
    progress: UiPrimitive;
    activity: UiPrimitive;
    status: UiPrimitive;
    alert: UiPrimitive;
    list: UiPrimitive;
    item: UiPrimitive;
    table: UiPrimitive;
    header: UiPrimitive;
    body: UiPrimitive;
    footer: UiPrimitive;
    cell: UiPrimitive;
    modal: UiPrimitive;
    popover: UiPrimitive;
    tabs: UiPrimitive;
    tab: UiPrimitive;
    panel: UiPrimitive;
    disclosure: UiPrimitive;
    flag(options: UiPlayerOptions): UiNode;
    connection(options: UiPlayerOptions): UiNode;
    playerName(options: UiPlayerOptions): UiNode;
}

Member	Description
`menu()`	Sets the Menu, shown while the room is not playing or on Esc.
`hud()`	Sets the HUD of the running match.
`push()`	Publishes swaps to everyone, or only to one player.
`flag()`	A player's country flag; `player` is required.
`connection()`	A player's connection quality; `player` is required.
`playerName()`	A player's name in the room's color with its badge, rendered by the client; the node holds only the player's identity. `player` is required.

The ui global

UI