Host calls

Players: who is here, visibility and moderation

Finding players, their identity and client, hiding them, bans, kicks and permission checks.

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.

players

fn players() -> Vec<PlayerId>

Everybody currently connected.

Wasm request

No fields besides call.

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

{"call": "players"}

player_name

fn player_name(player: PlayerId) -> Option<String>

A player's name, or None if they have gone.

Wasm request

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

{"call": "player_name", "player": 7}

player_uuid

fn player_uuid(player: PlayerId) -> Option<u128>

A player's uuid, as the sixteen bytes it is.

Wasm request

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

{"call": "player_uuid", "player": 7}

client_brand

fn client_brand(player: PlayerId) -> Option<String>

What a client calls itself, from minecraft:brand, if it ever said.

None covers both "not a vanilla client" and "has not sent it yet"; the two are not distinguishable and a plugin that treats an absence as a modded client will be wrong about the first few ticks of every join.

Wasm request

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

{"call": "client_brand", "player": 7}

latency

fn latency(player: PlayerId) -> Option<u32>

A player's latency in milliseconds, as their keep-alive answers measure it: the number the tab list's bars are drawn from (connection.latency(), a running average). The real one, whatever the tab list is told to show others. None for somebody who has gone.

Wasm request

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

{"call": "latency", "player": 7}

is_bedrock

fn is_bedrock(player: PlayerId) -> bool

Whether a player is connected through Bedrock rather than a Java client. Their own client draws only what the bridge translates; to every other player they look like anybody else. false for somebody who has gone.

Wasm request

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

{"call": "is_bedrock", "player": 7}

refresh_commands

fn refresh_commands(player: PlayerId) -> bool

Sends a player their command list again, decided afresh, at the next tick: for a permissions plugin, after a change that adds or removes a command they may run.

Wasm request

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

{"call": "refresh_commands", "player": 7}

set_hidden

fn set_hidden(player: PlayerId, level: Option<i32>, viewers: Option<&[PlayerId]>) -> bool

Hides a player from everybody who may not run something needing permission level or, given viewers, from everybody but those players (an unlisted operator too, and an empty list hides them from all): gone from their tab list and their world, as if they had left. Nobody is hidden from themselves. A level of None shows them again, and a guest that sends viewers with it is refused. Kept until changed or the player leaves; a plugin sends the list again when it changes. False if they are not connected.

Wasm request

Shape: level: null (or no level) shows the player to everybody again; viewers needs a level. At most 4096 viewers.

Shape and limits, as the router words its errors: "level is out of range"; "viewers holds at most … players, not …"; "viewers needs a level to hide below".

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

{"call": "set_hidden", "player": 7}

set_hidden_account

fn set_hidden_account(plugin: &str, account: u128, level: Option<i32>, viewers: Option<&[PlayerId]>) -> bool

set_hidden for an account, online or not: a player arriving on it is hidden before anything is sent about them. viewers are read as their accounts, so one who leaves and comes back still sees. A level of None forgets it and shows them. Kept in memory and dropped with the plugin, which sends its rows again at start. An account holds one row, so two plugins hiding it overwrite each other and either can show them: hiding is trusted to whichever plugin an owner installed, and no call checks a permission.

Wasm request

Shape: As set_hidden, by account id, for a player who may be offline.

Shape and limits, as the router words its errors: "level is out of range"; "viewers holds at most … players, not …"; "viewers needs a level to hide below".

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": "set_hidden_account", "account": "069a79f444e94726a5befca90e38aaf5"}

can_see

fn can_see(viewer: PlayerId, subject: PlayerId) -> bool

Whether viewer may see subject, for a plugin that lists players to a player.

Wasm request

Shape and limits, as the router words its errors: "… is out of range".

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

{"call": "can_see", "viewer": 7, "subject": 1}

ban

fn ban(name: &str, account: u128, reason: &str, source: &str, until_seconds: Option<u64>) -> bool

Puts name on the server's own ban list, with pardon and the login's refusal to go with it. until_seconds is when it lapses, seconds since 1970, capped at the end of year 9999; None is never. A ban that stands, from anybody, is left alone and the answer is false: a plugin lifts it first if it means to replace it. Any plugin may ban or pardon anybody; the caller answers for who asked. Nobody already online is removed: follow with kick.

Wasm request

Shape and limits, as the router words its errors: "until_seconds is seconds since 1970".

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

{"call": "ban", "account": "069a79f444e94726a5befca90e38aaf5", "name": "Steve", "reason": "", "source": "plugin"}

pardon

fn pardon(name: &str) -> bool

pardon: lifts name's ban, whoever made it, and answers whether there was one.

Wasm request

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

{"call": "pardon", "name": "Steve"}

banned

fn banned(name: &str) -> bool

Whether name stands banned on the server's list now.

Wasm request

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

{"call": "banned", "name": "Steve"}

hidden

fn hidden(player: PlayerId) -> Option<i32>

The permission level a player is hidden below, or None when everybody can see them.

Wasm request

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

{"call": "hidden", "player": 7}

player_named

fn player_named(name: &str) -> Option<PlayerId>

Finds somebody by name, case-insensitively, as a command would.

Wasm request

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

{"call": "player_named", "name": "Steve"}

watch_look

fn watch_look(plugin: &str, player: PlayerId, on: bool) -> bool

Starts or stops telling this plugin where a player looks: with it on, a player_look event each tick the player's yaw or pitch has changed since they were last told -- at most one a tick per player, carrying where they look by then. Only the plugins that asked hear it, and only for the players they asked about. False for a player who is not online.

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": "watch_look", "player": 7, "on": true}

watch_input

fn watch_input(plugin: &str, player: PlayerId, on: bool) -> bool

Starts or stops telling this plugin which movement keys a player holds: with it on, a player_input event each time the keys their client reports change -- forward, backward, left, right, jump, sneak, sprint -- and never while they hold the same ones. Only the plugins that asked hear it, and only for the players they asked about: a vehicle's driver, while they drive. False for a player who is not online.

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": "watch_input", "player": 7, "on": true}

kick

fn kick(player: PlayerId, reason: &str) -> bool

Throws somebody off the server, as /kick does: their client is shown reason (plain text, as message takes it; empty is the game's "Kicked by an operator") and closes the connection. A Bedrock player is shown it too, through the bridge. Answers whether anybody was there to kick.

Wasm request

Router notes: No reason is /kick's own, with none given.

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

{"call": "kick", "player": 7}

allows

fn allows(player: PlayerId, level: i32) -> bool

Whether somebody may run something needing this permission level.

The levels are the game's own five. A plugin with its own idea of permissions builds it on top of this rather than the server growing a second scheme.

Wasm request

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

{"call": "allows", "player": 7, "level": 1}

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