Host calls

Web map and chunk pre-generation

Drawing the web map, its markers, and queueing chunks to be generated ahead of players.

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.

render_web_map

fn render_web_map(world: &World) -> Result<bool, String>

Draws a world's web map now, once: Ok(true) when drawing starts, Ok(false) when it is drawn or being drawn already (or web-map.render is on-create), Err when the web map is off or does not draw that world.

For a gamemode that builds landmarks after a world is made: with web-map.render: on-plugin-signal the server waits for this call before it draws the map, then draws the chunks as they stand (the landmarks with them) and the generator's terrain everywhere else. A world's map is drawn once and never again, so call it as soon as what should be on the map stands, before players have built anything; calling again is harmless.

Wasm request

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

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

web_map_marker

fn web_map_marker(plugin: &str, world: &World, marker: &MapMarker) -> Result<bool, String>

Puts a labelled marker on a world's web map, or moves or renames the plugin's marker of the same id: Ok(true) when the map changed, Ok(false) when it was so already, Err when the web map is off, does not draw that world, or the marker is refused.

Markers are drawn over the map's tiles as a dot and a label; they are not part of the images, so setting one never redraws the map. Each belongs to the plugin that set it (two plugins may use the same id), is kept with the world's map so it survives a restart, and goes when that plugin is unloaded or removed. Its id is 1 to 64 of [A-Za-z0-9_.:-], its label 1 to 64 characters with no control characters, x and z block coordinates within 30,000,000 of the origin; a plugin may keep 512 markers a world. Setting a marker as it already is changes nothing, so a plugin may set its markers again at every start.

Wasm request

Shape and limits, as the router words its errors: "kind is landmark, monument or point, not …"; "… is out of range".

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": "web_map_marker", "x": 1, "z": 1, "world": "minecraft:overworld", "kind": "landmark", "id": "spawn", "label": "Spawn"}

web_map_remove_marker

fn web_map_remove_marker(plugin: &str, world: &World, id: &str) -> Result<bool, String>

Takes the plugin's marker of that id off a world's web map: Ok(true) when there was one, Ok(false) when there was none, Err when the web map is off or does not draw that world.

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": "web_map_remove_marker", "world": "minecraft:overworld", "id": "spawn"}

queue_chunks

fn queue_chunks(plugin: &str, world: &World, chunks: &[(i32, i32)]) -> Option<u32>

Queues chunks to be generated and written off the tick: at most 4096 outstanding per plugin and world, none past 1,875,000 chunks from the origin, None when read-only or stopping.

Generated on threads of their own. Answers how many were taken -- fewer than asked when the plugin has 4096 outstanding in that world (waiting, building, or finished and not yet asked about) -- or None for a world this server does not serve or cannot generate, a read-only server, or one stopping. Chunks beyond 1,875,000 chunks of the origin are refused.

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 Option<u32>, encoded as in conventions.

{"call": "queue_chunks", "world": "minecraft:overworld", "chunks": [[0, 0], [0, 1]]}

chunks_generated

fn chunks_generated(plugin: &str, world: &World) -> Generated

What became of the chunks this plugin queued in that world since it last asked. Each finished chunk is reported once.

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 Generated, encoded as in conventions; objects in it carry done, failed, waiting.

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

unqueue_chunks

fn unqueue_chunks(plugin: &str, world: &World) -> u32

Drops this plugin's chunks still waiting in that world; one being built finishes and is reported. Answers how many were dropped.

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 u32, encoded as in conventions.

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

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