Plugin API

rustmc plugin API

rustmc is a Minecraft Java Edition server written from scratch in Rust. It speaks the protocol of Minecraft 26.3. It runs plugins written in Rust (compiled into the server) or in any language that compiles to WebAssembly (loaded from the server's plugins/*.wasm). Both kinds use the same contract.

A plugin can do three things:

• listen to events: something happened, and it may veto it;
• hook any step the game takes: run before it (prepend), instead of it (override), or after it (append);
• ask the server: read and change the world through the host calls.

With no plugins loaded, the server behaves like the vanilla dedicated server. Guarantees says what that means and how it is tested.

Coverage

Every list in this reference is checked against the code. The numbers below are written by python tools/gen_api_docs.py, which counts each kind in the source and in these pages, and stops with an error if an event or a named hook point has no row here. --check fails when a page is stale.

424 hook points in all, the same number python tools/api_check.py --list prints.

Start here

• Getting started: build, install and configure a WebAssembly plugin in Rust with the guest SDK, using a real plugin as the example.
• Host calls: everything a plugin can ask, in 19 groups, each call with its signature, fields, reply, limits and an example.

Contents

Guides

• Getting started with the guest SDK
• Your first Rust plugin (compiled into the server)
• Your first WebAssembly plugin: the raw ABI, with a hand-written .wat
• Creatures: spawning and ordering a plugin's own creatures
• Recipes: an alias command, a packet filter, a chat formatter, a block rule

Concepts

• Events: the closed list, priorities, cancelling
• Hooks: the three modes and how several plugins compose
• Data: Data, HookData and record!, the values that cross the boundary
• Guarantees: what the server promises, and what a plugin cannot break

Reference

• Manifest: every field, the load-time checks, subscription rules, settings
• Events: every event, its fields, and what cancelling it does
• Hook points, one page per family:
  • Commands: command.<root>
  • Packets: packet.<state>.<direction>.<name>, with pitfalls
  • Game events: the event names, as hook points
  • Subsystems: world generation, movement, blocks, loot, spawning, AI, redstone, fluids, portals, permissions
  • Generated index of every hook point
• Host calls, one page per group
• The guest SDK: rustmc-guest's functions and the calls each makes

WebAssembly

• The ABI: exports, imports, data encoding, the bus, menus, storage
• Limits: fuel, sizes, nesting, and what happens when a call fails

Contributing

• Adding a hook point
• How the API is proven: api_tests and tools/api_check.py

Stability

Nothing in the code is marked experimental. These parts are tied to things outside the API's control, so expect them to change between versions:

• Packet hooks and packet calls (packet.*, send_packet, packet_decode, packet_encode, packet_schemas). Their names come from the protocol's generated packet table and their bodies are the wire format, so both follow the game version. Prefer an event or a named hook point when one exists.
• Command hook points (command.<root>) follow the game's command tree.
• Block, item, entity and other ids follow the game's registries. A Wasm request's ids pass through the game's rename table, so a renamed id keeps working; a removed one does not.
• World generation as a plugin (rustmc_plugin::generator) is native only, and each generator is frozen to one game version (generation/<version>/ in the plugins repository).
• The Rust API (rustmc_plugin) is not published as a versioned crate. The Event enum is #[non_exhaustive], and adding an event or a Host method is a change to the crate. A Wasm guest is shielded from this: an unknown call answers an error, and an event it does not know is just a name it can ignore.

Hosting these pages

This folder is plain GitHub-flavoured Markdown with relative links, so it renders on GitHub as it is. To publish it with GitHub Pages, set the Pages source to the docs/ folder of a branch. This page is then served at /api/.

These are generated by python tools/gen_api_docs.py; regenerate them rather than editing them:

• reference/hooks/index.md;
• reference/host-calls.md and every page in reference/host-calls/;
• the coverage table on this page;
• reference/guest-sdk.md, with --sdk=<path to a rustmc-plugins checkout>.

Comments of the form <!-- path:line --> in these pages cite the source a statement was read from, as of the commit that last changed the page.

From docs/api/README.md in the RustMC repository at bbd81209ad.