Panel

cinnabar:extension/panel@0.1.0

An opt-in retained settings panel, rendered and hit-tested by the host.

Grants: controls.

Types

event

One numeric control event routed to its owning mod by control ID.

record event {
    id: string,
    value: f32,
}

panel-layout

Where this mod’s panel lies over the HUD root as last laid out: the panel root’s width and height in panel units, scale, the HUD GUI units one panel unit spans, which follows the GUI scale and a reference_size fitted to a small window, and offset, the panel root’s top left in HUD GUI units from the HUD root’s top left. The pointer of input.read-controls at p lies at (p - offset) / scale in panel units.

record panel-layout {
    width: f32,
    height: f32,
    scale: f32,
    offset: tuple<f32, f32>,
}

Functions

open

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

Opens this instance’s panel on successful callback return. Requires controls authority and retained or pending panel content. Repeated opens keep it open. The latest opener owns input and closes other owners. Opening keys belong to the mod.

close

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

Closes this instance’s panel on successful callback return. Requires controls authority. Repeated closes keep it closed; content remains available for a later open.

toggle

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

Flips this instance’s requested visibility, including earlier requests in this callback. Uses the same authority, content and successful-return rules as open and close.

set-content

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

Bounded panel JSON; empty text removes the panel and releases its input. A cinnabar_hud_control node draws a named control of this mod’s HUD surface, centred: its laid-out box fitted to the node, or at scale times its HUD size, or with fit, its painted ink filling that fraction of the node, at most max_scale times its HUD size.

update-content

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

Applies a bounded sparse control patch and registered surface route atomically. A route change keeps the offset of each scroll view the new surface shares by layout key, clamped to its content. Omitting controls preserves them; bindings, when present, replace custom scalars. The JSON record optionally accepts collection_reveal: {collection: string, item: u32}. The item is its immutable published index, resolved through the accepted collection_order. Each request is consumed once; a filtered-out item is ignored. Optional show_gameplay_hud: bool changes whether the gameplay HUD and mods’ HUD surfaces stay drawn under the open panel; it lasts until changed again or until set-content replaces the panel.

read-layout

read-layout: func() -> option<panel-layout>;

Requires controls authority; none without it and while this mod’s panel is not open.

Types: panel-layout.