Host calls

Tab list, nametags, sidebar, boss bars and scores

What each player sees in the tab list, over heads, in the sidebar and in boss bars.

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.

show_sidebar

fn show_sidebar(player: PlayerId, title: &str, lines: &[String]) -> Result<bool, String>

Shows one person a sidebar of their own: a title and up to 15 lines, top to bottom, each a text component as message_text takes them, drawn without numbers. Showing again replaces it. The server's /scoreboard sidebar is left alone; whichever was shown last is what the player sees. Answers whether they were there; an error for a bad component or too many lines.

Wasm request

Shape and limits, as the router words its errors: "title should be a text component"; "lines should be a list of text components".

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

{"call": "show_sidebar", "player": 7, "title": {"text": "Title"}, "lines": [{"text": "line"}]}

show_sidebar_lines

fn show_sidebar_lines(plugin: &str, player: PlayerId, title: &str, lines: &[crate::tab::SidebarLine]) -> Result<bool, String>

Shows one person a sidebar whose lines each have their own right-hand side: a text component where the number would be, or a number, or nothing (TAB's text||format||score). Up to 15 lines, top to bottom, which keep their order whatever they show. Showing again sends only what changed -- the title, each changed line, the lines no longer there -- so a board redrawn every tick does not flicker. Taken away when plugin is unloaded; show_sidebar is unchanged beside it, and either replaces the other. Answers whether they were there; an error for a bad component or too many lines.

Wasm request

Shape and limits, as the router words its errors: "title should be a text component"; "lines should be a list of …"; "each line's text should be a text component"; "a line's score should be a whole number that fits in 32 bits, not …".

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": "show_sidebar_lines", "player": 7, "title": {"text": "Title"}, "lines": [{"text": "line"}]}

boss_bar_show

fn boss_bar_show(plugin: &str, player: PlayerId, id: &str, bar: &crate::tab::BossBar) -> Result<bool, String>

Shows one person a boss bar, or changes it if they have it: id is the plugin's own name for it, and the server keeps the wire's for each plugin and id, so the game's own bars -- raids, the wither, the dragon, /bossbar -- are never touched. Showing again sends only what changed. Taken away when plugin is unloaded. Answers whether they were there; an error for a bad title, a progress outside 0 to 1, or an id empty or over 64 characters.

Wasm request

Shape and limits, as the router words its errors: "bar should be …"; "bar.title should be a text component"; "… is not a boss bar colour"; "… is not a boss bar style".

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": "boss_bar_show", "player": 7, "id": "spawn", "bar": {"title": {"text": "Raid"}, "progress": 0.5, "colour": "red"}}

boss_bar_hide

fn boss_bar_hide(plugin: &str, player: PlayerId, id: &str) -> bool

Takes one of this plugin's boss bars off a player's screen; false if they did not have 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": "boss_bar_hide", "player": 7, "id": "spawn"}

hide_sidebar

fn hide_sidebar(player: PlayerId) -> bool

Takes away the sidebar show_sidebar gave a player; false if they had none.

Wasm request

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

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

set_list_name

fn set_list_name(player: PlayerId, name: Option<&str>) -> Result<bool, String>

Shows a player in everybody's tab list under name (a text component), or as themselves again for None; kept for players who join later. False for nobody there.

Wasm request

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

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

set_list_order

fn set_list_order(player: PlayerId, order: i32) -> bool

Where a player sorts in everybody's tab list: higher first. False for nobody there.

Wasm request

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

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

{"call": "set_list_order", "player": 7, "order": 1}

set_list_name_for

fn set_list_name_for(plugin: &str, viewer: PlayerId, target: PlayerId, name: Option<&str>) -> Result<bool, String>

Shows target in one viewer's tab list under name (a text component), over the name set_list_name gives everybody; None shows that viewer what everybody sees again. Kept by the server, so the server's own re-sends keep it, and taken back when either player leaves or plugin is unloaded. False for a viewer or target not there; an error for a bad component.

Wasm request

Router notes: The plugin is always the caller: a guest changes the views it owns, never another's. 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": "set_list_name_for", "viewer": 7, "target": 8}

set_list_name_for_batch

fn set_list_name_for_batch(plugin: &str, entries: &[crate::tab::ForViewer<Option<String>>]) -> Result<u32, String>

set_list_name_for for up to MAX_BATCH entries at once, each viewer's sent as one packet. How many applied (both players there); an error, and nothing changed, for a bad component or too many entries.

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

{"call": "set_list_name_for_batch", "entries": []}

set_listed_for

fn set_listed_for(plugin: &str, viewer: PlayerId, target: PlayerId, listed: bool) -> bool

Whether target is in one viewer's tab list at all: what a per-world player list hides people with. Their body is still in the world, only their row is gone. Kept as set_list_name_for is. False for a viewer or target not there.

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": "set_listed_for", "listed": true, "viewer": 7, "target": 8}

set_listed_for_batch

fn set_listed_for_batch(plugin: &str, entries: &[crate::tab::ForViewer<bool>]) -> Result<u32, String>

set_listed_for for up to MAX_BATCH entries; how many applied.

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

{"call": "set_listed_for_batch", "entries": []}

set_list_game_mode_shown_for

fn set_list_game_mode_shown_for(plugin: &str, viewer: PlayerId, target: PlayerId, mode: Option<GameMode>) -> bool

The game mode one viewer's tab list shows for target, over their real one -- a spectator shown as survival, so they are not greyed out at the bottom -- or None for the real one. Only the row: the viewer's world is untouched. Not for a player's own row, which their client reads its own game mode from (false). Kept as set_list_name_for is.

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": "set_list_game_mode_shown_for", "viewer": 7, "target": 8}

set_list_game_mode_shown_for_batch

fn set_list_game_mode_shown_for_batch(plugin: &str, entries: &[crate::tab::ForViewer<Option<GameMode>>]) -> Result<u32, String>

set_list_game_mode_shown_for for up to MAX_BATCH entries; how many applied.

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

{"call": "set_list_game_mode_shown_for_batch", "entries": []}

set_list_latency

fn set_list_latency(plugin: &str, target: PlayerId, latency: Option<u32>) -> bool

The latency everybody's tab list shows for target, in milliseconds, over the measured one (a ping spoof); None shows the measured one again. latency still answers the real one. Kept for players who join later, and taken back when plugin is unloaded. False for nobody there.

Wasm request

Shape and limits, as the router words its errors: "latency should be whole milliseconds, not …".

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_list_latency", "target": 8}

set_nametag

fn set_nametag(plugin: &str, player: PlayerId, nametag: Option<&crate::tab::Nametag>) -> Result<bool, String>

Gives a player a nametag: a prefix and suffix (text components) around their name, over their head and in the tab list, its colour, who sees it and who pushes them. None takes it away. The server owns the team that draws it. While it is set, every client is shown it in place of the player's /team team, which still applies on the server (friendly fire, selectors, /team list); clearing it shows their /team team again. Taken back when plugin is unloaded. False for nobody there; an error for a bad component or colour.

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": "set_nametag", "player": 7}

set_nametag_batch

fn set_nametag_batch(plugin: &str, entries: &[(PlayerId, Option<crate::tab::Nametag>)]) -> Result<u32, String>

set_nametag for up to MAX_BATCH players at once; how many applied (the player there). An error, and nothing changed, for a bad tag or too many entries.

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

{"call": "set_nametag_batch", "entries": []}

set_nametag_for

fn set_nametag_for(plugin: &str, viewer: PlayerId, target: PlayerId, nametag: Option<&crate::tab::Nametag>) -> Result<bool, String>

Gives target a nametag as one viewer sees it, over the one set_nametag gives everybody: a relational prefix or suffix, or the tag hidden from that viewer alone (visibility: never). None shows that viewer everybody's tag again, or the player's /team team when there is none. What a viewer sees is, first to last: their own tag, everybody's, /team's. Taken back when either player leaves or plugin is unloaded. False for a viewer or target not there; an error for a bad component or colour.

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": "set_nametag_for", "viewer": 7, "target": 8}

set_nametag_for_batch

fn set_nametag_for_batch(plugin: &str, entries: &[crate::tab::ForViewer<Option<crate::tab::Nametag>>]) -> Result<u32, String>

set_nametag_for for up to MAX_BATCH entries; how many applied. An error, and nothing changed, for a bad tag or too many entries.

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

{"call": "set_nametag_for_batch", "entries": []}

set_below_name

fn set_below_name(plugin: &str, viewer: PlayerId, target: PlayerId, score: Option<&crate::tab::Score>) -> Result<bool, String>

The number one viewer sees under target's name, with its own number format; None takes it away. Drawn by an objective the server owns, shown only to viewers given a score in it: their first score puts it in the below-name slot, their last one taken away gives that slot back to whatever /scoreboard shows there. Taken back when either player leaves or plugin is unloaded. False for a viewer or target not there; an error for a bad format.

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": "set_below_name", "viewer": 7, "target": 8}

set_below_name_batch

fn set_below_name_batch(plugin: &str, entries: &[crate::tab::ForViewer<Option<crate::tab::Score>>]) -> Result<u32, String>

set_below_name for up to MAX_BATCH entries; how many applied.

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

{"call": "set_below_name_batch", "entries": []}

set_list_score

fn set_list_score(plugin: &str, viewer: PlayerId, target: PlayerId, score: Option<&crate::tab::Score>) -> Result<bool, String>

The number one viewer's tab list shows beside target, as set_below_name does under their name: the tab-list objective, drawn as a number or as hearts (list_score_render).

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": "set_list_score", "viewer": 7, "target": 8}

set_list_score_batch

fn set_list_score_batch(plugin: &str, entries: &[crate::tab::ForViewer<Option<crate::tab::Score>>]) -> Result<u32, String>

set_list_score for up to MAX_BATCH entries; how many applied.

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

{"call": "set_list_score_batch", "entries": []}

objective_title

fn objective_title(slot: &str, title: &str) -> Result<bool, String>

The title of the plugin objective in slot (below_name or list), a text component, for every viewer: what below-name draws after each number. An error for another slot or a bad component.

Wasm request

Shape and limits, as the router words its errors: "title should be a text component".

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

{"call": "objective_title", "slot": "below_name", "title": {"text": "Title"}}

list_score_render

fn list_score_render(render: crate::tab::ScoreRender) -> bool

Whether the plugin tab-list objective draws its numbers as numbers or as hearts, for every viewer.

Wasm request

Shape and limits, as the router words its errors: "… is not integer or hearts".

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

{"call": "list_score_render", "render": "integer"}

list_fake_entries

fn list_fake_entries(plugin: &str, viewer: PlayerId, entries: &[crate::tab::FakeEntry]) -> Result<bool, String>

Shows one viewer plugin's fake tab-list rows -- TAB's layout -- in place of the ones it showed them before: up to MAX_FAKE_ENTRIES profiles that are nobody, each with its own text, latency, game mode, skin and order. The same id is the same row from one call to the next, changed in place; rows left out are taken away, and an empty list takes them all. Only that viewer sees them. Taken back when the viewer leaves or plugin is unloaded. False for a viewer not there; an error, and nothing changed, for a bad row.

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": "list_fake_entries", "entries": [], "viewer": 7}

list_fake_entries_batch

fn list_fake_entries_batch(plugin: &str, viewers: &[(PlayerId, Vec<crate::tab::FakeEntry>)]) -> Result<u32, String>

list_fake_entries for many viewers at once, up to MAX_BATCH rows in all; how many viewers were there. An error, and nothing changed, for any bad row.

Wasm request

Shape and limits, as the router words its errors: "viewers should be a list"; "at most 1000 viewers a call, not …".

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

{"call": "list_fake_entries_batch", "viewers": [7]}

set_tab_header

fn set_tab_header(player: PlayerId, header: &str, footer: &str) -> Result<bool, String>

The lines above and below one player's tab list, as text components ("" for none).

Wasm request

Shape and limits, as the router words its errors: "header should be a text component"; "footer should be a text component".

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

{"call": "set_tab_header", "player": 7, "header": {"text": "Header"}, "footer": {"text": "Footer"}}

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