Player state

cinnabar:extension/player-state@0.1.0

Read-only, session-bound facts about the local player’s presented inventory and effects.

Grants: player_state for local observations; actor reads instead require players or entities for their kind.

Types

item

One presented item stack, retaining wire identity when a name is unavailable.

record item {
    identifier: option<string>,
    network-id: s32,
    metadata: u32,
    count: u16,
    block: bool,
    damage: option<u32>,
    max-durability: option<u32>,
}

slot

Preserves whether a cell is known separately from whether it contains an item.

record slot {
    known: bool,
    item: option<item>,
}

Types: item.

effect

One currently presented status effect; amplifier and duration keep their wire units.

record effect {
    effect-id: s32,
    amplifier: s32,
    remaining-ticks: option<u64>,
    ambient: bool,
    particles: bool,
}

snapshot

Inventory and effects from one session and dimension; unknown cells stay in place.

record snapshot {
    session: u64,
    dimension: s32,
    selected-slot: option<u8>,
    inventory: list<slot>,
    armor: list<slot>,
    offhand: slot,
    effects: list<effect>,
}

Types: effect, slot.

world-observation

Local feet and life state fenced to a connected destination and dimension.

record world-observation {
    session: u64,
    %world: string,
    dimension: s32,
    position: tuple<f32, f32, f32>,
    alive: bool,
    runtime-id: u64,
}

motion

Presented local motion, readable without owning gameplay input.

record motion {
    session: u64,
    dimension: s32,
    yaw: f32,
    pitch: f32,
    velocity: tuple<f32, f32, f32>,
    on-ground: bool,
}

food

Food values associated with the held item, including server item components.

record food {
    nutrition: u32,
    saturation-modifier: f32,
}

vitals

Authoritative food attributes; unavailable attributes remain absent.

record vitals {
    session: u64,
    dimension: s32,
    hunger: option<f32>,
    max-hunger: option<f32>,
    saturation: option<f32>,
    held-food: option<food>,
}

Types: food.

bounds

An axis-aligned box in world coordinates, with minimum and maximum corners.

record bounds {
    min: tuple<f32, f32, f32>,
    max: tuple<f32, f32, f32>,
}

actor

An admitted actor in the presented world; optional targeting facts are not estimates.

record actor {
    session: u64,
    dimension: s32,
    runtime-id: u64,
    player: bool,
    position: tuple<f32, f32, f32>,
    boxes: list<bounds>,
    name: string,
    identifier: string,
    yaw: f32,
    pitch: f32,
    pickable: bool,
    hittable: option<bool>,
    look-origin: option<tuple<f32, f32, f32>>,
    look-direction: option<tuple<f32, f32, f32>>,
    invisible: bool,
    sneaking: bool,
    hurt: bool,
    health: option<f32>,
}

Types: bounds.

observed-actor

An actor observation with its independently replicated health maximum.

record observed-actor {
    actor: actor,
    max-health: option<f32>,
}

Types: actor.

combat-kind

totem is a totem-of-undying activation on runtime-id, local or remote, and death a server death notice. Read event lives with read-combat-lives and current actor lives with read-actor-lives.

enum combat-kind {
    attack-admitted,
    hurt,
    death,
    totem,
}

combat-event

Retained combat evidence scoped to a session and dimension; it does not identify an attacker.

record combat-event {
    sequence: u64,
    session: u64,
    dimension: s32,
    kind: combat-kind,
    local: bool,
    player: bool,
    runtime-id: u64,
    distance: option<f32>,
    position: tuple<f32, f32, f32>,
}

Types: combat-kind.

actor-life

An admitted actor’s current life: life changes whenever the actor spawns again or dies, and dead is its current death state. Compare lives within one session.

record actor-life {
    life: u64,
    dead: bool,
}

chat-message

One retained received chat message, addressed by a monotonic sequence.

record chat-message {
    sequence: u64,
    text: string,
}

world-time

The server world clock: time is the absolute ticks the server last set, advanced at 20 per second while its daylight cycle runs, 24000 per day. daylight-cycle is the server’s daylight-cycle rule. Visual time overrides never apply.

record world-time {
    session: u64,
    time: s64,
    daylight-cycle: bool,
}

sidebar-row

A resolved sidebar label paired with its server-provided score.

record sidebar-row {
    label: string,
    score: s32,
}

sidebar

The currently resolved sidebar title and ordered rows.

record sidebar {
    title: string,
    rows: list<sidebar-row>,
}

Types: sidebar-row.

equipment

The equipment family of a snapshot, without copying status effects.

record equipment {
    session: u64,
    dimension: s32,
    selected-slot: option<u8>,
    inventory: list<slot>,
    armor: list<slot>,
    offhand: slot,
}

Types: slot.

effects

The effect family of a snapshot, without copying equipment.

record effects {
    session: u64,
    dimension: s32,
    effects: list<effect>,
}

Types: effect.

revisions

Independent exact-content tokens for equipment and effects within an instance.

record revisions {
    session: u64,
    dimension: s32,
    equipment: u64,
    effects: u64,
}

Functions

read-motion

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

Read-only presented motion; requires player-state authority, including while menus own input.

Types: motion.

read-vitals

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

Authoritative current food attributes; unknown fields remain absent, never estimated.

Types: vitals.

read-ping

read-ping: func() -> result<option<u32>, string>;

Actual upstream round-trip milliseconds; absent before measurement or when unsupported.

read-actors

read-actors: func() -> result<list<actor>, string>;

At most 16 nearby actors within 128 blocks; player rows require players, other rows entities.

Types: actor.

read-actors-limited

read-actors-limited: func(limit: u32) -> result<list<observed-actor>, string>;

Reads a smaller prefix of the same authorized observations to bound guest copying work. limit is 1 through MAX_OBSERVED_ACTORS; filtering and session authority are unchanged.

Types: observed-actor.

read-actor-lives

read-actor-lives: func(runtime-ids: list<u64>) -> result<list<option<actor-life>>, string>;

One entry per requested runtime ID, in order, regardless of distance or the actor reads’ limit: none when the session has no such admitted actor in the current dimension, or the caller lacks the grant for its kind. Player rows require players, other rows entities. At most MAX_ACTOR_LIFE_READS IDs; shares the actor reads’ callback allowance.

Types: actor-life.

read-combat

read-combat: func(after: u64, limit: u32) -> result<list<combat-event>, string>;

Incremental retained evidence, at most 4 entries per read. Requires player-state authority. Attack admission is outbound intent, NOT server confirmation; hurt carries NO attacker attribution.

Types: combat-event.

read-combat-lives

read-combat-lives: func(sequences: list<u64>) -> result<list<option<u64>>, string>;

The actor’s read-actor-lives life when each combat event was recorded, in request order. Death events carry the life after the death. Compare lives within one session. None when the event is no longer retained, belongs to another session or dimension, or the caller cannot read it. Requires the same grants as read-combat and shares its callback allowance. At most MAX_COMBAT_LIFE_READS sequences.

read-chat

read-chat: func(after: u64, limit: u32) -> result<list<chat-message>, string>;

Newest 32 retained received messages, filtered by sequence > after, in FIFO order. limit is 1 through 4; individual text fields are at most 256 UTF-8 bytes.

Types: chat-message.

read-world-time

read-world-time: func() -> result<option<world-time>, string>;

Requires player-state authority; none outside a connected session or before the server sets a time.

Types: world-time.

read-world

read-world: func() -> result<option<world-observation>, string>;

Session-fenced feet position and life state, readable while menus own input.

Types: world-observation.

read-fps

read-fps: func() -> result<option<f32>, string>;

Measured completed client frames per real second, never the configured limit.

read-sidebar

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

Ordered, resolved sidebar names; none when the server has no sidebar.

Types: sidebar.

read-snapshot

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

Requires the player-state grant. None outside the current connected session. Available while a screen owns input; carries no camera, interaction or packet authority.

Types: snapshot.

read-revision

read-revision: func() -> result<option<u64>, string>;

Exact content token for the current snapshot, scoped to this component instance. None outside a current snapshot. Shares the read-snapshot grant and read budget. Contents equal to the last full read reuse its token, even after unimported changes.

read-revisions

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

Independent exact observation tokens. Equipment is unaffected by ticking effects. Tokens advance on observed changes and never repeat within an instance, including reconnects. These three reads share read-snapshot’s grant, bounds, and callback read allowance.

Types: revisions.

read-equipment

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

Reads only equipment under the snapshot grant and shared read allowance.

Types: equipment.

read-effects

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

Reads only effects under the snapshot grant and shared read allowance.

Types: effects.