Host calls

The server network: cross-server messages, presence and hopping

Publishing to the other servers network in rustmc.yml links, hearing them, who is on each, and sending players across.

Generated by tools/gen_api_docs.py; do not edit by hand. See host calls for how a call is made and how values are encoded. Each example shows the shape of a Wasm request with its required fields; the values in it are illustrative.

network_name

fn network_name() -> Option<String>

This server's name on the network, network.name in rustmc.yml: None while the network is off, which is how a plugin that works alone or across servers tells which.

Wasm request

No fields besides call.

Router notes: The publisher and the subscriber are the manifest's name: the namespace a plugin may use is its own, so a guest that could name another could speak on its channels.

Reply: {"ok": ...} holding the Rust return value Option<String>, encoded as in conventions.

{"call": "network_name"}

network_servers

fn network_servers() -> Vec<crate::value::NetworkServer>

Every server on the network, this one first and then each peer rustmc.yml names: whether this server's link to it is up (a publish now reaches it), how many players it has online, hidden ones not counted, and its max-players (nought until a peer has said). Empty while the network is off.

Wasm request

No fields besides call.

Reply: {"ok": ...} holding the Rust return value Vec<crate::value::NetworkServer>, encoded as in conventions; objects in it carry name, up, online, max, this.

{"call": "network_servers"}

network_publish

fn network_publish(plugin: &str, channel: &str, payload: &[u8], local: bool) -> Result<u32, String>

Sends payload on channel to every peer whose link is up, and to this server's own subscribers -- the publisher among them, if it subscribed -- unless local is false. Answers how many peers it went to, so a publisher sees the link's state; nought is a network where nobody else is up. Best effort: a peer whose link drops before the message is written never gets it, and nothing is sent again.

A channel is <namespace>:<name>, at most 128 bytes, with no spaces. A plugin may use only its own namespace, its manifest name (chat publishes chat:global), and those network.channels.<plugin> grants it. payload is at most MAX_NETWORK_PAYLOAD bytes. An error, and nothing sent, for a channel the plugin may not use, a payload too large, or a network that is off.

Needs: network.enabled in rustmc.yml; a channel outside the plugin's own namespace needs network.channels.<plugin> .

Wasm request

Router notes: plugin is never sent by a Wasm guest: the server fills it in from the manifest name.

Reply: {"ok": ...} holding the Rust return value Result<u32, String>, encoded as in conventions. An Err arrives as {"error": "..."}.

{"call": "network_publish", "channel": "example:channel"}

network_subscribe

fn network_subscribe(plugin: &str, channel: &str) -> Result<bool, String>

Hears channel as the network_message event, from every server, this one included. A name ending in * hears every channel it begins: chat:*. The same namespace rule as network_publish. Whether it is new; subscribing twice is one subscription. Forgotten when the plugin unloads, so a plugin subscribes in start. The plugin must also hear network_message in its manifest's events.

Needs: as network_publish.

Wasm request

Router notes: plugin is never sent by a Wasm guest: the server fills it in from the manifest name.

Reply: {"ok": ...} holding the Rust return value Result<bool, String>, encoded as in conventions. An Err arrives as {"error": "..."}.

{"call": "network_subscribe", "channel": "example:channel"}

network_unsubscribe

fn network_unsubscribe(plugin: &str, channel: &str) -> bool

Stops hearing what network_subscribe named, spelt as it was. Whether it was heard.

Wasm request

Router notes: plugin is never sent by a Wasm guest: the server fills it in from the manifest name.

Reply: {"ok": ...} holding the Rust return value bool, encoded as in conventions.

{"call": "network_unsubscribe", "channel": "example:channel"}

network_players

fn network_players() -> Vec<crate::value::NetworkPlayer>

Everyone online anywhere on the network, this server's players first, each with the server they are on and whether that server hides them. Peers say who is on as it changes, about once a second; a peer whose link is down has nobody listed. A hidden player is listed so that a plugin can show them to staff, and must not be shown to anybody else. Empty while the network is off.

Wasm request

No fields besides call.

Reply: {"ok": ...} holding the Rust return value Vec<crate::value::NetworkPlayer>, encoded as in conventions; objects in it carry uuid, name, server, hidden.

{"call": "network_players"}

network_send

fn network_send(player: PlayerId, server: &str) -> Result<bool, String>

Sends player to the peer named server, by the transfer packet to its join address in rustmc.yml. The peer must have accepts-transfers=true in its server.properties, or the client is refused at its door. False if the player has gone; an error for a server that is not a peer, has no join address, or a network that is off. Whether the peer is up is not checked: a client can reach a server this one cannot.

Needs: network.enabled, and a network.peers.<peer>.join address in rustmc.yml; the peer needs accepts-transfers=true.

Wasm request

Reply: {"ok": ...} holding the Rust return value Result<bool, String>, encoded as in conventions. An Err arrives as {"error": "..."}.

{"call": "network_send", "player": 7, "server": "<server>"}

From docs/api/reference/host-calls/server-network.md in the RustMC repository at bbd81209ad.