Input

cinnabar:extension/input@0.1.0

Local control edges, available only with explicit controls authority.

Grants: controls, except demo-pressed, which needs no grant.

Imported type event: event.

Types

text-event

A committed native field value addressed by its declared control ID.

record text-event {
    id: string,
    value: string,
}

field-key

A field navigation key with modifiers sampled at the key edge.

record field-key {
    id: string,
    key: string,
    shift: bool,
    control: bool,
    alt: bool,
    super-key: bool,
}

field-event

A native edit, submission or navigation edge; composition remains host-owned.

variant field-event {
    change(text-event),
    submit(text-event),
    key(field-key),
}

Types: field-key, text-event.

controls

One focused input sample; keys and pointer use the host’s coordinate and naming contracts.

record controls {
    seconds: f32,
    focused: bool,
    gameplay: bool,
    panel-open: bool,
    keys-pressed: list<string>,
    keys-held: list<string>,
    keys-admitted: list<string>,
    events: list<event>,
    pointer: option<tuple<f32, f32>>,
    wheel: f32,
}

Types: event.

selection

Selects which fields to copy without changing the underlying frame or its event ordering.

record selection {
    keys-pressed: option<list<string>>,
    keys-held: option<list<string>>,
    keys-admitted: option<list<string>>,
    events: bool,
}

binding-context

The context in which the player assigned a physical chord.

enum binding-context {
    gameplay,
    ui,
}

binding-modifiers

Modifier groups required in addition to the key; either side satisfies a group.

record binding-modifiers {
    shift: bool,
    control: bool,
    alt: bool,
    super-key: bool,
}

action-binding

One player-assigned keyboard or observable mouse-button chord. Multiple rows are alternative bindings. More specific satisfied chords on the same key and context take precedence. Keys use exactly the controls.keys-held naming contract.

record action-binding {
    action: string,
    context: binding-context,
    key: string,
    modifiers: binding-modifiers,
}

Types: binding-context, binding-modifiers.

bindings

A page of the player’s current chords, in settings order. Total is at most MAX_INPUT_BINDINGS; entries has at most MAX_INPUT_BINDINGS_PER_READ rows. Only keyboard keys and MouseLeft/MouseRight/MouseMiddle are observable here; mouse axes, additional buttons, gamepads and built-in touch controls are not in keys-held.

record bindings {
    revision: u64,
    total: u32,
    entries: list<action-binding>,
}

Types: action-binding.

Functions

read-container-screen

read-container-screen: func() -> result<option<string>, string>;

Current open container screen identity, requiring controls permission. None outside containers. Observation does not grant pointer ownership.

position-pointer

position-pointer: func(x: f32, y: f32) -> result<_, string>;

Requests one pointer move in normalized window coordinates (0..1 on each axis). Requires controls permission and a focused container. Staged until callback success; consumed once, discarded if the screen changed. Does not press buttons or capture input.

read-bindings

read-bindings: func(after: option<u64>, offset: u32, limit: u32) -> result<option<bindings>, string>;

Requires controls authority and shares read-controls’ callback read allowance. Offset is 0 through total, and limit is 1 through MAX_INPUT_BINDINGS_PER_READ. Pass the last complete revision to receive none while unchanged. To collect pages, pass none, advance offset by each page’s length and restart at zero if revision changes. Discard old assignments while collecting a changed revision; apply complete revisions. Revisions are host-local: clear guest caches on reinitialization. Returns an error until settings are sampled or for invalid page bounds. Does not resolve actions.

Types: bindings.

demo-pressed

demo-pressed: func() -> bool;

True only for the current frame’s host-assigned action edge.

read-controls

read-controls: func() -> result<controls, string>;

Reads this callback’s control sample with controls authority and the shared read allowance.

Types: controls.

read-selected-controls

read-selected-controls: func(selection: selection) -> result<controls, string>;

Reads selected fields from the same current frame, preserving native key order. Requires controls authority and shares the read-controls callback read budget.

Types: controls, selection.

read-native-editing

read-native-editing: func() -> result<bool, string>;

Whether a native field or numeric editor on this mod’s open panel owns key input in the current frame, including IME composition. The keys it consumes still appear in keys-pressed and keys-held; skip panel key handling of your own while this is true. False while the panel is closed or another mod owns input. Requires controls authority.

read-text-events

read-text-events: func() -> result<list<text-event>, string>;

Committed single-line native text edits, separate from legacy numeric control events. Requires controls authority; repeated reads see the same bounded batch in a frame callback.

Types: text-event.

read-field-events

read-field-events: func() -> result<list<field-event>, string>;

Live values coalesce per field between frame callbacks. Submit and navigation retain order. Navigation includes the modifiers sampled at that key edge; preedit stays host-local.

Types: field-event.

reserve-keys

reserve-keys: func(keys: list<string>) -> result<_, string>;

Physical key names reserved before the ordinary gameplay router samples them.