Presentation

cinnabar:extension/presentation@0.1.0

Mod-supplied parameters of native world presentation; requires hud authority, and nonempty per-actor lists also players or entities. Each call replaces this mod’s retained value once the callback succeeds; a callback may make 8 presentation calls, and one more traps it. Limits are the constants in mod_api::presentation.

The client merges loaded mods in load order. The earliest mod that sets a nametag style, a hurt overlay or chat actions owns that policy. For each runtime ID and surface, the earliest mod whose grants admit the actor’s kind owns the row: players need the players grant, other actors the entities grant, and rows a mod’s grants do not admit never apply. Tooltip lines append in load order.

Grants: hud; actor rows additionally require players or entities for their kind.

Imported type rgba: rgba.

Types

nametag-style

Parameters of the native nametag renderer: opacity 0–1, scale 0.5–3, border width 0–8. Text colours replace the native ones when present; annotation spans keep their own.

record nametag-style {
    hide: bool,
    hide-players: bool,
    hide-passengers: bool,
    show-self: bool,
    show-when-hud-hidden: bool,
    opacity: f32,
    scale: f32,
    shadow: bool,
    border-width: f32,
    text-color: option<rgba>,
    own-text-color: option<rgba>,
    border-color: option<rgba>,
    background-color: option<rgba>,
}

Types: rgba.

text-span

Plain single-line text of at most MAX_ANNOTATION_SPAN_BYTES, without style codes.

record text-span {
    text: string,
    color: rgba,
}

Types: rgba.

annotation-position

Where annotation spans go relative to the native name. Spans draw end to end in list order, with nothing inserted between them. before and after extend the name’s first line, and the host inserts exactly one space between the name and the spans; any other separator belongs in the spans. above and below draw the spans on their own centred line above the name’s first line or below its last. A player-list row has one line, so roster spans placed above or below follow the name as after does.

enum annotation-position {
    before,
    after,
    above,
    below,
}

annotation

Text attached to one actor’s eligible nametag and, for a player whose actor the client knows, that player’s player-list row. Each surface holds up to MAX_ANNOTATION_SPANS spans; an empty list leaves that surface native. Nametag spans on the local player also show its own tag. Runtime IDs are nonzero and distinct within one call.

record annotation {
    runtime-id: u64,
    nametag: list<text-span>,
    nametag-position: annotation-position,
    roster: list<text-span>,
    roster-position: annotation-position,
}

Types: annotation-position, text-span.

actor-tint

An overlay tint drawn while the actor is not hurt.

record actor-tint {
    runtime-id: u64,
    color: rgba,
}

Types: rgba.

tooltip-line

One extra item tooltip line of plain text, at most MAX_TOOLTIP_LINE_BYTES; metadata none matches every variant. One item’s tooltip shows at most MAX_ITEM_TOOLTIP_LINES.

record tooltip-line {
    identifier: string,
    metadata: option<u32>,
    text: string,
    color: rgba,
}

Types: rgba.

chat-action

A clickable span: a primary click or tap on text inside a message of the open chat history closes the chat and reports action, with value 1, among input.read-controls events on the owning mod’s next frame; reading it requires controls authority. text is at most MAX_CHAT_ACTION_TEXT_BYTES; action is at most MAX_CHAT_ACTION_ID_BYTES of [A-Za-z0-9_.-].

record chat-action {
    text: string,
    action: string,
}

Functions

set-nametag-style

set-nametag-style: func(style: option<nametag-style>) -> result<_, string>;

Retained; none restores native nametags.

Types: nametag-style.

set-annotations

set-annotations: func(annotations: list<annotation>) -> result<_, string>;

Retained; replaces every annotation from this mod, at most MAX_ANNOTATIONS.

Types: annotation.

set-hurt-overlay

set-hurt-overlay: func(body: option<rgba>, armor: option<rgba>) -> result<_, string>;

Native damage overlay colours for actor bodies and their armour, while an actor is hurt; none keeps native. One policy: the earliest mod setting either colour owns both.

Types: rgba.

set-actor-tints

set-actor-tints: func(tints: list<actor-tint>) -> result<_, string>;

Retained; replaces every tint from this mod, at most MAX_ACTOR_TINTS distinct nonzero runtime IDs.

Types: actor-tint.

set-tooltip-lines

set-tooltip-lines: func(lines: list<tooltip-line>) -> result<_, string>;

Retained; replaces every tooltip line from this mod, at most MAX_TOOLTIP_LINES.

Types: tooltip-line.

set-chat-actions

set-chat-actions: func(actions: list<chat-action>) -> result<_, string>;

Retained; replaces every chat action from this mod, at most MAX_CHAT_ACTIONS. The earliest mod with chat actions owns every clickable span and receives every click.

Types: chat-action.