Automation agents

Automation agents do the chores at your base. Ask in chat, like “sort my chests by category” or “smelt all my raw gold evenly”, and Allay hands the job to an agent that works in the background while you keep playing.

#How an agent works

You ask. The chat starts an agent and names it.
It talks to you under its name. It asks with buttons (“go ahead?”), and a click answers back at once.
It waits for free. Furnaces and brewing stands take time; an agent sleeps until they're done, and sleeping costs nothing.
It ends with a report. Labels over chests show what went where.

An agent stays near you: it pauses while you're more than 64 blocks from where it started. Each player runs up to 2 agents at once, each for at most 30 minutes.

#Helper agents

A step of another kind goes to a helper agent. A brewing agent short of glass bottles hands the glass to a furnaces agent, hears exactly what it made and where, and brews on. An agent can't finish while a helper it started still runs: it waits for the report.

#What agents may touch

Only your own things, in containers you could open yourself (see Integrations).
Blocks within 32 blocks (automation.radius, at most 52).
Furnaces, brewing stands, and crafting tables in plain sight: a wall of opaque blocks hides one; glass, leaves, and slabs don't.
Never the inside of a shulker box item. A placed shulker box is a chest like any other.
A chest someone has open stays out. A chest a hopper feeds, like a sorter's input, only takes things in.

If you or anyone else takes what an agent counts on, it stops and says so.

#Chests

Pick the chests first:

Left-click each chest you want, or press [All nearby] to take every chest around (gaps of up to 6 blocks between them, up to 64 chests).
Press [Done].

Then say what to do:

Sort each chest, or group everything by category across them.
Move what you name into a chest, from other chests, your inventory, or every chest around: “put all my wood into this chest”, “take 32 coal there”.
Stash: “put my loot away” puts your inventory into the chests that already hold each item, or that a sign or an item frame names. Your hotbar stays.
Take: “get me 64 iron”, “6 lapis and 8 coal”, or “top my torches up to a stack” takes it out of the chests around.

The agent reads the signs and item frames on chests, and asks when a sign doesn't say enough. Names work as in an inventory layout: “all the iron” means raw iron, ingots, nuggets, and blocks, and “except the enchanted” leaves those alone. Copper chests, barrels, and placed shulker boxes count too.

Every change is planned, checked, and written in one tick, or nothing moves. [Put back] undoes the last five changes, one by one, for 5 minutes, as long as nobody touched those chests since.

#Furnaces

“Smelt all my raw gold evenly.”

Smelting spreads evenly over free furnaces, blast furnaces, and smokers, each by what it can cook.
Each gets exactly the fuel it needs. Coal blocks split into coal. Without coal it burns your planks, sticks, or bamboo, and logs or a bucket of lava when you ask.
Ask by what you want out: “smelt iron” smelts raw iron first, then the ores.
Tell it where the output goes, and full furnaces empty themselves there. You get the experience, as if you took it out yourself (on Paper; on Spigot it stays in the furnace).
“Add 20 more ore” joins a running job. Say “always into my inventory” once, and it remembers.

#Brewing

“Brew three night vision potions.”

Brewing starts where a stand already is (an awkward potion saves a step) and from the potions you carry, so “make my night vision longer” upgrades yours.
It fills stands three bottles at a time, brews several potions at once, and runs more than the stands hold in rounds.
It takes only what's needed and turns a blaze rod into powder.
It fills your glass bottles at water or a cauldron nearby, once nothing else is missing. A cauldron loses a level per bottle, as in the game.
Potions go by any name: “speed”, “healing II”, “splash healing”, “extended night vision”.
When a stand doesn't fit, the agent says why: still brewing, a reagent left in its top slot, or finished potions to collect.

Taking the bottles out of a stand mid-brew stops the agent.

#Crafting

“Craft me a set of diamond tools.”

2×2 recipes need nothing; 3×3 ones need a real crafting table nearby. A stonecutter in sight cuts what it can there.
A smithing table turns diamond gear into netherite in place, keeping its enchantments, name, and wear.
Ingredients come from your inventory, bundles, the ender chest, and the chests around, never from inside shulker boxes. Only server recipes with plain ingredients count; nothing comes from nowhere.
What's left over goes back.

#The anvil

The crafting agent puts enchanted books and items of the same kind onto an item in the cheapest order, and renames it. It finds the books in your inventory, bundles, the ender chest, and chests near. It shows the result and the levels first and works only after your yes. You pay the levels, nothing costing 40 or more in survival is done, and the anvil wears down as in the game.

#Who may use them

Everyone, by default. Each kind needs allay.automation and its own permission: allay.automation.chests, .furnaces, .brewing, or .crafting. Take them away from regular players with your permission plugin to keep automation for, say, VIPs. automation.* in Configuration switches kinds off and sets the limits.

Next: Commands and permissions