Gameplay

cinnabar:extension/gameplay@0.1.0

Explicit local gameplay capabilities; no raw packet access.

Grants: Per operation: players, terrain, movement, camera, interaction, entities, commands or packet_delay; see each function.

Types

vector3

Three coordinates; the containing record or function specifies their units and frame.

record vector3 {
    x: f32,
    y: f32,
    z: f32,
}

player

Remote player feet in world coordinates, without names or network access.

record player {
    runtime-id: u64,
    position: vector3,
}

Types: vector3.

snapshot

Current input-owned frame only. Angles are actor YXZ radians: yaw left, pitch up.

record snapshot {
    session: u64,
    dimension: s32,
    eye: vector3,
    yaw: f32,
    pitch: f32,
    attack-held: bool,
    frame-seconds: f32,
    players: list<player>,
}

Types: player, vector3.

movement-snapshot

Input-owned local physics state; velocity is blocks per simulation tick.

record movement-snapshot {
    session: u64,
    dimension: s32,
    tick: u64,
    velocity: vector3,
    on-ground: bool,
    jump-held: bool,
    sprint-held: bool,
    sneak-held: bool,
    eligible: bool,
    knockback-sequence: u64,
}

Types: vector3.

movement-intents

True holds the control as if its binding were held; false adds nothing to physical input.

record movement-intents {
    sprint: bool,
    sneak: bool,
}

control-modes

The game’s own control modes, replacing the player’s toggle sprint, toggle sneak and always sprint settings while renewed. Always sprint applies only to keyboard and mouse.

record control-modes {
    toggle-sprint: bool,
    toggle-sneak: bool,
    always-sprint: bool,
}

camera-pose

The last rendered camera, including third-person and rig offsets. Angles are actor YXZ radians.

record camera-pose {
    position: vector3,
    yaw: f32,
    pitch: f32,
}

Types: vector3.

mob

A nearby non-player actor; health comes from its replicated health attribute.

record mob {
    runtime-id: u64,
    unique-id: s64,
    type-id: string,
    position: vector3,
    health: option<f32>,
    max-health: option<f32>,
}

Types: vector3.

camera-rig

Camera-local blocks (x right, y up, z back), roll in radians, FOV change in degrees.

record camera-rig {
    offset: vector3,
    roll: f32,
    fov-delta: f32,
}

Types: vector3.

Functions

read-frame

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

Requires players or terrain; player rows require players. None means gameplay does not own input.

Types: snapshot.

read-movement

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

Requires movement authority; none means gameplay does not own input.

Types: movement-snapshot.

pulse-jump

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

Stages one ordinary jump input for the next physics tick, with movement authority.

cancel-jump

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

Cancels pending local jump input after a successful callback, even outside gameplay.

set-movement-intents

set-movement-intents: func(intents: option<movement-intents>) -> result<_, string>;

Renew every focused gameplay frame; omission releases both intents. Requires movement authority; server movement, hunger and item-use restrictions still apply.

Types: movement-intents.

set-control-modes

set-control-modes: func(modes: option<control-modes>) -> result<_, string>;

Renew every focused gameplay frame; omission restores the player’s own settings. Requires movement authority. With several mods, a mode is on when any of them sets it.

Types: control-modes.

rotate

rotate: func(yaw-delta: f32, pitch-delta: f32) -> result<_, string>;

Requires the camera grant and a current frame; commits only after frame returns.

set-attack-reach

set-attack-reach: func(blocks: option<f32>) -> result<_, string>;

Requires interaction authority; a non-none range also requires a current gameplay frame. Overrides local actor pick and attack range up to MAX_ENTITY_REACH_BLOCKS; none restores ordinary mode and input limits. Attack eligibility, obstruction and server validation still apply. Does not change mining or block-use reach.

pulse-attack

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

One attack-press edge, only while the physical attack control is held. An active action filter receives it as a repeat.

set-packet-delay

set-packet-delay: func(delay-ms: u32) -> result<_, string>;

Requires packet-delay authority; 0 drains the queue, maximum 1000 milliseconds. Delays post-login application packets in both directions, without raw packet access. Retained only after a successful callback; no current gameplay frame required.

read-relayed-position

read-relayed-position: func() -> result<option<vector3>, string>;

Requires packet-delay authority: the local feet position last relayed to the server, which trails the presented position while packets are delayed. None outside gameplay or while no delay is active.

Types: vector3.

read-camera

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

Requires players or terrain, as read-frame. None means gameplay does not own input.

Types: camera-pose.

read-mobs

read-mobs: func() -> result<list<mob>, string>;

Requires the entities grant and a current frame; nearest first, bounded by count and range.

Types: mob.

set-camera-rig

set-camera-rig: func(rig: option<camera-rig>) -> result<_, string>;

Retained third-person rig, swept against blocks; none restores the player’s own view.

Types: camera-rig.

request-command

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

Sent as a player command request after frame returns; the command must be granted by name.