HUD

cinnabar:extension/hud@0.1.0

The mod’s retained gameplay HUD layer and the vanilla HUD elements around it. Every function except set-label requires hud authority.

Grants: hud, except set-label, which needs no grant.

Types

viewport

The gameplay HUD root in GUI units and the GUI scale.

record viewport {
    width: f32,
    height: f32,
    scale: f32,
}

font

Fonts a surface label can use.

enum font {
    native,
    sans,
}

vanilla-element

Vanilla HUD elements a mod may read and hide.

enum vanilla-element {
    crosshair,
    status-effects,
    sidebar,
    hunger,
}

rect

A rectangle in GUI units from the top left of the HUD root.

record rect {
    x: f32,
    y: f32,
    width: f32,
    height: f32,
}

element-state

Whether vanilla draws the element this frame, ignoring hiding, and where. bounds covers what vanilla draws: the drawn row of shanks for hunger, not its renderer node; the effect icons for status-effects; the cursor for crosshair; the sidebar’s rows for sidebar. None while vanilla lays the element out nowhere.

record element-state {
    element: vanilla-element,
    visible: bool,
    bounds: option<rect>,
}

Types: rect, vanilla-element.

Functions

set-label

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

Replaces this mod’s label. Empty text removes it; invalid text is rejected.

local-message

local-message: func(text: string) -> result<_, string>;

Adds one bounded local-only system chat line after a successful callback.

set-surface

set-surface: func(json: string) -> result<_, string>;

Replaces the mod’s JSON-UI layer, drawn over gameplay below vanilla screens and never hit-tested. The JSON is a bounded surface: screen, document, bindings, collections and transitions, as panel surfaces. Empty text removes the layer.

update-surface

update-surface: func(json: string) -> result<_, string>;

Sparse patch of the current layer; omitted names keep their values. remove_bindings lists bound names to unbind first, each once, none also set by the patch and at most the binding limit; a removed name the document still reads draws as never bound. bindings then replaces every binding, binding_changes sets the named ones and collection_order reorders collections. controls maps top-level control names of the document, without namespace and optionally with an @ base as a document key, to a replacement control object, or to null to remove one. The patched document is validated as set-surface validates a whole one, and only the controls whose resolution reads a replaced definition, embedded ones included, are laid out again.

read-viewport

read-viewport: func() -> option<viewport>;

None before the first laid-out frame.

Types: viewport.

measure-text

measure-text: func(text: string, font: font) -> result<f32, string>;

Width of one line of text in GUI units at text scale 1, as a surface label lays it out.

Types: font.

set-hidden-elements

set-hidden-elements: func(elements: list<vanilla-element>) -> result<_, string>;

Retained; the listed elements are not drawn. An empty list restores them all.

Types: vanilla-element.

read-elements

read-elements: func() -> result<list<element-state>, string>;

The current state of every vanilla element, in enum order.

Types: element-state.