Repository navigation
Plugin protocol client tools
Part of the Plugin protocol. The backend asks for these tools with a tool_call event, and the plugin posts each result back as Tool results describes.
2.4 merged and reshaped tools, and the backend serves only the 2.4 set: plugins before 2.4 lose the tools whose names changed. Since backend 5.5 the model sees some of these as one tool (get_surroundings with get_light_spawn_check and scan_farm from 6.16 to 6.20, when plugin 6.21 dropped both, inventory for get_inventory, get_item_durability, get_food_options, and get_brewing_items, locate for both locate tools, get_recipes with get_brewing_recipe, get_locations with get_death_info, get_player_status with get_xp_info, allay_settings with set_timezone, and since 6.17 operator for the seven operator tools, by action), but the backend still calls the plugin by the names below, so nothing changes for a plugin. Every spot comes as absolute x, y, z with distance (horizontal, in blocks) and direction (north, north-east…); dimensions are overworld, the_nether, the_end, and tools accept Bukkit's old normal and nether too.
Since plugin 6.21 results add, all optional: look_at with kind: nothing gives block_range, entity_range, and block_beyond_reach, and entities stop at walls; scan_nearby_containers and find_item give locked_containers and unloaded_chunks, a container more_kinds and more_kinds_inside; get_food_options and get_brewing_items give inside_boxes_and_bundles, brewing more_stands; find_villagers gives more_villagers and each villager more_trades; get_anvil_plan gives capped_to and not_considered; goals set returns done when already met, and a reach goal x, z, radius, dimension, and counts_from_arrival_in; show_marks gives nearest {x, y, z, distance, direction, above, turn}; locate_structure takes common names, and its not-found result gives searched and dimension; get_world from another dimension gives overworld {time, phase, weather}; get_advancements lists 15 todo, counts hidden ones once done, and takes detail; get_recipes lists crafting_transmute and crafting_special recipes and, for fireworks, fireworks; give_item takes potion and firework, teleport an optional y and returns surface, safe, and danger; set_gamemode returns blocked, heal cleared_effects, apply_effect kept_stronger, set_time and set_weather world, frozen, and overridden. The automation craft takes count up to 2304 and firework, and answers in_ender_chest; chests take answers skipped_chests and, per amount, then. A tool that answered no (nothing crafted, nothing found) still answers ok: true; the plugin shows its line as a refusal.
| Name | Args | Returns |
|---|---|---|
get_player_status |
– | gamemode, health, max_health, food, saturation, level, level_progress, x, y, z, dimension, biome, light, facing, flying, effects [{type, level, seconds}], held_item |
get_inventory |
{ "include_enderchest"?: bool } |
main [item], armor {head, chest, legs, feet}, offhand, and inside_containers {id: count} with what the shulker boxes and bundles in main and offhand hold; with include_enderchest, enderchest [item] and enderchest_inside_containers. Items as in Items below |
get_surroundings |
{ "radius"?: 1–16 } default 8 |
radius, blocks {id: count} (top 12), notable [{id, x, y, z, distance, direction}] (ores, chests, spawners, portals; 15 nearest; since plugin 6.21 ores, spawners, vaults, and budding amethyst only in the player's sight, and containers only ones they could open, in the counts too), entities [{type, count, nearest, hostile?}] within 32 blocks, other_players (a count only) |
look_at |
{ "detail"?: bool } |
What's under the crosshair. kind: "nothing"; or kind: "block" (within 6): id, state?, x, y, z, distance, hardness, blast_resistance, preferred_tool?, needs_tier?, held_tool_is_right, break_seconds?, drops_with_held_item [item], age/max_age?, waterlogged?, block_light, sky_light, plus container {name?, slots, used_slots, items {id: count}, more_kinds?, inside_shulker_boxes?, inside_bundles?} — or with detail, stacks [item with slot] up to 54 and more_stacks — and enchanting {bookshelves, counted_max, top_offer_min_level, top_offer_max_level, player_level, lapis_in_inventory}; or kind: "entity" (within 16): type, name?, distance, item? (dropped items, item frames), for living ones health, max_health, armor, attack_damage?, hostile, your_hit {weapon, damage_per_hit, hits_to_kill?, estimate}, for traders profession, level?, trades [trade]. Another player is only {kind, type: "player", distance}. Since plugin 5.5, a container the asker couldn't open comes with locked (why) instead of container
|
get_world |
– | dimension, time, phase, day, moon, weather, difficulty, rules {…}, border |
get_statistics |
– | play_time_hours, deaths, mob_kills, player_kills, walked_km, flown_km, jumps, fish_caught, minutes_since_death, minutes_since_rest |
get_advancements |
{ "filter"?: "todo" | "done" | "all" } default todo |
done_count, todo_count, and up to 40 per list: todo and/or done [{key, title, description, started?}]; key is what goals takes for an advancement |
get_recipes |
{ "item": "beacon" } |
item, name?, source?, recipes [{type, shape?, key?, ingredients?, input?, seconds?, experience?, template?, base?, addition?, makes?}] up to 5, more_recipes. Crafting, cooking, stonecutting, and smithing only. Since plugin 6.12 item may be a name in any language the game has («зелье заражения»), and the server's own things count: a mod's item (mymod:wrench), a plugin's or data pack's item built on a game item, by its model's id (redbull:original), and an expansion's; name is its name in the asker's language and source where it comes from when that isn't the game. A potion, or an item a brewing stand makes, answers potions are brewed: call get_brewing_recipe with <id>; an unknown name answers no item called X on this server; close: Name (id), …. Since plugin 6.13 items (1–5 names) asks for several at once: results [{query, …the same fields, or error}] in the order asked, up to 3 recipes each when there are several; the backend sends item beside it for older plugins, which answer only that one, and then asks for the rest one by one. Since plugin 6.19 plan: true (with count, 1–64, default 1) adds plan to each item: what crafting that many would take from the asker's inventory, bundles, ender chest (when one is near), and the chests near them they may open, planned as craft plans it, four levels deep, smelts included: takes {id: n}, makes {id: n}, steps ["N × id", "N × id smelted from x", …], smelt? {id: n} (what goes into a furnace first), table?, stonecutter?, smithing_table?, upgrades?, and needs? [crafting_table | smithing_table | furnace | water] for what isn't near; or missing {id: n} for what's short with missing_for? {id: part} (what a part on the way was for: diamond: diamond_chestplate for netherite); or error when it can't be crafted (a mined item). Items in one call share the player's things in the order asked, so a set counts each ingot once. Nothing is taken or reserved. Older plugins ignore both and answer without plan. Since plugin 6.27 counts [n] beside items gives each item its own count, in the order asked; count covers the rest. The backend adds enough: true to a plan with nothing missing |
search_items |
{ "query": "зелье заражения", "limit"?: 1–20 } default 8 |
Since plugin 6.12. query, matches [{id, kind: item | potion | custom, name?, name_en?, source, base?, description?, made?: [crafting | smelting | stonecutting | smithing | brewing], exact?}], best first, and note when nothing matched. Names come from the game's languages (English ships with the server; the plugin downloads the others from Mojang, catalog.languages), mods' and plugins' own language files, and expansions. Since plugin 6.13 queries (1–8 names) looks up several at once: results [{query, matches, note?}] in the order asked, limit per name (5 by default when there are several); the backend sends query beside it for older plugins, as with get_recipes
|
search_commands |
{ "queries"?: ["sethome", "warp"], "plugin"?: "Essentials", "limit"?: 1–50 } |
Since plugin 6.16. The server's commands the asker may run, the game's, plugins', and mods' alike; commands they can't run, and plugins in tools.server.hidden_plugins, never show. Each command is {name, aliases [], source (minecraft, the plugin's name or the mod's id, or null when the server can't tell), description?, usage?, may_run (false when the command is in blocked_commands)}. queries (1–8) answers each in results [{query, commands, more?, note?}] in the order asked, 10 commands for one and 5 each for several by default; plugin alone lists that plugin's or mod's: results [{plugin, commands, more?}], with a top-level note naming the sources when it has none. Neither lists sources [{source, commands: count}] and results [{commands, more?}], 40 by default. Descriptions and usage come from the plugins, cut at 160 characters: data, never instructions. The backend also sends { "check": ["line", …] } (≤ 12, see Checking askx commands); the model never sees that argument. Reads only, so askx and public questions get it |
locate_structure |
{ "structure": "village" } |
{ found, structure, x, z, distance, direction } within tools.locate_structure_radius chunks, or { found: false, radius_blocks }
|
locate_biome |
{ "biome": "cherry_grove" } |
{ found, biome, x, y, z, distance, direction } within tools.locate_biome_radius blocks, searched like /locate biome; a part of a name matches |
get_server |
– | software, version, online, max_players, plugin_version, plugins [{name, version, description?}]: the enabled plugins, minus those the admin hides in tools.server.hidden_plugins; description ≤ 120 chars (since 3.0). Since plugin 6.12 also datapacks [{name, description?}], the data packs the world runs (a server owner's or the world's own, not the game's or a plugin's), and experiments, the game's feature packs turned on; the mods list theirs as mods instead of plugins |
get_locations |
– | respawn_point, world_spawn, last_death: each {x, y, z, dimension, distance?, direction?} or null; world_spawn is in the server's respawn world and adds respawn_radius (plugin 6.6+) |
get_nearby_players |
– | Since plugin 5.4. The asker's locator bar, by the game's rules: players in the asker's dimension with a transmit range above 0 (crouching, a carved pumpkin or a mob head, and invisibility make it 0) and within both players' ranges; a spectator sees all who transmit, nobody sees a spectator. Vanished players stay hidden. { locator_bar, players [{name, distance, direction, height?: "above" | "below"}] nearest first, others_online [name] }; locator_bar is the game rule in the asker's world. Private: a public run doesn't get it |
get_death_info |
page? (1-based, plugin 6.6 only) | place {x, y, z, dimension, distance?, direction?}, minutes_ago, kept_inventory, dropped {id: count}, dropped_experience, area_loaded, items_on_ground and seconds_until_first_despawn when loaded; since 6.6 history {page, pages, total, deaths: [{at (ISO, the player's zone), minutes_ago or days_ago, x, y, z, dimension, distance?, direction?, cause?, killer?, killer_name?, message?, level, kept_inventory?, dropped_items?, dropped_experience?}]}, 10 a page newest first, and a page past the end is an error naming the count. Plugin 6.6 kept deaths on disk; since plugin 6.7 and server 6.9 the plugin reports each death (POST /api/v2/users/{id}/deaths), returns only the live facts here, and the backend adds history itself from what it keeps, preferring it over a 6.6 plugin's own |
find_villagers |
{ "item"?: "enchanted_book", "profession"?: "librarian", "radius"?: 4–64 } |
radius, villagers (up to 10, nearest first) [{profession, level?, x, y, z, distance, direction, trades [trade] (up to 10; with item, only those trades)}] |
scan_nearby_containers |
{ "radius"?: 1–52 } default 32 (1–24, default 16, in plugin 5.14.1; 1–12, default 8, before it; older plugins clamp) |
radius, containers (20 nearest) [{type, x, y, z, distance, direction, name?, used_slots, top {id: count}, inside_containers?}], more_containers. Since plugin 5.5, only containers the asker could open: outside a GriefPrevention claim or with container trust in it, and never an unopened structure chest. Since plugin 5.7 a double chest counts once, the containers found glow for the asker with a label (highlighted), and a way button goes under the answer when the nearest is far or out of sight |
find_item |
{ "item": "diamond", "radius"?: 1–52 } default 32 (1–24, default 16, in plugin 5.14.1; 1–12, default 8, before it; older plugins clamp) |
query, matched_ids (when item isn't an exact id and matched as part of ids), total, radius, places (up to 30) [{where: inventory | offhand | armor | enderchest, slot, count, inside?} or {where: container, type, x, y, z, distance, direction, name?, count, inside_boxes?}], more_places. Counts shulker boxes and bundles one level deep. Since plugin 5.5, only containers the asker could open: outside a GriefPrevention claim or with container trust in it, and never an unopened structure chest. Since plugin 5.7 a double chest counts once, the containers found glow for the asker with a label (highlighted), and a way button goes under the answer when the nearest is far or out of sight |
inspect_item |
{ "from"?: "hand" | "offhand" | "head" | "chest" | "legs" | "feet" | "inventory" | "enderchest" | "container", "slot"?: 0–53, "inner_slot"?: 0–63 } |
One item in full: from, slot, with inner_slot also inside and inner_slot, then everything an item has (below), plus lore (≤ 10 lines), unbreakable, attributes [{attribute, amount, operation, slot}], tooltip {attack_damage, attack_speed}, effects [{type, level, seconds | instant}], dye_color, repair_cost, book {title?, author?, generation?, pages}, firework {flight?, explosions [{shape, colors, fade_colors?, trail?, twinkle?}]}, map {scale_level, blocks_per_side, center_x, center_z, dimension, locked, player_inside}, contents [item with slot] up to 27 and more_stacks. slot is required for inventory (0–35), enderchest (0–26), and container (the one under the crosshair, 6 blocks); inner_slot reads that slot inside the shulker box or bundle found there |
get_item_durability |
– | items [{from, slot?, id, damage, max_damage, percent_left, unbreaking?, expected_uses?, mending?, almost_broken?}] for armor, offhand, and every inventory slot (0–8 the hotbar) |
get_xp_info |
{ "target_level"?: 0–100 } |
level, progress, total_points, points_to_next_level, target_level?, points_to_target? |
get_food_options |
– | food, saturation, food_missing, foods [{id, count, nutrition, saturation, note?}] |
get_anvil_plan |
{ "item"?: "diamond_sword", "slot"?: 0–40, "enchantments"?: { "sharpness": 5, "mending": 1 }, "slots"?: [0–40] } |
Since plugin 6.12 for any item the player has, wherever it lies: slot names it (0–35 the inventory, 36–39 boots to helmet, 40 the offhand), item by id, part of one (sword), or name in any language (hand is the hand, or the tool's own pick when the hand is empty); with neither the tool picks the item in hand when the books improve it, else the only item they improve, else answers { found: false, reason, choose: [{slot, where, item, gain}] } for the model to ask. Results carry the item's target (where) and slot. Before 6.12, for the item in hand only. With enchantments: ideal books, as item, item_repair_cost, steps [{left, right, levels}] where pieces are item or <enchantment> <level>, total_levels, too_expensive. Without (plugin 5.3+): what the player has, the enchanted books and enchanted items of the same kind in the inventory (or only slots), priced as the game does: found, item, pieces [{piece: hand | hotbar N | inventory row R column C, slot?, kind, enchantments, repair_cost}], steps [{left, right, levels, gives}], result, total_levels, too_expensive, unused?; { found: false, reason } when nothing improves the item |
inspect_redstone |
{ "radius"?: 1–10, "around"?: "look" | "player" } default 6, look |
Since plugin 5.6. Every redstone part within the radius (80 nearest the center): { id, x, y, z, … } with dust power and connects, repeaters input_from, outputs, delay_ticks, powered, locked?, comparators mode, observers watches, pistons pushes, extended, sticky, and received for mechanisms; issues [{ id, x, y, z, issue, detail }] with dust_dot, torch_burned_out, piston_jammed, hopper_locked, repeater_locked, dust_runs_past. Only blocks where the asker may build (outside claims, or with build trust in GriefPrevention); refused when the center is in someone else's claim |
get_brewing_recipe |
{ "potion": "night_vision", "form"?: "potion" | "splash_potion" | "lingering_potion" } |
Since plugin 5.3, read from the game's brewing recipes (26.3 keeps them as data): potion, form, steps [{bottle, add, makes}] from a water bottle, fuel. Drink first, then gunpowder and dragon's breath turn the bottle. Since plugin 6.12 the server's brews count too (mods' and data packs' recipes, Paper plugins' potion mixes made of items, expansions' brews), potion may be a name in any language (infestation and «зелье заражения» find infested), and a plugin's own bottle reads as its id alone (redbull:crude_taurine) |
get_brewing_items |
– | inventory [item] for brewing, brewing_stands (up to 4 within 8 blocks) [{x, y, z, distance, direction, fuel_level, seconds_left?, ingredient?, fuel?, bottles}] |
point_to |
{ "x", "z", "y"?, "dimension"?, "label"?, "seconds"?: 1–3600, "style"?, "bar_color"? } or { "player", "seconds"?, "style"?, "bar_color"? }
|
Points the compass and draws a trail only the player sees. Since plugin 5.3: seconds up to tools.point_to.max_seconds (600 by default; older plugins allow 30 and refuse more), 30 by default (6.22.1: about a second for every two blocks; since plugin 6.23.0, without seconds the trail lasts while the player gets closer, ends idle_seconds after they stop, and runs max_seconds at most, which seconds in the result then says); the trail ends when the player arrives, and a new one replaces the old. style is sparkle (default), flame, soul, glow, magic, spark, cherry, notes, hearts, snow, totem, or happy; older plugins ignore it. A dimension other than the player's is refused. Since plugin 6.23.0, a boss bar (tools.point_to.bar, boss_bar by default) shows the arrow, the blocks left, and the height and shrinks on the way; bar_color is pink, blue, red, green, yellow, purple, or white (tools.point_to.bar_color by default; older plugins ignore it), and the compass points there in every dimension, so compass is always true. Returns { distance, direction, seconds?, idle_seconds?, style?, compass, action_bar?, boss_bar? } (idle_seconds and boss_bar since plugin 6.23.0); since plugin 6.21, action_bar says whether an arrow toward the spot and the blocks left show above the hotbar (tools.point_to.action_bar). Since plugin 5.4, player instead of x and z: a trail that follows that player while they're on the asker's locator bar (as get_nearby_players says), goes dark while they hide, and ends when the asker reaches them, when they leave, or after 15 s off the bar; seconds defaults to tools.point_to.follow_seconds (180). A player off the bar is refused. Returns { player, distance, direction, seconds, style, follows, compass, action_bar?, boss_bar? }
|
show_marks |
{ "marks"?: [{ "x", "y", "z", "block"?, "label"?: "≤ 48", "color"? }] (≤ 64), "seconds"?, "clear"?: true } |
Since plugin 5.5. Display entities only the asker sees, glowing through walls: a stained-glass box hugging the block there, or with block, a smaller ghost of that block on a free spot, each with an optional text label. color is yellow (boxes by default), green, red, blue, aqua (ghosts by default), purple, orange, or white. Refused per mark: farther than tools.show_marks.radius (48), ores, spawners, and vaults, containers the asker couldn't open (a GriefPrevention claim without container trust, or an unopened structure chest), a ghost on an occupied block. A new call replaces the set; they go after seconds (tools.show_marks.default_seconds 120, at most max_seconds 600), on /allay cancel, or when the player leaves; a ghost goes out once the player places a block on it. Returns { shown, seconds, refused?: [{x, y, z, reason}] }, or { cleared }
|
show_draft |
{ "action"?: "show" | "add" | "layer" | "move" | "rotate" | "check" | "clear", "title"?, "palette"?: [{ "char", "block": "id[states]", "label"? }], "layers"?: [[row]], "offset"?: { "right"?, "up"?, "forward"? }, "x"?, "y"?, "z"?, "y_offset"?, "layer"?: 1–15 | "next" | "prev" | "all", "turns"?: 1–3 } |
Since plugin 5.6. A build up to 20 × 15 × 20 (width × height × depth) as ghosts only the asker sees, one layer at a time; the plugin checks the layer every 10 ticks, puts a red box with what belongs there on a wrong block, moves on when a layer is done, and counts in a boss bar. Written facing north: right east, forward north; layers bottom up, rows far to near, characters left to right; . or a space leaves a cell alone, air must stay empty. Only the states a palette entry spells out are checked (dust's are never). Labels show for entries used at most 6 times. show starts two blocks ahead, centered, at the feet plus y_offset, or at the corner x, y, z, and replaces the old draft; add merges cells at a non-negative offset; move shifts by offset; rotate turns clockwise around the middle; check returns { title, done, total, layers [{layer, done, total}], wrong [{layer, x, y, z, wanted, found}] (20) }. Refused in a claim where the asker may not build, farther than 32 blocks, or over the size. One draft per player, in memory: /allay cancel, leaving, or a restart drops it. Returns { title, size, blocks, layer, corner, facing }
|
ping_me |
– | Note particles and a sound over the player that everyone nearby sees and hears; { pinged, y }
|
sort_inventory |
{ "undo"?: bool (5.11+), "hotbar"?: bool, "offhand"?: bool, "pins"?: [{ "slot": 1–9 | "inventory:1"–"inventory:27" (5.8+) | "offhand", "item": "sword" | "golden_apple" | "potion:healing" }] } (since plugin 5.7) |
Merges stacks and sorts slots 9–35 by id, plus the hotbar and offhand when asked; pins put the best matching item (an id or a group) in a slot first. Since plugin 5.7.1 a sorted hotbar holds the pins (or, without pins, its hand items) and takes other items only when the main inventory is full; layout (5.8+): { order?, zones?: [{ items, where: row:N | row:last | column:N | column:last | slots:A-B | start | end }], by?: name | category | count, rows?, keep?, merge_only? }, items as ids, groups, materials, categories, enchanted, named, damaged. { merged_stacks, pinned?, not_found?, hotbar, offhand, rows }; undo puts back the last sort or chest change and returns { restored, chests_restored? }, hotbar as 9 ids or null (5.7.1+), rows as the main inventory's 3 rows of 9 (5.8+) |
reminders |
{ "action"?: "add" | "list" | "cancel", "minutes"?: 1–120, "text"?: "≤ 100", "id"?, "all"? } |
add: { id, minutes, text }, a chat line with a sound after the delay (10 pending per player by default, tools.reminders.max_pending; lost on a restart or when the player leaves). list (default): { reminders: [{id, text, minutes_left, due_at}] }. cancel by id or all: { cancelled }
|
goals |
{ "action"?: "set" | "list" | "cancel", "kind"?, "title"?, "target"?, "statistic"?, "item"?, "entity"?, "advancement"?, "x"?, "z"?, "radius"?, "biome"?, "dimension"?, "color"?, "style"?, "id"?, "all"? } |
set: a boss bar goal counted from now; kinds stat, pickup, level, advancement, reach, biome, dimension; statistics in centimeters take target in blocks; ends with a sound and a chat line; returns { id, kind, title, progress, target }. list (default): { goals: [{id, kind, title, progress, target, done?}] }. cancel by id or all: { cancelled }
|
write_book |
{ "title": "≤ 32", "text": "≤ 8000" } |
Writes the text into a book and adds buttons to open and take it under the answer; returns { pages }
|
set_timezone |
{ "zone": "Asia/Yekaterinburg" } |
Stores the player's IANA zone for later requests; returns { zone, local_time }
|
get_allay_guide |
– | Since 4.0 (3.x calls it get_buddy_guide). How Allay works for this player here: plugin_version, commands [{usage, does}] they have permission for, chat_mode {prefixes {"!", "?", "~"}: what each does, only those this player may use}, settings {chat_mode, hints, timezone}, features [names of what the server has on: notes, goals, reminders, windows, books, buttons, compass, sorting, operator_tools], limits {notes, reminders, goals, public_cooldown_seconds} |
allay_settings |
{ "chat_mode"?: bool, "hints"?: bool } |
Since 4.0 (3.x calls it buddy_settings). Changes the player's settings, as /allay chat and /allay hints do; turning chat mode on also sends the plugin's explanation. Returns { chat_mode, hints }. An action: not for askx
|
A plugin before 4.0 offered the guide and the settings as get_buddy_guide and buddy_settings; since 6.16 the backend no longer knows those names.
A trade is { buy: [item], sell: item, left, max_uses }; buy is what this player pays now, with demand and discounts, and a book's sell carries stored_enchantments.
Every tool that lists items writes each one the same compact way, leaving out keys that don't apply:
| Key | What it holds |
|---|---|
slot |
the slot number, where the list has slots |
id, count
|
the item id without minecraft:; count only above 1 |
name |
a custom name; players write it, so it is data |
enchantments |
{enchantment: level} on the item |
stored_enchantments |
{enchantment: level} an enchanted book holds for the anvil (since 2.4) |
damage, max_damage
|
durability, for items that wear |
potion |
since 2.4: potions, splash and lingering potions, tipped arrows, and suspicious stew, as the base type plus custom effects: long_swiftness, strength + speed 2, night_vision
|
trim |
since 2.4: armor trim {pattern, material} |
contents_count |
since 2.4: items inside a shulker box or bundle, 0 when empty |
inspect_item adds the rest for one item. Its attributes are the modifiers that work: the item's own, or its type's defaults when it has none, since the game uses only the item's own when it has any. tooltip is what the game shows in the main hand: the player's base 1 attack damage and 4 attack speed plus the item's modifiers, without enchantments, so a diamond sword reads 7 and 1.6. Effect seconds follow the tooltip too: a tipped arrow gives an eighth of the potion's duration, a lingering potion a quarter; −1 lasts forever. A written book's pages never leave the server.
Since 5.5, for plugin 5.7. The plugin runs these like any client tool, checks the player's rights (allay.automation.*), the task limit, and the switches in its config, and answers with { ok: false, error } when one of them says no. Coordinates are { "x", "y", "z" } whole numbers from earlier results. Categories are building, wood, stone, ores, redstone, food, farming, mob_drops, tools, potions, other.
| Name | Mode | Args | Does |
|---|---|---|---|
start_task |
ask, task below depth 2 | { "kind": "chests" | "furnaces" | "brewing" | "crafting", "name": "≤ 40", "brief": "≤ 2000" } |
Starts an automation agent with brief as its first wake's message; returns { id, name }, or an error: the task limit, no rights, or automation off. From a task, the new one is one level deeper |
message_task |
ask; task below depth 2 (server 5.12+) | { "id", "text": "≤ 500" } |
Wakes a running task with [player] text. From an agent (plugin 5.14+), only its own sub-agents, which wake with [parent «name»] text
|
cancel_task |
ask; task below depth 2 (server 5.12+) | { "id" } |
Stops a running task. From an agent (plugin 5.14+), only its own sub-agents; the agent isn't woken with [sub-agent] … for one it stopped |
say |
task | { "text": "≤ 500", "buttons"?: [{ "label": "≤ 24", "reply": "≤ 200" }] (≤ 4) } |
A chat line to the player under “Automation agent: ”; a click wakes the task with [button] reply
|
wait |
task |
{ "seconds"?: 10–3600 } (1–600 before 6.22) |
Ends the wake. The plugin clamps seconds to at least 10 and at most automation.max_wait_seconds (600 by default, up to 3600). Since plugin 6.22 a wait without seconds while nothing else can wake the agent (no job, no sub-agent, no line or question to the player) counts as a silent wake: the agent is told once, then stopped. The plugin wakes the task with [player] … on an answer, [button] … on a click, [job] … when its job ends (smelting or brewing done, a picking mode closed), [sub-agent] … when a sub-agent it started ends (since 5.10.1), [parent «name»] … from the agent that started it (plugin 5.14+), or [timer] … after seconds
|
finish |
task | { "summary": "≤ 500", "handoff"?: bool (server 5.12+) } |
Ends the task; the player sees summary. Since plugin 5.14, refused while a sub-agent of the task runs, unless handoff is true: the agent would never hear the report it needs. With handoff, the sub-agents carry on and report to the player themselves |
pick_blocks |
task | { "kind": "chests" | "furnaces" | "brewing_stands", "looking"?: bool } |
A picking mode with [Done] [All] [Cancel]; its end wakes the task with [job] …. looking takes the block under the crosshair at once and returns it |
chests |
task | { "action": "read" | "plan" | "apply" | "undo", "mode"?: "sort" | "group" | "move" | "take" (5.11+) | "stash" (5.11+), "layout"?: as in sort_inventory (5.8+, sort and group), "chests"?: [xyz] (≤ 64), "assign"?: [{ x, y, z, "category"?, "items"?: [id] (≤ 27) }] (≤ 64), "items"?: [selector] (ids before 5.11), "categories"?: [category], "count"?: 1–2304 (5.11+), "amounts"?: [{ "item": selector, "count"? | "up_to"? (take) }] (≤ 16, 5.11.1+), "up_to"?: 1–2304 (5.11+, take), "keep"?: [selector] (5.11+), "hotbar"?: bool (5.11+, stash), "to"?: [xyz] (≤ 64), "from"?: ["inventory" | "nearby"] (5.10.2+) } |
Reads chests (contents, signs, item frames, problems, only_adding for a sorter's input), plans a sort, a grouping, a move, a take into the inventory, or a stash of the inventory as a preview, applies it, or undoes the last apply (the last five since 5.11). Copper chests and placed shulker boxes count as chests since 5.11 |
smelt |
task | { "action": "scan" | "start" | "add" (5.11+) | "fuel" (5.10+) | "status" | "collect", "item"?, "count"?: 1–4096, "items"?: [{ "item", "count"? }] (≤ 8), "furnaces"?: [xyz] (≤ 16), "fuel"?, "each"?, "up_to"?, "need"?, "types"?, "to"?: "inventory" | "auto" (5.11+) | [xyz] (1–8), "remember"?: bool (5.11+) } |
Furnaces, blast furnaces, and smokers near the player; several items split by each furnace's speed. Since 5.11 to on start empties full furnaces and the rest at the end, collect pays the furnace's experience, add adds more of what the job cooks, and planks, sticks, bamboo, and lava burn |
brew |
task | { "action": "scan" | "start" | "status" | "collect", "potion"?, "form"?: "potion" | "splash_potion" | "lingering_potion", "bottles"?: 1–64, "potions"?: [{ "potion", "form"?, "bottles"? }] (1–4, 5.11+), "fresh"?: bool, "stands"?: [xyz] (≤ 8), "to"?: "inventory" | "auto" (5.11+) | [xyz] (1–8), "remember"?: bool (5.11+) } |
Brewing stands near the player. Since 5.11 several potions at once, rounds on the same stands past three bottles a stand, water bottles filled from glass bottles at water or a cauldron, and to on start delivers by itself |
craft |
task | { "item", "count"?: 1–64, "dry_run"?: bool } |
Crafts at a crafting table near the player. Since plugin 6.19 a plan that smelts first crafts only what the furnaces need (raw iron from its block) and answers { crafted: false, smelt: {id: n}, crafted_for_the_furnace?: ["N × id"], note }; a furnaces agent smelts, then craft runs again. Missing answers carry missing_for as get_recipes' plan does, and netherite gear crafts the diamond piece from diamonds when the player has none |
grindstone |
task | { "action"?: "plan" | "apply", "item"?: "hand" | id, "combine"?: bool } |
Since plugin 6.19. A grindstone near the player in plain sight, as the game's: takes every enchantment but curses off the item (a book with none left turns plain) and drops their experience at it, or with combine joins a second piece of the same item from the player's things (both durabilities plus 5% of the maximum, enchantments but curses gone from both). plan answers item, grindstone {x, y, z}, takes_off {id: level}, curses_stay?, with? {item, from, durability, enchantments_lost?}, durability? {before, after, max}, experience (“23–45”), levels 0; apply adds done and the experience dropped. No levels, no wear |
The plugin defines what each of them returns; the model reads whatever comes back.
Listed only for operators and only when the admin enables them (tools.operator in the plugin config). The plugin checks isOp() again when it runs one. They act on the asking player only.
| Name | Args | Does |
|---|---|---|
give_item |
{ "item": "diamond_sword", "count"?: 1–576, "enchantments"?: { "sharpness": 5 } } |
Puts the item into the player's inventory, dropping what doesn't fit at their feet |
teleport |
{ "x", "y", "z", "dimension"? } or { "player": "name" }
|
Teleports the player |
set_gamemode |
{ "mode": "survival" | "creative" | "adventure" | "spectator" } |
Changes the player's game mode |
heal |
– | Full health, food, and saturation; puts out fire |
apply_effect |
{ "effect": "night_vision", "seconds"?: 1–3600, "level"?: 1–10 } or { "clear": true }
|
Gives the player an effect, or clears all of them |
set_time |
{ "time": "day" | "noon" | "night" | "midnight" | 0–23999 } |
Sets the time in the player's world |
set_weather |
{ "weather": "clear" | "rain" | "thunder", "seconds"?: 1–86400 } |
Sets the weather in the player's world |