/// The Rift plugin contract.
///
/// One event schema and one host API, shared by every execution mode: the
/// sandboxed configuration script, persistent Lua and WebAssembly plugins and
/// remote bus responders. Rust host types mirror these definitions with serde
/// derives; the bus uses their JSON form.
///
/// Rules that keep C and Go guests pleasant (see docs/plugins.md):
/// - WASI 0.2, no `async`, no `stream` or `future`.
/// - No `resource` types: host-managed things are plain `u64` handles.
/// - Plain data only: no `flags`, no nested options, tuples only as pairs.
/// - Plugin configuration and free-form payloads are JSON strings.
/// - Every hook is an export and every export has a default in each SDK.
/// - The guest is single-threaded; the host never calls one instance
/// concurrently.
/// - Additive changes keep compiled components loading: new host functions,
/// new types and new interfaces, never a changed type or a new case in an
/// existing enum or variant. Wasmtime matches `@0.1.x` names with each
/// other, so 0.1.1 adds the optional `dialogs` export and the dialog host
/// functions, 0.1.2 the optional `decisions` export and the rich text
/// host functions, 0.1.3 the visibility and permission meta host
/// functions, 0.1.4 `players.title-json` and the optional `styled`
/// export (rich suggestion tooltips and server-list text), and 0.1.5
/// `players.locale`, command permissions that may be empty (every player
/// may run the command) and the optional `chat` export, without breaking
/// components built against 0.1.0.
/// - Breaking changes move to 1.0.
package rift:plugin@0.1.5;
interface types {
/// Log severity.
enum level {
trace,
debug,
info,
warn,
error,
}
/// A joined player in the process-wide directory.
record player-info {
connection-id: u64,
/// 32 lowercase hexadecimal digits, without dashes.
uuid: string,
name: string,
/// The backend the player is connected to.
server: string,
protocol: s32,
}
/// The session an authenticated player hook is about. Fields that do not
/// apply to a hook are `none` or empty.
record context {
connection-id: u64,
uuid: string,
name: string,
listener: string,
hostname: string,
peer-ip: string,
protocol: s32,
server: option<string>,
default-server: option<string>,
/// `before-transfer`/`after-transfer`: the destination.
target: option<string>,
/// `before-transfer`: why the transfer happens; `disconnect`: why the
/// session closed.
reason: option<string>,
/// `after-transfer`: whether the transfer completed.
success: option<bool>,
/// `command`/`suggest`, and `chat` for a command: the command name
/// and the text after it.
command: option<string>,
args: string,
/// `suggest`: the argument being completed and its 1-based position.
word: string,
position: u32,
}
/// Metadata available right after TCP accept, before any bytes are read.
record connection {
listener: string,
peer-addr: string,
peer-ip: string,
peer-port: u16,
local-addr: string,
local-ip: string,
local-port: u16,
default-backend: option<string>,
}
/// `route`: keep the configured policy, pick a configured backend or
/// group, or close the connection.
variant route-decision {
default,
backend(string),
reject(option<string>),
}
/// The answer to a decision hook. Each hook accepts a subset:
/// - login, before-transfer: continue, deny
/// - initial-server: continue, deny, server
/// - command: continue, message, server, queue, leave-queue
variant action {
continue,
deny(string),
server(string),
message(string),
queue(string),
leave-queue,
}
/// `action` with rich text (since 0.1.2), the answer of the `decisions`
/// export. The hooks accept the same subsets, with `deny-json` wherever
/// `deny` is accepted and `message-json` wherever `message` is. It is
/// also the answer of the `chat` export (since 0.1.5), which accepts
/// continue, deny and deny-json.
///
/// `deny` and `message` are plain text of 1..=1024 bytes. `deny-json`
/// and `message-json` are JSON text components of at most 32 KiB, for
/// colours, line breaks, hover text and click events; text that does not
/// start with `{`, `[` or `"` is shown as written.
variant decision {
continue,
deny(string),
server(string),
message(string),
queue(string),
leave-queue,
deny-json(string),
message-json(string),
}
record suggestion {
text: string,
tooltip: option<string>,
}
/// `suggestion` with a rich tooltip (since 0.1.4), the answer of the
/// `styled` export. `tooltip-json` is a JSON text component (including
/// the `mini` and `legacy` authoring objects, see docs/text.md) or text
/// shown as written; empty means no tooltip.
record rich-suggestion {
text: string,
tooltip-json: option<string>,
}
/// A server-list ping, before any backend contact.
record ping {
listener: string,
hostname: string,
protocol: s32,
peer-ip: string,
/// The routed backend or group; `none` for an unmatched hostname.
backend: option<string>,
maintenance: bool,
online: u64,
max-players: u64,
}
/// Fields a `status` hook replaces for one ping. `motd-json` is a JSON
/// text component or a JSON string.
record status-override {
motd-json: option<string>,
version: option<string>,
protocol: option<s32>,
online: option<u32>,
max-players: option<u32>,
sample: option<list<string>>,
/// A `data:image/png;base64,...` URI.
favicon: option<string>,
}
/// `status-override` with rich version and player-sample text (since
/// 0.1.4), the answer of the `styled` export. `version-json` and each
/// `sample-json` line are JSON text components (including the `mini`
/// and `legacy` authoring objects) or text shown as written; clients
/// show them as `ยง` codes.
record rich-status-override {
motd-json: option<string>,
version-json: option<string>,
protocol: option<s32>,
online: option<u32>,
max-players: option<u32>,
sample-json: option<list<string>>,
/// A `data:image/png;base64,...` URI.
favicon: option<string>,
}
/// An authenticated request to `/ext` or `/ext/*` on the web server.
record http-request {
method: string,
path: string,
query: string,
body: string,
headers: list<tuple<string, string>>,
/// The status object with operator detail, as a JSON object, plus
/// `operator`: the authenticated caller as `{name, permissions,
/// groups}`. `permissions` is `null` for full access and `groups` is
/// `null` when the caller is not limited to service groups. Any
/// caller with the `extensions` permission reaches this hook, so check
/// `operator` before acting for it.
context-json: string,
}
record http-response {
status: u16,
content-type: string,
body: string,
}
/// A bus message delivered to a subscription made with `bus.subscribe`.
record bus-message {
/// The handle `bus.subscribe` returned.
handle: u64,
subject: string,
payload: list<u8>,
reply: option<string>,
}
/// A Rift event, mirroring a `rift.events.*` publication.
record rift-event {
/// For example `rift.events.players` or `rift.events.instances`.
subject: string,
/// The event body as published on the bus (a JSON object).
payload-json: string,
}
/// How a command's arguments are completed.
variant suggest-kind {
none,
/// A fixed list, filtered by prefix.
fixed(list<string>),
/// Online player names.
players,
/// Servers the player may join.
servers,
/// Ask the plugin's `suggest` export.
dynamic,
}
record command-spec {
/// 1..=64 bytes of `a-z0-9_-`; `server` and `hub` are reserved.
name: string,
/// The permission node a player needs to see and run the command.
/// Empty (since 0.1.5) means every player may see and run it; hosts
/// before 0.1.5 reject a registration with an empty permission.
permission: string,
suggest: suggest-kind,
}
/// Events a plugin can receive. The host skips exports a plugin does not
/// list, so unused hooks cost nothing per event.
enum hook {
route,
login,
initial-server,
before-transfer,
command,
suggest,
status,
http,
join,
after-transfer,
disconnect,
message,
timer,
event,
}
/// What `init` returns. Subscriptions and timers are created from inside
/// `init` through the host API.
record registration {
commands: list<command-spec>,
/// Events to deliver. An empty list delivers every hook.
hooks: list<hook>,
}
/// A boss bar shown to one player.
record boss-bar-spec {
/// A plain string or a JSON text component.
text-json: string,
/// 0.0 to 1.0.
progress: f32,
/// pink, blue, red, green, yellow, purple or white.
color: string,
/// progress, notched_6, notched_10, notched_12 or notched_20.
style: string,
darken-sky: bool,
play-music: bool,
create-fog: bool,
}
/// A title; times are ticks.
record title-spec {
title: string,
subtitle: option<string>,
fade-in: s32,
stay: s32,
fade-out: s32,
}
/// `title-spec` with rich text (since 0.1.4); times are ticks. Both are
/// JSON text components (including the `mini` and `legacy` authoring
/// objects) or text shown as written. An empty `title-json` shows only
/// the subtitle.
record title-json-spec {
title-json: string,
subtitle-json: option<string>,
fade-in: s32,
stay: s32,
fade-out: s32,
}
/// What a player sent through the chat box (since 0.1.5).
enum chat-kind {
/// A chat message.
message,
/// A command that neither Rift nor a plugin owns, on its way to the
/// backend.
command,
}
/// A chat message or backend command a player sent, before the backend
/// sees it (since 0.1.5); the input of the `chat` export.
record chat-attempt {
/// The player. `server` is their current backend. For `command`,
/// `ctx.command` is the root name and `ctx.args` the rest.
ctx: context,
kind: chat-kind,
/// The message, or the command line without the leading slash.
text: string,
}
/// A click on a plugin action of a dialog this plugin showed with
/// `players.dialog` (since 0.1.1).
record dialog-response {
/// The player who clicked. `server` is their current backend; the
/// command, target and suggestion fields are empty.
ctx: context,
/// The action's `id` as the plugin wrote it, such as `submit`.
action: string,
/// The player's input values by key, as a JSON object: strings for
/// text and single-option inputs, booleans, numbers. `{}` for a
/// `custom` action. They come from the client: check them like any
/// player input.
values-json: string,
/// The action's `payload` (`custom`) or `additions`
/// (`dynamic/custom`) as JSON, exactly as the plugin wrote it. Rift
/// keeps it, so the client can neither see nor change it.
payload-json: option<string>,
}
}
/// The joined players. `target` is a name, a UUID or a connection id.
interface players {
use types.{player-info, title-spec, title-json-spec, boss-bar-spec};
/// Players, optionally only those on one server or service group.
%list: func(server: option<string>) -> result<list<player-info>, string>;
get: func(target: string) -> result<option<player-info>, string>;
/// Names starting with `prefix`, sorted.
names: func(prefix: option<string>) -> list<string>;
/// Each returns whether the player was online. Plain text is 1..=1024
/// bytes.
message: func(target: string, text: string) -> result<bool, string>;
action-bar: func(target: string, text: string) -> result<bool, string>;
title: func(target: string, title: title-spec) -> result<bool, string>;
/// JSON text components; both `none` restores the configured tab list.
tab-list: func(target: string, header-json: option<string>, footer-json: option<string>) -> result<bool, string>;
/// `none` removes the bar called `name`.
boss-bar: func(target: string, name: string, bar: option<boss-bar-spec>) -> result<bool, string>;
kick: func(target: string, reason: string) -> result<bool, string>;
/// Show a dialog to a player on Minecraft 1.21.6 or newer, replacing any
/// open one (since 0.1.1). `dialog-json` is a dialog in the vanilla JSON
/// format; see docs/dialogs.md for the accepted subset. Buttons whose
/// `custom` or `dynamic/custom` action has an `id` without a namespace
/// come back through the `dialogs` export. Returns false when the player
/// is offline, older than 1.21.6 or has too many undelivered actions; an
/// invalid dialog is an error.
dialog: func(target: string, dialog-json: string) -> result<bool, string>;
/// Close the dialog this Rift showed, if it is still open (since 0.1.1).
clear-dialog: func(target: string) -> result<bool, string>;
transfer: func(target: string, server: string) -> result<bool, string>;
/// Returns how many players received the message.
broadcast: func(text: string) -> result<u32, string>;
/// `message`, `action-bar`, `kick` and `broadcast` with a JSON text
/// component of at most 32 KiB instead of plain text, for colours, line
/// breaks, hover text and click events (since 0.1.2). Text that does not
/// start with `{`, `[` or `"` is shown as written. Rift spells hover and
/// click events the way each player's client reads them.
message-json: func(target: string, text-json: string) -> result<bool, string>;
action-bar-json: func(target: string, text-json: string) -> result<bool, string>;
kick-json: func(target: string, reason-json: string) -> result<bool, string>;
broadcast-json: func(text-json: string) -> result<u32, string>;
/// The permission node a viewer needs to see the player, from their
/// `rift.visible-to` meta, or `none` when everyone sees them (since
/// 0.1.3). `list` and `get` return hidden players too; Rift leaves them
/// out of tab lists, counts and completion for viewers without the node.
visible-to: func(target: string) -> result<option<string>, string>;
/// `title` with JSON text components (since 0.1.4).
title-json: func(target: string, title: title-json-spec) -> result<bool, string>;
/// The language the player's client reported, as the client spells it
/// (`en_us`; old clients send `en_US`), or `none` while Rift does not
/// know it yet (since 0.1.5). The client sends it after login: during
/// configuration from 1.20.2, after Join Game before. So it is never
/// known in `login`, in `join` only for 1.20.2 and newer clients, and it
/// follows later changes of the client's language setting.
locale: func(target: string) -> result<option<string>, string>;
}
/// The durable key-value store. Namespaces are prefixed with
/// `plugin.<name>.` for persistent plugins.
interface store {
get: func(namespace: string, key: string) -> result<option<list<u8>>, string>;
set: func(namespace: string, key: string, value: list<u8>) -> result<_, string>;
/// Returns whether an entry existed.
delete: func(namespace: string, key: string) -> result<bool, string>;
/// Adds `delta` to an integer entry (missing counts as 0) and returns it.
increment: func(namespace: string, key: string, delta: s64) -> result<s64, string>;
/// Entries whose key starts with `prefix`, sorted by key.
%list: func(namespace: string, prefix: string) -> result<list<tuple<string, list<u8>>>, string>;
}
/// Rift's permission store: user nodes and group memberships.
interface permissions {
/// Whether the node is true in the player's current contexts.
has: func(uuid: string, node: string) -> bool;
/// Set the user's global permission node; `none` removes it.
set: func(uuid: string, node: string, value: option<bool>) -> result<_, string>;
/// Returns whether membership changed.
add-group: func(uuid: string, group: string) -> result<bool, string>;
remove-group: func(uuid: string, group: string) -> result<bool, string>;
/// The player's groups, including inherited and `default`.
groups: func(uuid: string) -> list<string>;
/// Every group with its weight, display name and nodes, as a JSON object.
list-groups: func() -> string;
/// One meta value in the player's current contexts (since 0.1.3).
meta: func(uuid: string, key: string) -> option<string>;
/// Set the user's meta node `key` in exactly the contexts of
/// `contexts-json` (a JSON object such as `{"server":"lobby-1"}`; `none`
/// is global), expiring at `expires-at` Unix seconds if given; a `none`
/// value removes the node in those contexts. Returns whether anything
/// changed (since 0.1.3).
set-meta: func(uuid: string, key: string, value: option<string>, contexts-json: option<string>, expires-at: option<u64>) -> result<bool, string>;
}
/// The message bus.
interface bus {
/// Returns how many subscribers received the message.
publish: func(subject: string, payload: list<u8>, reply: option<string>) -> result<u32, string>;
/// Send a request and wait for the first reply.
request: func(subject: string, payload: list<u8>, timeout-ms: u32) -> result<list<u8>, string>;
/// Messages arrive through the `message` export with this handle.
/// `queue-group` load-balances between subscribers of the same group.
subscribe: func(subject: string, queue-group: option<string>) -> result<u64, string>;
unsubscribe: func(handle: u64) -> bool;
/// Append to a durable stream; returns the sequence number.
stream-publish: func(subject: string, payload: list<u8>) -> result<u64, string>;
}
/// Managed servers, through the same `rift.control.*` operations as the bus.
/// Results are the control service's JSON replies.
interface servers {
create: func(group: string) -> result<string, string>;
remove: func(name: string) -> result<string, string>;
start: func(name: string) -> result<string, string>;
stop: func(name: string) -> result<string, string>;
download: func(template: string) -> result<string, string>;
/// Any other `rift.control.<operation>` (status, servers, groups, nodes,
/// templates, transfer, drain, maintenance, reload) with a JSON payload.
control: func(operation: string, payload-json: string) -> result<string, string>;
}
/// Timers fire through the `timer` export with the returned handle.
interface timers {
/// Repeats every `ms` milliseconds (at least 10).
every: func(ms: u32) -> u64;
/// Fires once after `ms` milliseconds.
after: func(ms: u32) -> u64;
/// Returns whether the timer existed.
cancel: func(handle: u64) -> bool;
}
/// Rift's log stream, prefixed with the plugin name.
interface log {
use types.{level};
log: func(level: level, message: string);
}
interface meta {
name: func() -> string;
version: func() -> string;
/// Guest path of the plugin's private data directory (`/data`).
data-dir: func() -> string;
/// Guest path of the configuration directory (`/host`), if granted.
config-dir: func() -> option<string>;
/// Monotonic seconds since Rift started.
clock: func() -> f64;
/// Unix time in seconds.
time: func() -> s64;
}
/// Hooks the host calls. Every export has a default in each SDK, and the
/// host skips hooks the plugin does not list in its registration.
interface handler {
use types.{
context, connection, route-decision, action, suggestion, ping,
status-override, http-request, http-response, bus-message, rift-event,
registration,
};
/// Called once per instance with the `rift.plugin(name, config)` table
/// encoded as JSON (`{}` without one).
init: func(config-json: string) -> result<registration, string>;
/// The configuration changed and the manifest sets `hot_reload = true`.
reload: func(config-json: string) -> result<_, string>;
shutdown: func(reason: string);
route: func(connection: connection) -> route-decision;
login: func(ctx: context) -> action;
initial-server: func(ctx: context) -> action;
before-transfer: func(ctx: context) -> action;
command: func(ctx: context) -> action;
suggest: func(ctx: context) -> list<suggestion>;
status: func(ping: ping) -> option<status-override>;
http: func(request: http-request) -> option<http-response>;
join: func(ctx: context);
after-transfer: func(ctx: context);
disconnect: func(ctx: context);
message: func(message: bus-message);
timer: func(handle: u64);
event: func(event: rift-event);
}
/// Dialog clicks (since 0.1.1). Optional: the host calls it only for
/// components that export it, so components built against 0.1.0 still load.
/// It runs as an observer, under the same limit as `join`.
interface dialogs {
use types.{dialog-response};
/// A player clicked a plugin action of a dialog this plugin showed.
dialog: func(response: dialog-response);
}
/// The decision hooks answering with rich text (since 0.1.2). Optional: for a
/// component that exports it, the host calls these instead of the `handler`
/// functions of the same names, so components built against 0.1.0 and 0.1.1
/// still load. Deadlines and failure policies are those of the hooks.
interface decisions {
use types.{context, decision};
login: func(ctx: context) -> decision;
initial-server: func(ctx: context) -> decision;
before-transfer: func(ctx: context) -> decision;
command: func(ctx: context) -> decision;
}
/// The `suggest` and `status` hooks answering with rich text (since 0.1.4).
/// Optional: for a component that exports it, the host calls these instead
/// of the `handler` functions of the same names, so components built against
/// 0.1.0 to 0.1.3 still load. Deadlines and failure policies are those of the
/// hooks.
interface styled {
use types.{context, rich-suggestion, ping, rich-status-override};
suggest: func(ctx: context) -> list<rich-suggestion>;
status: func(ping: ping) -> option<rich-status-override>;
}
/// Chat messages and backend commands before the backend sees them (since
/// 0.1.5), for mutes and filters. Optional, and unlike the other optional
/// exports it is the registration: the host asks every component that exports
/// it, about every message of every player, and no entry in the `hook` list
/// is needed. So only components that moderate chat export it; the SDKs leave
/// it out unless a plugin asks for it (worlds `plugin-chat` and `core-chat`).
///
/// Withholding one signed message breaks a player's signature chain, so a
/// component that exports `chat` starts only with
/// `authentication.signed_chat = false`, which makes backends take chat as
/// unsigned. Commands that Rift or a plugin owns never come here. The
/// deadline is 50 ms unless the manifest sets `deadlines.chat`; a missed
/// deadline or a failure applies the manifest's policy, where `deny` drops
/// the message.
interface chat {
use types.{chat-attempt, decision};
/// Accepts `continue` (the backend receives the packet unchanged), and
/// `deny` and `deny-json` (the packet is dropped and the player sees the
/// text).
chat: func(attempt: chat-attempt) -> decision;
}
/// Every import and the exports every component has, without WASI: what the
/// host requires. Exports added in later 0.1 releases are looked up
/// separately.
world base {
import players;
import store;
import permissions;
import bus;
import servers;
import timers;
import log;
import meta;
export handler;
}
/// The optional exports, which the host looks up one by one: one world
/// each, so a component may have any of them.
world optional {
export dialogs;
}
world optional-decisions {
export decisions;
}
world optional-styled {
export styled;
}
world optional-chat {
export chat;
}
/// Imports and exports without WASI; the host links WASI separately.
world core {
include base;
export dialogs;
export decisions;
export styled;
}
/// `core` for a component that also exports `chat`.
world core-chat {
include core;
export chat;
}
/// The world guests build against. TinyGo's `wasip2` target expects the
/// WASI CLI import set even when a plugin does not use it.
world plugin {
include wasi:cli/imports@0.2.0;
include core;
}
/// `plugin` for a component that also exports `chat`.
world plugin-chat {
include plugin;
export chat;
}