Skip to Content

Jobs

A module is a continuous controller: Kill Aura, a bounce loop, Offhand. A job is finite work towards a goal: open a chest and take what’s needed, build a wall, fill a shulker box, fly a route. You describe the work as a step, start it, and the runner ticks it, cancels it when your module turns off, and can say at any moment what it’s doing and why it’s waiting.

Step<Integer> restock = Steps.openContainer(chest, 20, Placement.Options.forServer()) .then(view -> Steps.take(view, ItemInfo::isFood, Containers.Transfer.upTo(32))) .then(moved -> Steps.closeContainer().then(Step.supply("Count", () -> moved))) .named("Restock food") .timeout(20 * 30) .retry(2); Myriad.jobs().start(this, restock).result() .thenAccept(moved -> info("Took " + moved)) .exceptionally(t -> { warn("Couldn't restock: " + Why.of(t)); return null; });

The pieces

Step<T>a description of work producing a T: a value like Placement.Options, reusable and printable (toString() is the tree). Nothing happens until it’s started
Job<T>a step running for an owner: state(), why(), status(), progress(), children(), pause()/resume()/cancel(), result()
Progress<T>what a step reports each tick: running(), stuck(why), done(value), failed(why)
Whya reason: a Code everyone can match (Why.NO_ITEM, or your own Why.Code.of("my-addon:no_schematic")), a detail for people, and what it’s about (a position, an item)
Myriad.jobs()start(owner, step), running(), of(owner), cancel(owner), later(owner, ticks, action), every(owner, ticks, action)

Stuck is not failed. A build waiting for cobblestone is stuck: it keeps being ticked, carries on by itself when cobblestone arrives, and a remedy can fetch some. Failed means it can’t finish from here (the server refused the block, the container is gone).

Composing

a.then(b), a.then(result -> step)one after another, passing the result on
Step.sequence(name, a, b, c)in order; steps that finish at once hand over in the same tick
Step.all(name, list)at once; done when every one is, the first failure cancels the rest
Step.race(name, list)at once; the first to finish wins, the rest are cancelled
Step.forEach(name, () -> items, item -> step)one step per item, the items read when it starts
Step.when(condition, step), Step.choose(name, () -> step)decided when reached, not when built
step.repeat(n), step.repeatWhile(condition)again
Step.run, supply, delay, until, await(future), fail, nothingthe small leaves

Policies wrap a step and everything under it, and show as pills on its job:

named(name), named(() -> live)what the Jobs window shows
timeout(ticks)running or stuck too long: fails with TIMEOUT (paused ticks don’t count)
stuckFor(ticks)stuck too long: fails with the stuck reason
whenStuck(code, ticks, why -> remedy)stuck on code for ticks: the step pauses, the remedy runs (as its child), then the step carries on. If the remedy fails, so does the step
recover(why -> alternative), retry(n)on failure; never on a cancellation (the player, a lost race, the owner turning off, leaving the world). A retry starts the next tick, in the same job
require(condition, why)checked when reached
suspending(moduleIds...)holds those modules off while it runs (suspension)
finallyDo(action), onDone(value -> ...), onFailed(why -> ...), peek(value -> ...)callbacks
Step<Void> wall = Steps.build(wallBlueprint, Building.Options.forServer()) .whenStuck(Why.NO_ITEM, 20, why -> fetchFrom(supplyChest)) // fetch more, then carry on building .stuckFor(20 * 60); // but not forever

The services as steps

Every one passes the job as the owner to the service, so cancelling the job cancels what it asked for, and two jobs of one module don’t cancel each other’s.

StepProducesStuck onFails on
Steps.place(pos, slot, options), place(hit, slot, options)OUT_OF_REACH, NOT_VISIBLE, NO_SUPPORT, ENTITY_IN_WAY, BLOCKED, RATE_LIMITEDSERVER_REFUSED, UNSUPPORTED
Steps.placeState(pos, state, slot, options) (solved click, one more where it takes several, then its setting)as place, and WRONG_ANGLEas place
Steps.use(hit, slot, options)as placeas place
Steps.breakBlock(pos, priority, options)OUT_OF_REACH, UNBREAKABLESERVER_REFUSED
Steps.lookAt(target, options), face(yaw, pitch, options)
Steps.selectSlot(slot)
Steps.ensureInHotbar(item, preferred)the slotNO_ITEM, NO_SLOT
Steps.borrow(inventoryIndex)the slot (given back when the enclosing step ends)NO_ITEM
Steps.openContainer(pos, ticks, options)the ViewOUT_OF_REACHTIMEOUT, NO_CONTAINER
Steps.take(view, what, how), put(view, what, how)how many movedNO_ROOMNO_CONTAINER
Steps.arrange(view, arrangement)whether it all went inNO_CONTAINER
Steps.closeContainer(), untilClosed(view, ticks)TIMEOUT
Steps.inItem(inventoryIndex, view -> step)the step’s result, once the box is backNO_ITEM, NO_ROOM, SERVER_REFUSED, TIMEOUT
Steps.build(blueprint, options), keepUp(...)the commonest reason in reach (“no item: ×12 cobblestone”)
Steps.suspend(moduleIds...)
Steps.walkTo(pos), walkNear(pos, radius) (Baritone)NO_PATHING (no Baritone), BLOCKED (Baritone found no way)
Steps.fly(flight, f -> keepFlying) (done once it’s landed)the flight’s reason: NO_ELYTRA, UNLOADED, SERVER_REFUSEDwhy it had to come down
Steps.acquire(what, count, sources)how many you holdNO_ITEM (“×12 short”) once every source was tried

fly starts the flight and asks keepFlying once a tick, which steers it (heading, speed, height) and says whether to go on; once it says no, the flight lands. acquire tries a list of MaterialSources in turn until you hold enough: MaterialSource.container(pos) (a chest, opened, taken from, closed), MaterialSource.shulkerBoxes() (the boxes you carry), or your own, a lambda returning a step that fetches up to a count and says how many it got:

MaterialSource stash = (what, count) -> Steps.walkNear(stashPos, 3).then(MaterialSource.container(stashPos).fetch(what, count)); Step<Integer> obsidian = Steps.acquire(s -> s.is(Items.OBSIDIAN), 64, List.of(MaterialSource.shulkerBoxes(), stash));

Writing a step

When nothing above fits, write a Step.Run. One is made for each start and polled once a tick, at the start of the tick before the services act, so what it asks for goes out that tick.

final class FlyLeg implements Step.Run<Void> { @Override public Progress<Void> tick(JobContext ctx) { if (!chunkLoaded()) return Progress.stuck(Why.of(Why.UNLOADED, "the next chunk")); if (arrived()) return Progress.done(); steerTowardsCorner(); ctx.progress(flown(), legLength()); return Progress.running(); } @Override public void cancel(JobContext ctx) { land(); // let go of what you hold } @Override public String status() { return "leg " + leg + " of " + legs; } } Step<Void> leg = Step.of("Flying the leg", FlyLeg::new);
  • Pass ctx.job() as the owner to every service.
  • Never subscribe to the bus yourself: ctx.on(PacketEvent.Receive.class, e -> ...) hears events for the life of the step and delivers them on its tick (on the render thread, whatever thread fired them; read them, you can’t cancel).
  • ctx.budget() says how long you may still work this tick; stop when it’s spent and carry on next tick.
  • pause/resume mean stop asking the services for things and start again; cancel means let go.
  • A throw fails the step: throw Why.of(code, detail).asException() fails it with that reason.

Jobs and modules

Modules start jobs: a Printer is a module around one job, a search a module around a job tree. Turning the module off cancels its jobs (their reason is OWNER_OFF); leaving the world cancels every job (LEFT_WORLD). A root job that fails with nobody listening to its result() (and no onFailed or recover) shows a notice with your module’s name and the reason; one stuck for five seconds shows one too, once (not for OUT_OF_REACH, which the player puts right by moving). The player sees your jobs in the Jobs window and HUD element and can pause or cancel them there or with .job; name your steps for them (named(...)) and give long ones a status(). JobEvent.Started, Changed and Finished go on the bus, for UIs and for other addons that react to your work.

A build started by Steps.build or Steps.keepUp belongs to the step’s job: to draw its plan, find it among Myriad.building().running() by its owner(), a job under yours.

private @Nullable Build myBuild() { for (Build b : Myriad.building().running()) { if (b.owner() instanceof Job<?> j && root(j) == job) return b; // root: follow parent() up } return null; }