Terrain

cinnabar:extension/terrain@0.1.0

Bounded local terrain reads. The queries a callback reads become its subscriptions, which the client samples before later frames, so a new query reads pending first. A deferred callback keeps its subscriptions. Unknown terrain is never reported as air.

Grants: terrain.

Types

position

An integer block position in the current dimension.

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

geometry

Selects which block shapes to request; an empty set requests neither family.

flags geometry {
    collision,
    selection,
}

region-query

Inclusive minimum and exclusive maximum; each extent is 1 to MAX_TERRAIN_EXTENT blocks.

record region-query {
    min: position,
    max: position,
    geometry: geometry,
}

Types: geometry, position.

stamp

Identifies one sample of one query; an equal stamp means identical contents.

record stamp {
    session: u64,
    dimension: s32,
    registry: u64,
    revision: u64,
}

physics-flags

Available block contact properties; missing physics remains absent on the block state.

flags physics-flags {
    climbable,
    water,
    lava,
    cobweb,
    powder-snow,
    scaffolding,
    passable,
}

surface-response

The resolved contact response associated with the block’s physics.

enum surface-response {
    none,
    slime,
    bed,
    honey,
    soul-sand,
    bubble-up,
    bubble-down,
}

physics

Resolved movement and fluid properties, when the registry supplies them.

record physics {
    friction: f64,
    horizontal-speed-factor: f64,
    vertical-speed-factor: f64,
    fluid-height: f64,
    %flags: physics-flags,
    surface: surface-response,
}

Types: physics-flags, surface-response.

resolved-shape

An index into the region’s shapes; shape 0 is known-empty.

variant resolved-shape {
    unavailable,
    known(u32),
}

shape-binding

Distinguishes unrequested, shared and position-dependent geometry without guessing boxes.

variant shape-binding {
    not-requested,
    fixed(resolved-shape),
    per-cell,
}

Types: resolved-shape.

block-state

One distinct runtime ID; metadata and physics are absent when the registry lacks them.

record block-state {
    runtime-id: u32,
    identifier: option<string>,
    canonical-state: option<string>,
    tags: list<string>,
    physics: option<physics>,
    collision: shape-binding,
    selection: shape-binding,
}

Types: physics, shape-binding.

chunk-revision

Revision of a column the region depends on; none is absent terrain.

record chunk-revision {
    x: s32,
    z: s32,
    revision: option<u64>,
}

shape-override

Geometry of one layer slot that depends on its position; none keeps the state’s binding.

record shape-override {
    slot: u32,
    collision: option<resolved-shape>,
    selection: option<resolved-shape>,
}

Types: resolved-shape.

region

Cell ((x * size-z) + z) * size-y + y, relative to the minimum, has layer l at slot l * cells + cell. Shapes are block-local, with native position offsets applied.

record region {
    stamp: stamp,
    chunks: list<chunk-revision>,
    layer-count: u8,
    loaded: list<u64>,
    states: list<u16>,
    palette: list<block-state>,
    shape-offsets: list<u32>,
    shape-boxes: list<f64>,
    overrides: list<shape-override>,
}

Types: block-state, chunk-revision, shape-override, stamp.

read-result

A deferred sample, an unchanged stamp or a complete changed region.

variant read-result {
    pending,
    unchanged(stamp),
    changed(region),
}

Types: region, stamp.

read-error

Admission or availability failures; shrink a query when its response exceeds a limit.

enum read-error {
    denied,
    unavailable,
    invalid-query,
    out-of-range,
    budget-exhausted,
    limit-exceeded,
}

Functions

read-region

read-region: func(query: region-query, after: option<stamp>) -> result<read-result, read-error>;

Requires terrain authority and a gameplay frame; the query lies within MAX_TERRAIN_DISTANCE blocks of the player’s feet on each axis. Pass the stamp last received for this query to skip unchanged data. Limits are mod-api’s MAX_TERRAIN_* constants.

Types: read-error, read-result, region-query, stamp.

find-blocks

find-blocks: func(identifiers: list<string>, range: f32, limit: u32) -> result<list<position>, read-error>;

Positions of loaded blocks whose identifier matches one of 1 to MAX_FOUND_BLOCK_IDENTIFIERS namespaced names, nearest first, within range blocks of the player’s feet (1 to MAX_TERRAIN_DISTANCE) and at most limit results (1 to MAX_FOUND_BLOCKS). Like a region query, a search becomes a subscription that the client scans incrementally between frames, so a new search returns none and results fill in as loaded terrain is scanned. Searches and region queries share MAX_TERRAIN_QUERIES and the callback’s terrain call budget. Requires terrain authority and a gameplay frame.

Types: position, read-error.