Host calls

Player state: health, food, experience, mode and movement

What a player has and is doing, and changing it.

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.

vitals

fn vitals(player: PlayerId) -> Option<Vitals>

Health, food and saturation.

Wasm request

Reply: {"ok": ...} holding the Rust return value Option<Vitals>, encoded as in conventions; objects in it carry health, food, saturation.

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

game_mode

fn game_mode(player: PlayerId) -> Option<GameMode>

The game mode a player is in; None for a player who is not here.

Wasm request

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

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

player_motion

fn player_motion(player: PlayerId) -> Option<Motion>

How a player is moving: their velocity, and whether they are sprinting, sneaking and on the ground. None for somebody who is not there.

Wasm request

Reply: {"ok": ...} holding the Rust return value Option<Motion>, encoded as in conventions; objects in it carry velocity, sprinting, sneaking, on_ground.

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

nudge_view

fn nudge_view(player: PlayerId, dyaw: f32, dpitch: f32) -> bool

Turns a player's view by dyaw and dpitch degrees from wherever it is on their screen: ClientboundPlayerRotationPacket with both relative flags, so a recoil kick adds to the player's own aim rather than snapping it back to where the server last heard it was. Whether they were there to turn.

Not a teleport: no position goes out and no teleport id is waited on, so a player running keeps running where their client has them, and none of their moves is held back for an acknowledgement. The pitch stops at straight up or down (±90), as the game's own does. False, turning nothing, for a delta that is not a finite number.

Wasm request

Shape and limits, as the router words its errors: "… should be a number of degrees".

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

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

teleport

fn teleport(player: PlayerId, to: Vec3) -> bool

Moves somebody. Returns whether there was anybody to move.

Wasm request

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

{"call": "teleport", "player": 7, "to": [10.5, 64.0, -2.5]}

set_game_mode

fn set_game_mode(player: PlayerId, mode: GameMode) -> bool

Puts a player in a game mode, as /gamemode does. Whether they were there to be changed.

Wasm request

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

{"call": "set_game_mode", "player": 7, "mode": "survival"}

statistic

fn statistic(player: PlayerId, stat: &str, key: &str) -> Result<Option<i32>, String>

One of a player's statistics, as the statistics screen counts it: stat is its type (minecraft:custom, minecraft:mined, minecraft:killed, ...) and key what it counts (minecraft:play_time, minecraft:stone, minecraft:zombie). Nought for one nothing has happened to; Ok(None) for a player who is not online; an error for a type or key the game does not have.

Wasm request

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

{"call": "statistic", "player": 7, "stat": "minecraft:custom", "key": "minecraft:jump"}

save_player

fn save_player(player: PlayerId) -> bool

Writes an online player's data file now, rather than at the next save. Whether it was written: false for somebody not online, or a server that is not saving players.

Wasm request

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

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

experience_points

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

The experience somebody could spend, in points: every level they have, and the bar's progress towards the next (Player.calculateTotalExperiencePoints, not the lifetime score). None for a player who is not online.

Wasm request

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

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

set_food

fn set_food(player: PlayerId, food: i32, saturation: f32) -> Result<bool, String>

Sets a player's food bar: food 0 to 20, saturation 0 to food, as the game keeps them. For a gamemode that switched hunger off and owns the bar; with hunger running the game goes on spending it. Exhaustion is reset. Ok(false) for a player who is not online; an error for a value outside those bounds.

Wasm request

Shape and limits, as the router words its errors: "food is 0 to 20".

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

{"call": "set_food", "player": 7, "food": 20}

set_health

fn set_health(player: PlayerId, health: f32) -> Result<bool, String>

Sets a player's health, as /data cannot: above nought and at most their maximum (which Health Boost raises), clamped to it. A dead player (health nought, waiting to respawn) is left dead. Ok(false) for one not online or dead; an error for nought or less, or a value that is not a number.

Wasm request

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

{"call": "set_health", "player": 7, "health": 20.0}

heal

fn heal(player: PlayerId, amount: f32) -> Result<Option<f32>, String>

Heals a player by amount, up to their maximum: what a regeneration tick does, without the effect. Answers their health after; None for one not online or dead. An error for an amount that is negative or not a number.

Wasm request

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

{"call": "heal", "player": 7, "amount": 4.0}

selected_slot

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

The hotbar slot a player has selected, 0-8, numbered as inventory_slot numbers it; None for one not online.

Wasm request

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

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

set_respawn

fn set_respawn(player: PlayerId, world: &World, at: BlockPos, yaw: f32) -> Result<bool, String>

Sets where a player respawns after dying, as /spawnpoint does: the block they stand in at at in world, facing yaw, needing no bed (two free blocks, or the world spawn). Kept in their player file. Ok(false) for a player not online; an error for a world the server does not have.

Wasm request

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

{"call": "set_respawn", "player": 7, "world": "minecraft:overworld", "at": [10, 64, -3]}

clear_respawn

fn clear_respawn(player: PlayerId) -> bool

Forgets a player's respawn point, so they respawn at the world spawn; whether anybody was there.

Wasm request

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

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

give_experience

fn give_experience(player: PlayerId, points: i32) -> Result<bool, String>

Gives experience points, as /xp add <player> <points>, or takes them when points is negative. Taking more than they could spend is refused (an error) and changes nothing. Ok(false) for a player who is not online.

Wasm request

Shape and limits, as the router words its errors: "points should be a whole number".

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

{"call": "give_experience", "player": 7, "points": 10}

swing_arm

fn swing_arm(player: PlayerId, off_hand: bool) -> bool

Swings a player's arm, as a hit or a use swings it, for them and everybody who can see them: the main hand, or the off hand with off_hand. For work a plugin times itself (a skill's action every few ticks) that the game would otherwise show no movement for. False for nobody there.

Wasm request

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

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

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