Host calls

Worlds, time, border, game rules, sound and particles

Facts about a world as a whole, and effects played in 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.

game_rule_flag

fn game_rule_flag(rule: &str) -> bool

A boolean game rule, by the short name /gamerule uses.

A rule is not a setting the engine applies on a plugin's behalf, and it cannot be. drowning_damage and fire_damage each name one specific arithmetic -- the two points of drowning damage every twenty ticks, the one point of burning damage -- and nothing but the rule that does that arithmetic knows which of its own effects the flag governs. An engine that tried would have to know that fire_damage stops the damage and leaves the fire, which is a fact about the rule.

An unknown name answers false rather than an error, because this is called from the middle of a tick. So a misspelt or renamed rule reads false silently: check the name against /gamerule.

Wasm request

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

{"call": "game_rule_flag", "rule": "keep_inventory"}

game_rule_number

fn game_rule_number(rule: &str) -> i32

A numeric game rule, by the short name /gamerule uses. Nought for a name that is not a rule, for game_rule_flag's reason.

Wasm request

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

{"call": "game_rule_number", "rule": "keep_inventory"}

world_spawn

fn world_spawn(world: &World) -> Option<Vec3>

Where a new player appears in this world: what a /spawn command sends somebody to.

Wasm request

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

{"call": "world_spawn", "world": "minecraft:overworld"}

play_sound

fn play_sound(player: PlayerId, sound: &str, category: &str, volume: f32, pitch: f32) -> bool

Plays one of the game's sounds to one player, where they stand: sound by name (minecraft:entity.experience_orb.pickup), category the client's volume slider it obeys (players, blocks, hostile, neutral, ambient, weather, records). False for nobody there, a sound the game does not have or a category it does not know.

Wasm request

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

{"call": "play_sound", "player": 7, "category": "master", "volume": 1.0, "pitch": 1.0, "sound": "minecraft:entity.experience_orb.pickup"}

sound_at

fn sound_at(world: &World, at: Vec3, sound: &str, category: &str, volume: f32, pitch: f32) -> bool

Plays a sound at a place, to everybody near enough to hear it, as play_sound names one.

Wasm request

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

{"call": "sound_at", "world": "minecraft:overworld", "to": [10.5, 64.0, -2.5], "category": "master", "volume": 1.0, "pitch": 1.0, "sound": "minecraft:entity.experience_orb.pickup"}

particle

fn particle(world: &World, particle: &str, at: Vec3, count: i32, spread: Vec3, speed: f32) -> bool

Shows count of a particle at a place, scattered over spread (each axis's standard deviation) and moving at speed, to everybody near enough to see. Only particles that carry no options (minecraft:heart, minecraft:end_rod); false for one that does, or one the game does not have. At most 1000 a call.

Wasm request

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

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

{"call": "particle", "world": "minecraft:overworld", "to": [10.5, 64.0, -2.5], "count": 1, "spread": [0.5, 0.5, 0.5], "speed": 0.0, "particle": "minecraft:flame"}

world_floor

fn world_floor(world: &World) -> Option<i32>

The lowest y a block may exist at in this world.

Dimension state, and it is not the same in two of them: the overworld's floor is at minus sixty-four and the Nether's at nought. A rule that assumed one number would be wrong by sixty-four blocks in the other, and a plugin cannot work it out for itself -- the value comes out of the dimension type, which the engine reads, persists and sends to a joining client.

position says how far down somebody is; this says how far down is out of the world.

Wasm request

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

{"call": "world_floor", "world": "minecraft:overworld"}

world_ceiling

fn world_ceiling(world: &World) -> Option<i32>

One past the highest y a block may exist at in this world.

Wasm request

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

{"call": "world_ceiling", "world": "minecraft:overworld"}

time_of_day

fn time_of_day(world: &World) -> Option<i64>

The time of day, in ticks, out of twenty-four thousand.

Wasm request

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

{"call": "time_of_day", "world": "minecraft:overworld"}

set_time_of_day

fn set_time_of_day(world: &World, ticks: i64) -> bool

Sets a world's clock, as /time set does. Whether the world is there.

Wasm request

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

{"call": "set_time_of_day", "world": "minecraft:overworld", "ticks": 100}

local_difficulty

fn local_difficulty(world: &World, at: BlockPos) -> Option<f32>

The local difficulty at a place, which is not the world's difficulty setting.

DifficultyInstance.getSpecialMultiplier(). The setting is one of four words; this is a float that climbs with the world's age, the chunk's inhabited time and the moon, and it is nought on a young world however hard the setting is. The game uses it for:

The setting alone will not do, and that is why this is its own method rather than a difficulty() returning a word. Given the setting, every one of those five is constant from the first minute of a world, and a new world's skeletons carry enchanted bows — which is the game's own trap, written the wrong way round.

None for a world the host does not have, which is not the same as nought: nought is a real answer and the commonest one.

Wasm request

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

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

world_border

fn world_border(world: &World) -> Option<(f64, f64, f64)>

Where the world stops: the centre, and the full width rather than the half-width.

Here for the same reason time_of_day is: it is world state, persisted and sent to a client as it joins, and a plugin that owned it would have to own the packet and the save format with it. What a plugin does about a player being outside is a rule and belongs to the plugin; where the wall is, is not.

The width, not the half-width. getMinX is centre - size / 2, so a border reported as its half-width puts every wall twice as far out as it is and the rule reading it never fires.

Wasm request

Router notes: Answered as {centre_x, centre_z, size}, in blocks, so the fields are named rather than told apart by their order.

Reply: {"ok": ...} holding the Rust return value Option<(f64, f64, f64)>, encoded as in conventions; objects in it carry centre_x, centre_z, size.

{"call": "world_border", "world": "minecraft:overworld"}

world_border_damage

fn world_border_damage(world: &World) -> Option<(f64, f64)>

What being outside costs: the damage per block past the safe zone, and the safe zone.

WorldBorder.getDamagePerBlock and getSafeZone, which /worldborder damage amount and damage buffer change. None means the game's defaults, 0.2 and 5.

Wasm request

Reply: {"ok": ...} holding the Rust return value Option<(f64, f64)>, encoded as in conventions; objects in it carry per_block, safe_zone.

{"call": "world_border_damage", "world": "minecraft:overworld"}

set_world_border

fn set_world_border(world: &World, centre_x: f64, centre_z: f64, size: f64) -> bool

Moves it. Returns whether anything changed.

The engine sends the packet, because the wire format and the join sequence are its business; the caller supplies the number.

Wasm request

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

{"call": "set_world_border", "world": "minecraft:overworld", "centre_x": 1.0, "centre_z": 1.0, "size": 1.0}

worlds

fn worlds() -> Vec<World>

Every world this server serves, by name: minecraft:overworld and whichever of the Nether and the End are enabled.

Wasm request

No fields besides call.

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

{"call": "worlds"}

chunk_on_disk

fn chunk_on_disk(world: &World, chunk_x: i32, chunk_z: i32) -> Option<bool>

Whether a chunk has been written to disk (may read a region file's header from disk when it is not cached; refused past 1,875,000 chunks from the origin).

None for a world this server does not serve.

On disk, not merely generated: a chunk built a moment ago and not yet saved would be built again after a crash, which is the question a pre-generator is really asking. May read the region file's header from disk when it is not cached, so ask about many chunks sparingly. A chunk beyond 1,875,000 chunks of the origin is refused.

Wasm request

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

{"call": "chunk_on_disk", "world": "minecraft:overworld", "x": 1, "z": 1}

world_sidecar

fn world_sidecar(world: &World, name: &str) -> Option<String>

A file the world's generator left beside it (Generator::sidecars), by its plain file name, or None where there is none.

What a generator plans as it makes a world -- the sites it levelled for landmarks, where its resources suit the ground -- for a gameplay plugin to read instead of an admin placing them by hand. Read from the world's generated/ folder, so it survives restarts and can be read on a server that has stopped generating; None for a world this server does not serve, a name that is not one plain [a-z0-9._-] file name, or a file over four megabytes.

Wasm request

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

{"call": "world_sidecar", "world": "minecraft:overworld", "name": "Steve"}

world_id

fn world_id(world: &World) -> Option<String>

What tells this world from any other that has stood in its place: None for a dimension this server does not serve, or a folder it cannot write to.

Plugin storage lives beside the world and outlives it, so a row kept by position would otherwise carry over to a fresh world under the same name. Made once, kept in the file rustmc-world-id beside level.dat, so a backup keeps it and --restore brings it back. Deleting the folder ends it; a wipe that clears the regions and keeps the folder keeps it. All the dimensions of a level open that one folder, so they answer the same: this names the level, and a plugin keys a dimension's rows with the dimension as well.

Wasm request

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

{"call": "world_id", "world": "minecraft:overworld"}

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