Host calls

Schematics

Loading and saving schematic files in the plugin's own folder.

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.

schematic_list

fn schematic_list(plugin: &str) -> Result<SchematicList, String>

What is in this plugin's schematic folder, plugins/<plugin>/schematics, at most 1,024 names.

Wasm request

No fields besides call.

Router notes: The folder and the tickets are the caller's, from the manifest, as a port is. 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<SchematicList, String>, encoded as in conventions; objects in it carry files, name, bytes, modified. An Err arrives as {"error": "..."}.

{"call": "schematic_list"}

schematic_load

fn schematic_load(plugin: &str, name: &str, keep_unsafe: bool) -> Result<u64, String>

Starts reading <name>.schem from this plugin's folder, a Sponge schematic of version 1 to 3, on a thread of its own, answering at once with a ticket for schematic_result. A name is 1 to 64 letters, digits, _ and -: nothing else reaches the filesystem. A file is untrusted: every limit is checked before it costs anything, and anything past one refuses the file. keep_unsafe keeps what a command block runs, what a spawner spawns and a sign's click events, which are otherwise dropped and counted. At most 2 loads and saves running on the server and 4 tickets held per plugin; one left unread goes after five minutes.

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<u64, String>, encoded as in conventions. An Err arrives as {"error": "..."}.

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

schematic_result

fn schematic_result(plugin: &str, ticket: u64) -> Option<Result<SchematicInfo, String>>

How a load or save went: None while it runs and for a ticket this plugin does not hold. A failure, and a finished save, forget the ticket.

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<Result<SchematicInfo, String>>, encoded as in conventions; objects in it carry error, size, offset, version, data_version, server_data_version, names, entities, unknown, unknown_kinds, entities_lost, entities_unsafe, entities_refused, fields_dropped, foreign_entities, bytes. An Err arrives as {"error": "..."}.

{"call": "schematic_result", "ticket": 1}

schematic_names

fn schematic_names(plugin: &str, ticket: u64, start: usize, count: usize) -> Result<Vec<Option<String>>, String>

Names start onwards of a loaded schematic, at most 256: None for a block this server does not know. Every other name is whole, in the server's own order, so two spellings of a state are one name.

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<Vec<Option<String>>, String>, encoded as in conventions. An Err arrives as {"error": "..."}.

{"call": "schematic_names", "ticket": 1, "start": 0, "count": 1}

schematic_cells

fn schematic_cells(plugin: &str, ticket: u64, start: usize, count: usize) -> Result<Vec<u16>, String>

Cells start onwards of a loaded schematic, at most 65,536, each an index into its names, x fastest, then z, then y.

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<Vec<u16>, String>, encoded as in conventions. An Err arrives as {"error": "..."}.

{"call": "schematic_cells", "ticket": 1, "start": 0, "count": 1}

schematic_entities

fn schematic_entities(plugin: &str, ticket: u64, start: usize, count: usize) -> Result<Vec<(BlockPos, String)>, String>

Block entities start onwards of a loaded schematic, at most count, 64 a call and 1 MiB: where, from the box's lowest corner, and SNBT set_block_data takes.

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<Vec<(BlockPos, String)>, String>, encoded as in conventions; objects in it carry at, snbt. An Err arrives as {"error": "..."}.

{"call": "schematic_entities", "ticket": 1, "start": 0, "count": 1}

schematic_save

fn schematic_save(plugin: &str, name: &str, size: [u32; 3], offset: [i32; 3], overwrite: bool) -> Result<u64, String>

Starts saving <name>.schem to this plugin's folder: a ticket for schematic_put, and then schematic_finish. Refused when the name is taken, unless overwrite. The box's lengths are x, y, z; offset is where its lowest corner goes from the player pasting it.

Wasm request

Shape and limits, as the router words its errors: "size should be three lengths".

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<u64, String>, encoded as in conventions. An Err arrives as {"error": "..."}.

{"call": "schematic_save", "size": [16, 16, 16], "offset": 1, "name": "Steve"}

schematic_put

fn schematic_put(plugin: &str, ticket: u64, piece: &SchematicPiece) -> Result<(), String>

The next piece of a schematic being saved.

Wasm request

Shape and limits, as the router words its errors: "names should be strings"; "cells is not base64: …"; "cells should be two bytes a cell".

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<(), String>, encoded as in conventions. An Err arrives as {"error": "..."}.

{"call": "schematic_put", "ticket": 1}

schematic_finish

fn schematic_finish(plugin: &str, ticket: u64) -> Result<(), String>

Writes a saved schematic out on a thread of its own, whole or not at all, as Sponge version 3. schematic_result says how it went.

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<(), String>, encoded as in conventions. An Err arrives as {"error": "..."}.

{"call": "schematic_finish", "ticket": 1}

schematic_close

fn schematic_close(plugin: &str, ticket: u64) -> bool

Lets go of a ticket, whatever it was doing. Whether this plugin held it.

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": "schematic_close", "ticket": 1}

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