Host calls

Inventory, items and components

Giving, taking, reading and editing stacks, cooldowns, dropped items and containers.

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.

inspect_open

fn inspect_open(viewer: PlayerId, account: u128, name: &str, view: &str, edit: bool, title: &str) -> Result<bool, String>

Opens another player's inventory (view is inventory) or ender chest (ender), kept up to date while it is open, for viewer: the account's file if they are offline. With edit the viewer moves items as in a chest, and each click is all or nothing against what the target is doing; InspectChange reports it. Answers false when there is nobody to open. Trusted as set_slot is: the server checks nothing about viewer, and the plugin asks its own nodes, and closes the view with inspect_close if they change.

Wasm request

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

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

{"call": "inspect_open", "account": "069a79f444e94726a5befca90e38aaf5", "viewer": 7, "name": "Steve", "view": "inventory", "title": "Steve's inventory"}

inspect_close

fn inspect_close(viewer: PlayerId) -> bool

Closes a view inspect_open opened: for when viewer has lost the right to it. Answers whether one was open. No other screen of theirs is touched.

Wasm request

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

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

{"call": "inspect_close", "viewer": 7}

set_slot

fn set_slot(player: PlayerId, slot: i32, item: &str, count: i32, components: &[(String, String)]) -> Result<bool, String>

Puts a stack in one slot of a player's own inventory, numbered as inventory_slot numbers them, in place of whatever was there: count 0 empties it. components as give_item takes them. An error for a count past what the stack holds (nothing spreads the rest over other slots), and for air with a count.

Wasm request

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

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

{"call": "set_slot", "player": 7, "slot": 0, "count": 1}

take_held

fn take_held(player: PlayerId, item: &str, count: i32) -> i32

Takes up to count of item from the stack in a player's main hand, if that stack is item, and tells their client; how many were taken. What a shrine's offering, or any "pay with what you hold", needs.

Wasm request

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

{"call": "take_held", "player": 7, "item": "minecraft:diamond"}

give

fn give(player: PlayerId, stack: &ItemStack) -> i32

Puts something in somebody's inventory, returning how many did not fit.

Wasm request

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

{"call": "give", "player": 7, "item": "minecraft:diamond"}

give_item

fn give_item(player: PlayerId, item: &str, count: i32, components: &[(String, String)]) -> Result<i32, String>

give, with data components: a name, lore, a glint, enchantments, a player's head -- anything /give can put on an item, spelt as /give spells it (each component's id and its SNBT, such as ("minecraft:custom_name", "{text:'Key',color:'gold'}")). Answers how many did not fit; an error for an unknown item, a component that is not one, or more than 16 KiB of SNBT. minecraft:max_stack_size is 1 to 99, as the game allows, and more than 1 only for an item that does not wear out; the server stacks such a stack to its own size, as the client does.

Wasm request

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

{"call": "give_item", "player": 7, "item": "minecraft:diamond"}

set_item_cooldown

fn set_item_cooldown(player: PlayerId, group: &str, ticks: i32) -> bool

Starts an item cooldown, as an ender pearl's: for ticks the client draws the sweep across every stack in the group, and it replaces any cooldown of the group running; nought ends one. The group is an item's id, or the cooldown_group of a minecraft:use_cooldown component give_item put on a plugin's own items. An item whose id is cooling is not used (and player_use_item is not told); a group of the plugin's own is the plugin's to check, with item_cooldown. Answers false for somebody who is not online, or a group that is not a namespaced id.

Wasm request

Shape and limits, as the router words its errors: "ticks is too large".

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

{"call": "set_item_cooldown", "player": 7, "ticks": 100, "group": "minecraft:ender_pearl"}

item_cooldown

fn item_cooldown(player: PlayerId, group: &str) -> i32

The ticks left of a group's cooldown (set_item_cooldown), nought when it is not cooling: the server's own pearls and wind charges included.

Wasm request

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

{"call": "item_cooldown", "player": 7, "group": "minecraft:ender_pearl"}

take_item

fn take_item(player: PlayerId, item: &str, count: i32, components: &[(String, String)]) -> Result<i32, String>

Takes up to count of item out of somebody's inventory, in /clear's order: the hotbar, the main inventory, then armour and the offhand (never the crafting grid). With components (as give_item spells them) only stacks that are that exact stack are taken -- a named key, not a plain one; with none, any stack of the item, named and enchanted ones included. Answers how many it could not take (nought: all of them), the mirror of give_item, so a plugin undoing a grant knows whether it is whole. count for a player who is not online; an error for an unknown item, a bad component or a count below one.

Wasm request

Shape: With custom_data this takes as take_item_where does; components and custom_data cannot both be given.

Shape and limits, as the router words its errors: "take_item_where needs custom_data to match"; "take_item matches by components or by custom_data, not both".

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

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

held_item

fn held_item(player: PlayerId) -> Option<ItemStack>

What somebody is holding.

Wasm request

Reply: {"ok": ...} holding the Rust return value Option<ItemStack>, encoded as in conventions; objects in it carry item, count, damage.

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

inventory_slot

fn inventory_slot(player: PlayerId, slot: i32) -> Option<InventoryItem>

What is in one slot of a player's own inventory, numbered as the game's Inventory numbers them: 0-8 the hotbar, 9-35 the rest, 36-39 the armour (feet, legs, chest, head), 40 the off hand. None for an empty slot, a slot past 40, or nobody.

Wasm request

Shape and limits, as the router words its errors: "slot is required".

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

{"call": "inventory_slot", "player": 7, "slot": 0}

edit_slot

fn edit_slot(player: PlayerId, slot: i32, stamp: &str, set: &[(String, String)], remove: &[String]) -> Result<String, String>

Changes the components of the stack in one slot of a player's own inventory, in place and only if it is still the stack stamp (from inventory_slot) describes: the count may have moved, nothing else. set puts each component, spelt as /give spells it; remove takes each named one off. The stack keeps everything else it carries -- its enchantments, wear, name -- because it is edited, never rebuilt.

Answers applied, empty (nothing is there now) or changed (something else is), and edits nothing for the last two. An error for an unknown component, SNBT that does not parse, a value the component cannot carry, or a minecraft:max_stack_size outside 1 to 99 (or above 1 on something that wears out, or below the stack's count).

Wasm request

Shape and limits, as the router words its errors: "slot is required".

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

{"call": "edit_slot", "player": 7, "stamp": "<stamp from inventory_slot>", "slot": 0}

take_slot

fn take_slot(player: PlayerId, slot: i32, stamp: Option<&str>) -> Result<crate::value::SlotTake, String>

Takes the whole stack out of one slot of a player's own inventory (numbered as inventory_slot numbers them) -- with a stamp (from inventory_slot), only if it is still the stack the stamp describes; with none, whatever is there -- and answers it as lossless text with its item and count. The text names one item -- no count -- so two stacks of one kind of item give the same text, byte for byte. Empty for an empty slot or nobody there, Changed for a different stack, and nothing is taken for either. An error, leaving the slot as it was, for a slot past 40 or a stack this server cannot write down whole.

Wasm request

Shape and limits, as the router words its errors: "slot is required".

Router notes: {"stack": text, "item": id, "count": n} for a stack taken, else "empty" or "changed". With no stamp (or a null one), whatever the slot holds.

Reply: {"ok": ...} holding the Rust return value Result<crate::value::SlotTake, String>, encoded as in conventions; objects in it carry stack, item, count. An Err arrives as {"error": "..."}.

{"call": "take_slot", "player": 7, "slot": 0}

give_stack

fn give_stack(player: PlayerId, snbt: &str, count: i32, spill: bool) -> Result<i32, String>

Gives count of exactly the stack snbt (text from take_slot) describes, spread over slots as give_item spreads it, answering how many did not fit -- or, with spill, dropping what did not fit at the player's feet as that same stack and answering nought. count for a player who is not online. An error, giving nothing, for text that does not parse or names no item, or a count below one or above give_item's most.

Wasm request

Shape and limits, as the router words its errors: "count should fit in 32 bits".

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

{"call": "give_stack", "player": 7, "count": 1, "stack": "<text from take_slot>"}

inventory_cursor

fn inventory_cursor(player: PlayerId) -> Option<InventoryItem>

The stack a player holds on the cursor in an open screen -- picked up and not yet put down -- as inventory_slot reports a slot's, with its stamp. None for an empty cursor or nobody there.

Wasm request

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

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

edit_cursor

fn edit_cursor(player: PlayerId, stamp: &str, set: &[(String, String)], remove: &[String], count: Option<i32>) -> Result<String, String>

edit_slot for the stack on the cursor: its components set and removed, and with count its count set too (nought empties the cursor; otherwise 1 to what the stack, as edited, stacks to), only if it is still the stack stamp describes. Answers applied, empty or changed, and the client is shown the cursor as it now is. An error, changing nothing, for what edit_slot refuses or a count out of bounds.

Wasm request

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

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

{"call": "edit_cursor", "player": 7, "stamp": "<stamp from inventory_slot>"}

item_sum_where

fn item_sum_where(player: PlayerId, item: Option<&str>, custom_data: &[(String, String)], sum_key: &str) -> Result<Option<i64>, String>

item_count_where, summing a number the stacks carry rather than counting them: for each matching stack, its count times the whole number its minecraft:custom_data holds at sum_key -- or times one where the key is missing or not a whole number. For a plugin whose one stack stands for many (myplugin:count). Ok(None) for a player who is not online; an error as item_count_where errs, or for an empty sum_key.

Wasm request

Shape and limits, as the router words its errors: "item_sum_where needs custom_data to match".

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

{"call": "item_sum_where", "player": 7, "sum_key": "value"}

item_count

fn item_count(player: PlayerId, item: &str) -> Result<Option<i32>, String>

How many of item somebody carries: their main inventory, hotbar, armour and offhand (not the crafting grid). Ok(None) for a player who is not online, who is not the same as one carrying none; an error for an item this version does not have.

Wasm request

Shape: With custom_data this counts as item_count_where does, and item becomes optional.

Shape and limits, as the router words its errors: "item_count_where needs custom_data to match".

Router notes: With custom_data, the stacks that carry it, of item or of any item.

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

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

item_count_where

fn item_count_where(player: PlayerId, item: Option<&str>, custom_data: &[(String, String)]) -> Result<Option<i32>, String>

item_count by what the stacks carry: of item (any item when None), only the stacks whose minecraft:custom_data holds every (key, snbt) of custom_data -- a plugin's own items, counted in one call whatever they are made of, such as [("myplugin:id", "\"timber\"")]. Other keys the data holds do not matter, as for the game's own custom_data predicate; a number matches a number of any width. Ok(None) for a player who is not online; an error for an unknown item, SNBT that does not parse, or neither an item nor any data to match.

Wasm request

Shape: item_count with custom_data is routed here too.

Shape and limits, as the router words its errors: "item_count_where needs custom_data to match".

Router notes: With custom_data, the stacks that carry it, of item or of any item.

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

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

take_item_where

fn take_item_where(player: PlayerId, item: Option<&str>, count: i32, custom_data: &[(String, String)]) -> Result<i32, String>

take_item by what the stacks carry, as item_count_where matches them: up to count of the stacks whose custom data holds every (key, snbt), of item or of any item. Answers how many it could not take.

Wasm request

Shape: take_item with custom_data is routed here too.

Shape and limits, as the router words its errors: "take_item_where needs custom_data to match"; "take_item matches by components or by custom_data, not both".

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

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

drop_item

fn drop_item(world: &World, at: Vec3, item: &str, count: i32, components: &[(String, String)], velocity: Option<Vec3>) -> Result<Option<EntityId>, String>

Drops a stack into the world as an item entity at at: item with count and data components (as give_item takes them), moving at velocity blocks a tick or with the little scatter a dropped item has. It can be picked up at once. Answers its entity id; None for a world the server does not have. An error for a bad item, count or component.

Wasm request

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

{"call": "drop_item", "world": "minecraft:overworld", "to": [10.5, 64.0, -2.5], "item": "minecraft:diamond"}

container_add

fn container_add(world: &World, at: BlockPos, item: &str, count: i32) -> i32

Puts up to count of item into the block container at a position -- topping up its stacks first, then empty slots -- and answers how many went in. Nought for no container there. What a rollback of items taken out needs.

Wasm request

Shape: Routed together with container_remove; count is required.

Shape and limits, as the router words its errors: "count is required".

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

{"call": "container_add", "world": "minecraft:overworld", "at": [10, 64, -3], "item": "minecraft:diamond", "count": 1}

container_remove

fn container_remove(world: &World, at: BlockPos, item: &str, count: i32) -> i32

Takes up to count of item out of the block container at a position, answering how many came out: what a rollback of items put in needs.

Wasm request

Shape: Routed together with container_add; count is required.

Shape and limits, as the router words its errors: "count is required".

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

{"call": "container_remove", "world": "minecraft:overworld", "at": [10, 64, -3], "item": "minecraft:diamond", "count": 1}

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