events
INFO
Başvuru metni WIT dosyalarından otomatik üretildiği için İngilizce.
Game events with priorities and cancellation. A mod subscribes with subscribe; the host then calls the exported guest.handle-event once per event and subscription. Handlers run on the game / server main thread, one at a time.
Package blockheads:api@0.3.1 · Lua table bh.events · WIT source
Uses: types.{mod-id, priority, value, api-error, pos}, players.{player}
Types
subscription type
type subscription = u32;Identifies one subscription of the calling mod.
event-kind enum
The built-in events. Cases are only ever appended (0.1: player-join .. world-save; 0.2: player-pre-login .. player-move).
| Case | Description |
|---|---|
player-join | A player finished joining (after approval and the world summary). Server only. |
player-quit | A player left or was kicked. Server only. |
chat | A chat message, before it is shown or broadcast. Cancellable; the text can be replaced. |
command | A /command line, before any command handler runs. Cancellable (cancel = swallow the command). |
tick | One world step (0.2 s on the server). Fires after the world update. |
world-loaded | The world finished loading; world functions are usable from now on. |
world-save | The world is being saved (fires before and after, see save-phase). |
player-pre-login | (0.2) A player passed every vanilla join check and is about to be approved. Cancellable: the player is rejected with reject-reason (vanilla clients show their own text for it). Server only. |
block-place | (0.2) A player places a block or item into a tile. Cancellable: the tile stays as it is and the client is resynced exactly as for a protected tile. Server only. |
block-break | (0.2) A player removes a block, its contents, water or a back wall. Cancellable (same resync). Server only. |
block-changed | (0.2) A tile changed, by a player or by the simulation (growth, physics, NPCs). Monitor only: the outcome is ignored because cancelling simulation changes would desync clients. Server only. |
object-place | (0.2) A player places a workbench or an interaction object (chest, sign, door, bed, ...). Cancellable. Server only. |
damage | (0.2) A blockhead is about to take damage. Cancellable; the amount can be replaced. Server only. |
death | (0.2) A blockhead died. Server only. |
player-move | (0.2) A player's blockhead entered another tile. Server only. |
player-join-event record
Fired as player-join.
| Field | Type | Description |
|---|---|---|
player | borrow<player> |
player-quit-event record
Fired as player-quit.
| Field | Type | Description |
|---|---|---|
player | borrow<player> | |
was-kick | bool | True when the player was kicked or banned rather than leaving. |
chat-event record
Fired as chat. The handler may cancel the message or return replacement text in its outcome.
| Field | Type | Description |
|---|---|---|
player | borrow<player> | |
text | string | The message after the server's profanity filter and after earlier handlers' changes. |
cancelled | bool | True if an earlier handler cancelled it. |
command-sender variant
Who issued a command.
| Case | Payload | Description |
|---|---|---|
console | – | The server console (or the host app's console box). |
player | borrow<player> | A player in chat. |
command-event record
Fired as command.
| Field | Type | Description |
|---|---|---|
sender | command-sender | |
name | string | The command name without the leading /, lower-cased. |
args | list<string> | The rest of the line split on spaces. |
raw | string | The full line as typed, including the /. |
cancelled | bool |
tick-event record
Fired as tick.
| Field | Type | Description |
|---|---|---|
tick | u64 | Steps since the world was loaded, starting at 1. |
dt | f32 | Step length in seconds (0.2 on the server). |
world-loaded-event record
Fired as world-loaded.
| Field | Type | Description |
|---|---|---|
world-name | string | The world's display name. |
world-id | string | The world's save id (directory name on the server). |
save-phase enum
Before or after a save.
| Case | Description |
|---|---|
pre | |
post |
world-save-event record
Fired as world-save. Flush your storage on pre.
| Field | Type | Description |
|---|---|---|
phase | save-phase |
reject-reason enum
(0.2) Vanilla rejection reasons a player-pre-login handler may choose (the 0x26 reason byte in brackets).
| Case | Description |
|---|---|
client-too-old | [3] The client is too old. |
server-full | [5] The server is full. |
blacklisted | [6] Blacklisted. |
not-whitelisted | [7] Not on the whitelist. |
incorrect-password | [10] Wrong password. |
kicked | [11] Kicked. The default when a handler cancels without choosing. |
banned | [12] Banned. |
invalid-username | [14] Invalid user name. |
still-loading | [15] The server is still loading. |
player-pre-login-event record
(0.2) Fired as player-pre-login. The player is not online yet, so it is identified by id, not by handle.
| Field | Type | Description |
|---|---|---|
player-id | string | The player's id (the vanilla playerID). |
alias | string | The alias the player joins with. |
cancelled | bool | |
reason | reject-reason | The reason sent if the event ends up cancelled (set it with the reject-reason mutation). |
block-place-event record
(0.2) Fired as block-place.
| Field | Type | Description |
|---|---|---|
player | borrow<player> | |
at | pos | The target tile. |
item | u32 | The item type being placed (vanilla item ids). |
data-a | u16 | Item data A (for example the paint colour or rotation). |
data-b | u16 | Item data B. |
cancelled | bool |
break-layer enum
(0.2) What a block-break removes.
| Case | Description |
|---|---|
block | The tile, its contents or water. |
back-wall | The back wall. |
block-break-event record
(0.2) Fired as block-break.
| Field | Type | Description |
|---|---|---|
player | borrow<player> | |
at | pos | |
layer | break-layer | |
tile | u32 | The tile type before the removal. |
cancelled | bool |
block-changed-event record
(0.2) Fired as block-changed (monitor only).
| Field | Type | Description |
|---|---|---|
at | pos | |
tile | u32 | The new tile type. |
player | option<borrow<player>> | The player who caused the change, when known. |
object-kind enum
(0.2) What an object-place places.
| Case | Description |
|---|---|
workbench | A workbench / crafting station; item is the workbench type. |
interaction-object | An interaction object (chest, sign, door, bed, ...); item is its item type. |
object-place-event record
(0.2) Fired as object-place.
| Field | Type | Description |
|---|---|---|
player | borrow<player> | |
at | pos | |
object | object-kind | |
item | u32 | |
cancelled | bool |
damage-event record
(0.2) Fired as damage.
| Field | Type | Description |
|---|---|---|
player | option<borrow<player>> | The owner of the damaged blockhead. |
blockhead | u64 | The blockhead's unique id. |
amount | f32 | The damage (1.0 = a full health bar) after earlier handlers' changes, before armour and world rules. |
attacker | option<borrow<player>> | The attacking player for PvP damage. |
cancelled | bool |
death-event record
(0.2) Fired as death.
| Field | Type | Description |
|---|---|---|
player | option<borrow<player>> | The owner of the blockhead. |
blockhead | u64 | The blockhead's unique id. |
player-move-event record
(0.2) Fired as player-move.
| Field | Type | Description |
|---|---|---|
player | borrow<player> | |
from | pos | |
to | pos |
custom-event record
A custom event fired by a mod with fire-custom.
| Field | Type | Description |
|---|---|---|
name | string | Namespaced name, <mod-id>:<name>. |
source | mod-id | The mod that fired it. |
payload | value | Canonical CBOR payload; its shape is documented by the firing mod (usually in its wit/). |
cancelled | bool |
event variant
One event delivered to guest.handle-event.
| Case | Payload | Description |
|---|---|---|
player-join | player-join-event | |
player-quit | player-quit-event | |
chat | chat-event | |
command | command-event | |
tick | tick-event | |
world-loaded | world-loaded-event | |
world-save | world-save-event | |
custom | custom-event | |
player-pre-login | player-pre-login-event | (0.2) |
block-place | block-place-event | (0.2) |
block-break | block-break-event | (0.2) |
block-changed | block-changed-event | (0.2) |
object-place | object-place-event | (0.2) |
damage | damage-event | (0.2) |
death | death-event | (0.2) |
player-move | player-move-event | (0.2) |
mutation variant
A change a handler wants to make to a mutable event.
| Case | Payload | Description |
|---|---|---|
chat-text | string | Replace the chat text (only for chat). |
custom-payload | value | Replace the custom payload (only for custom). |
reject-reason | reject-reason | (0.2) The rejection reason (only for player-pre-login). |
damage-amount | f32 | (0.2) The damage amount, finite and >= 0 (only for damage). |
outcome record
What a handler returns. Ignored for monitor handlers and for events that are not cancellable.
| Field | Type | Description |
|---|---|---|
cancelled | bool | The new cancelled state. Returning false on a cancelled event un-cancels it. |
mutation | option<mutation> | An optional change; a mutation that does not fit the event is ignored with a warning. |
Functions
subscribe function
subscribe: func(kind: event-kind, priority: priority, ignore-cancelled: bool) -> result<subscription, api-error>;Subscribes to a built-in event. ignore-cancelled skips this handler while the event is cancelled.
subscribe-custom function
subscribe-custom: func(name: string, priority: priority, ignore-cancelled: bool) -> result<subscription, api-error>;Subscribes to a custom event by its full name (<mod-id>:<name>). Any mod's events may be subscribed.
unsubscribe function
unsubscribe: func(sub: subscription) -> bool;Removes a subscription. Returns false if it did not exist.
fire-custom function
fire-custom: func(name: string, payload: value) -> result<bool, api-error>;Fires a custom event. name must start with the caller's mod id and a colon. Listeners run synchronously with the normal priority rules; the result is true if the event ended up cancelled. Handlers of mods that are on the call stack (including the caller) get the event after the outermost call returns, with their outcome ignored.