Reference

Manifest

A plugin's manifest tells the server who the plugin is and what it wants. The server reads it once, at load, so it can decide whether to call a plugin without calling it. A Rust plugin returns a Manifest from Plugin::manifest. A Wasm guest emits it as JSON from rustmc_manifest (the ABI).

Every field but name may be left out. Unknown JSON fields are ignored.

events and hooks default in opposite directions on purpose. Being told about something costs a plugin nothing it did not ask for. Being run instead of the game is something a plugin has to ask for.

No manifest field grants access to host calls: every plugin may make every call. What reaches outside the server (outbound HTTP to a fixed URL, listening on a port) needs the server owner's grant in rustmc.yml instead (host calls).

Load-time checks

A manifest is refused, and the plugin not loaded, when:

• the name is empty, longer than 64 characters, or holds anything but letters, digits, _ and -;
• a plugin of the same name is already loaded;
• a setting's key is not [a-z0-9_]{1,64}, is declared twice, is an enum with no values, or has a default its own type refuses;
• a page id is not [a-z0-9_-]{1,32};
• (Wasm) a hook names no point, or a mode other than prepend, override or append;
• (Wasm) a command names no name, or a setting has an unknown type;
• (Wasm) hooks is not empty and the module does not export rustmc_on_hook, or listens is not empty and it does not export rustmc_on_message.

A plugin that names extended handlers is logged once at load, so the owner can see it.

Subscription rules

• Events. Exact names from the event list. No families, no wildcards. An empty or missing list hears every event. A name that is no event matches nothing, so ["none"] hears nothing.
• Hooks. A point is an exact name (block.hardness) or a family ending in .* (packet.play.*, command.*), or * for every hook point. One plugin may hook the same point in several modes.
• Topics (listens) take exact names, family.*, or *.
• Handler keys (extended) are an event name, hook:<point> (a family as hooks takes it), menu (clicks in this plugin's menus), call (other plugins' calls) or topic:<topic>.
• fail_closed names events. Only a cancellable event can fail closed; any other name is ignored. A Wasm guest that was skipped because it was busy on another thread also counts as failed here.

Commands

A command is sent to clients in the command tree, so it appears in tab completion. When a player runs it, the plugin hears command_run with command (the name) and rest (the line after it, unparsed). Completions while typing are asked of the plugin through rustmc_on_message (the ABI). Each command is also a hook point, command.<name> (commands).

Settings

Each entry of settings is {"key", "type", "default", "title"?, "help"?, "group"?, "min"?, "max"?, "max_length"?, "max_items"?, "values"?, "secret"?}.

title is the form's label (the key when empty), help one line under it, and settings with the same group are drawn together. A secret setting (a password, a token) is never sent back to a browser in full. sql_submit reads a database URL only from a secret setting.

The server keeps the values in plugins/<plugin>/settings.json. The plugin reads them with the settings host call and changes its own with setting_set. When anybody changes them, the plugins that hear settings_changed are told, except a plugin changing its own.

Pages

A page adds a tab to the web portal. id is [a-z0-9_-]{1,32}, unique in the plugin, and title is what the tab says. The portal asks for a page over the plugin bus, as a call: {"op": "portal.page", "page", "viewer"}, and sends a page's actions the same way: {"op": "portal.action", "page", "action", "values", "viewer"}. The plugin answers {"components": [...]}: data the portal draws, never markup or script.

The call comes from rustmc:portal, a name no plugin can have, and viewer is the portal user looking. An answer with more than 200 components, or more than 256 KiB of JSON, is refused, as is one that is not {"components": [...]}. An answer {"error": "..."} is shown as an error.

Each component is an object with a type. Every string is drawn as text, never as markup.

A component of another type is not drawn. A component that fails to draw is replaced by a message in its place only. Whatever an action answers replaces the whole page. The guest SDK's portal module (sdk/src/portal.rs) builds these components.

Switching off vanilla systems

A gamemode that replaces one of the game's own systems names it in disables, and the server stops running it for as long as the plugin is loaded and alive. A plugin that panics and is unloaded hands the system back.

What mob_spawning stops

The rule: switched off, mob_spawning acts as if every game rule that gates the world's own spawning were off -- spawn_mobs (and with it spawn_monsters's spawns), spawn_patrols, spawn_phantoms, spawn_wandering_traders, spawn_wardens and raids -- and villagers summon no iron golems, which have no rule of their own. Everything those rules leave running still runs, and the two spawner blocks keep their own rules (spawner_blocks_work, and the trial spawner's spawn_mobs): they are blocks built to spawn, and a gamemode decides whether its world has any. The game rules themselves are not changed.

Stops:

Goes on:

The server reads all of these through one helper (spawn::world_spawns), and a test refuses any other code that reads the spawning rules directly, so a new spawn path cannot forget the switch.

Other names are ignored rather than refused, so a plugin written for a newer server still loads on an older one. It asks the disabled_systems host call which of its names were honoured. A server where no plugin asks pays one atomic read per check.

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