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,
}

block-position

Integer world coordinates of one block.

record block-position {
    x: s32,
    y: s32,
    z: s32,
}

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,
    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,
    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,
}

movement-input

A resolved local control vector: right and forward axes are finite and bounded to -1..1. Buttons add holds to physical controls; axes replace walking input for this frame.

record movement-input {
    right: f32,
    forward: f32,
    jump: bool,
    sneak: bool,
    sprint: 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.

read-movement-input

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

Reads admitted controls before any mod output is applied. Requires movement authority. None means focused gameplay does not own input.

Types: movement-input.

set-movement-input

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

Replaces walking axes and supplies resolved button holds for one successful frame. Requires movement authority and focused gameplay. Renew every frame; none restores input. Sprint applies to the supplied direction; hunger, item use, collision, input locks and server authority still apply. A complete vector belongs to the earliest supplying mod.

Types: movement-input.

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-block-mining

set-block-mining: func(held: bool) -> result<_, string>;

Holds ordinary mining on the crosshair block for one successful gameplay frame. Requires interaction authority and a current gameplay frame when true; false releases only this mod’s request. Renew every frame. Omission, focus loss, unload and failed callbacks release it. Does not press attack or select targets; normal block reach, obstruction, game mode, tool timing, item use and server checks still apply.

read-block-target

read-block-target: func() -> result<option<vector3>, string>;

Center of the current crosshair block in world coordinates. Requires terrain and focused gameplay.

Types: vector3.

set-block-mining-target

set-block-mining-target: func(point: option<vector3>) -> result<_, string>;

Redirects held physical block mining toward a world point for one successful frame. Requires interaction, terrain and focused gameplay. Does not hold attack or rotate the view. Renew every frame; none or omission restores the crosshair. The first supplying mod wins. Ordinary reach, obstruction, mode, tool timing and server checks still apply.

Types: vector3.

break-blocks

break-blocks: func(positions: list<block-position>) -> result<_, string>;

Requests immediate destruction of explicit block positions on the next movement tick. Requires interaction, terrain and focused gameplay. At most MAX_BLOCK_BREAKS per frame, within MAX_BLOCK_BREAK_DISTANCE of the eye. Duplicate positions are coalesced. This explicit override bypasses local mining time, reach and obstruction, but retains game-mode permissions, loaded terrain and server validation. The host supplies held item and wire identities. Requests commit only after a successful callback and are discarded on focus loss or world changes. No camera or physical input is changed.

Types: block-position.

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.