types

Shared types used by every other interface.

Package blockheads:api@0.3.1 · Lua table bh.types · WIT source

Types

mod-id type

type mod-id = string;

A mod id as written in mod.toml ([a-z0-9_-]{2,40}).

value type

type value = list<u8>;

A dynamic value crossing a language boundary (service arguments and results, custom event payloads). Always canonical CBOR (RFC 8949 section 4.2.1, "core deterministic encoding"). Records are CBOR maps with kebab-case text keys, variants are one-entry maps {tag: value}, enums are text, option is null or the value, host handles are {"$h": u64}. Each SDK offers typed helpers so authors rarely touch the bytes.

pos record

A tile position in the world. x wraps around the world width, y grows upwards from bedrock.

Field	Type	Description
x	s32
y	s32

side enum

Which program a piece of mod code runs in.

Case	Description
server	The dedicated server (or the host of a local world).
client	A game client (PC port or Android loader).

priority enum

Event handler priority, in Spigot order. Handlers run from lowest to highest, then monitor. Inside one priority they run in mod load order (dependencies first).

Case	Description
lowest	Runs first. Use it when you want later handlers to see and override your decision.
low	Runs after lowest.
normal	The default.
high	Runs after normal.
highest	Runs last among handlers that may still cancel or modify the event.
monitor	Sees the final state. A monitor handler can neither cancel nor modify the event; its outcome is ignored.

api-error variant

Errors returned by host functions.

Case	Payload	Description
not-permitted	string	The mod lacks the permission named in the payload (for example players:kick).
invalid-argument	string	An argument was malformed; the payload says which one and why.
limit-exceeded	string	A size or count limit was hit (key too long, too many tasks, ...); the payload names the limit.
stale-handle	–	The handle refers to something that no longer exists (for example a player who left).
unsupported	–	The function is not available on this side or in this host version.
internal	string	The host failed for a reason the mod cannot fix; the payload is a human readable message.