Developer docs

Cookbook: banking loop

Travel to a bank, open it, deposit, withdraw a supply list, close, and go back to work. Used on its own (a skilling bank loop) or as the restock half of a combat plugin. Read PrivBot plugin concepts first.

Instead of writing the bank steps, describe the gear once and let ctx.restock.to bring the player to it. The same calls are written for Impact, Elorin, Orion, SpawnPK and Roat Pkz. They are not yet verified live on every server: ctx.capabilities reads unknown or partial for LOADOUT and RESTOCK until the bench sweep has run, so check it and read the job's reason() rather than assuming success.

  1. Capture what the player has right now, while they stand in the gear you want:

    Observed<GearSetup> worn = ctx.loadouts.captureWorn();        // by slot; ammunition at any count
    Observed<GearSetup> supplies = ctx.loadouts.captureCarried(); // one entry per item id, with a role (FOOD, RESTORE, ...)
    if (!worn.isPresent() || !supplies.isPresent()) { /* unreadable: do not save; say why and try again */ }
    
  2. Save and load by name, per account (letters, digits, _, -; folded to lower case). These touch the disk: call them on the worker, not in a selection predicate.

    ctx.loadouts.save("zulrah-worn", worn.get());              // true only if it was read back equal
    ctx.loadouts.save("zulrah-carried", supplies.get());
    Observed<GearSetup> wanted = ctx.loadouts.load("zulrah-worn");   // present, absent (no such name) or unreadable
    
  3. Restock with a job. Stand at, or next to, a bank first: the job does not travel (use ctx.travel.go or a RecoveryPlan for that).

    RestockTarget target = RestockTarget.builder()
            .worn(wornSetup)               // a WORN GearSetup
            .carried(carriedSetup)         // a CARRIED GearSetup
            .depositFirst(true)            // bank unwanted items first; also clears extras before a preset
            .preset("1")                   // optional, see below
            .build();
    
    private Job restock;                   // plugin state, worker thread only
    
    // in the restock node's execute, once per tick:
    if (restock == null) restock = ctx.restock.to(target);
    JobState state = restock.step(ctx);
    if (state == JobState.DONE) { restock = null; /* proved: both setups satisfied */ }
    else if (state != JobState.RUNNING) { status = restock.reason(); restock = null; }
    

    RestockTarget.isEmpty() is true when neither setup has entries; such a target fails at once with "empty target: nothing to restock to" instead of reporting success.

What the job does, in order. One action per step, then at most 2.4 s waiting for its proof.

  1. If the target names a preset (and the server has a preset button), use it first. With depositFirst and unwanted items carried, those are banked first (open, deposit, close), because a preset can replace the inventory. A preset is never proof: whatever it did not bring is still withdrawn.
  2. Missing worn pieces (and worn ammunition below its captured quantity): open the bank (always sent, whatever the bank reads), deposit unwanted items, withdraw each piece by item id.
  3. Close the bank and put the worn pieces on, one per step.
  4. Reopen, deposit unwanted items (swapped-out gear included), withdraw each carried shortfall by item id.
  5. Close the bank. A target that is already met never opens it.

What it proves. DONE ("restocked") only after readable equipment and inventory satisfy both setups and, with depositFirst, nothing unwanted is carried. Each withdrawal is proved by that item's carried count rising, each deposit by free slots rising, each worn piece by its slot holding it. The failure reasons are in plain words and tell the two common causes apart:

reason() Meaning
bank has none: <name> Two sent withdrawals brought nothing and no positive bank count was read for it: most likely the bank is out. Restock your supplies before retrying.
could not withdraw: <name> (bank shows <n>) The bank shows the item but the withdrawal did not arrive. Not an out-of-stock.
inventory full: no room for <name> The inventory has no slot for it. Not an out-of-stock.
could not withdraw: <name>, the inventory did not deposit, <name> did not go on The click was not sent, threw, or went out and the proof never appeared.
bank did not open No bank in reach.
could not click <name> Five clicks in a row threw.
restock did not settle in 500 steps The step budget ran out before both setups were satisfied.
setup cannot all be worn at once (e.g. two-handed + shield) The captured setup is contradictory.

An unreadable bank, inventory or equipment keeps the job RUNNING with the reason "<what> unreadable" and is never counted as "missing" or "closed"; five in a row end it FAILED.

Presets exist only on some servers. Impact has loadout presets in slots 1 to 6 (.preset("1") to .preset("6")); Elorin has the bank's "last preset" button, which ignores the slot you name. ctx.restock does not drive a preset on Orion, SpawnPK or Roat Pkz yet (those servers have their own preset/kit features); the preset is ignored and the withdraw path runs. To put on worn gear without banking, ctx.loadouts.equip(wornSetup) is a job too (DONE only when each slot holds its item; FAILED with not carried: <name> for a missing piece; after 20 equip clicks FAILED "setup cannot all be worn at once (e.g. two-handed + shield)"). Close the bank before you start it: on Elorin and SpawnPK an open bank covers the inventory, so the wear clicks miss.

Use SetupDiff.worn(setup, ctx.equipment.snapshot()) and SetupDiff.carried(setup, ctx.inventory.snapshot()) when you only need to know what is missing, extra or short before deciding to bank (missing(), shortfall(), extras(), satisfied()).

Legacy: write the bank steps yourself

Everything below is the older hand-written flow. It still works and is the right choice when you need a custom order of operations; for a plain "bank to this gear" prefer the job above.

Node layout

Node Priority shouldExecute (read-only) execute calls
DeathRecoveryNode (dangerous areas) RECOVERY_MIN (240) Polled HP is 0, or recovery active recovery.step(ctx)
TravelNode MOVEMENT (150) The plan needs a place the player is not at (bank or work area) navigation.step(ctx)
EatFoodNode (if you can be hit) HAZARD_SECONDARY_HIGH (95) HP below threshold, food carried supplies.eat(ctx)
BankNode PREP_HIGH (35) Bank trip needed (observed full, or supplies short) and at the bank banking.step(ctx)
Work node(s) below PREP_LOW (30) Supplies carried, inventory observed not full the work service

One BankNode does one bank operation per execute and proves it. The service keeps the step. Survival nodes get a turn between operations, and a failed step is retried on its own instead of replaying the whole trip.

Services to write

Service Owns
banking The step (open, deposit, withdraw each item, close), the proof of each, the failure count, the epoch that opened the bank
navigation One NavigationSession to the bank and one back; cancel on Stop, death, disconnect
supplies The wanted list and what "short" means, read from snapshots

Recipe: one operation per execute

public final class BankingService {
    enum Step { OPEN, DEPOSIT, WITHDRAW, CLOSE, DONE }

    private static final int MAX_FAILURES = 3;
    private volatile Step step = Step.OPEN;
    private volatile long openedEpoch = -1;
    private volatile int failures;
    private volatile String status = "";

    /** Worker. One bounded operation; the next tick continues. */
    public boolean step(MyTaskContext ctx) {
        switch (step) {
            case OPEN:     return openStep(ctx);
            case DEPOSIT:  return depositStep(ctx);
            case WITHDRAW: return withdrawStep(ctx);
            case CLOSE:    return closeStep(ctx);
            default:       return false;
        }
    }

    /** Disconnect, death, Stop: the next trip starts by opening again. */
    public void reset() {
        step = Step.OPEN;
        openedEpoch = -1;
        failures = 0;
        status = "";
    }

    private boolean fail(String reason) {
        status = ++failures >= MAX_FAILURES ? reason + " (stopping bank trip)" : reason;
        if (failures >= MAX_FAILURES) step = Step.DONE;   // a node above can pause the plugin with this status
        return false;
    }

    public String status() { return status; }
}

Recipe: open without trusting isOpen()

private boolean openStep(MyTaskContext ctx) {
    long epoch = ctx.runState.sessionEpoch;
    // Open once per session, unconditionally. Never skip because isOpen() says true.
    if (openedEpoch != epoch) {
        if (!ctx.bank.open()) {
            return fail("No bank booth, chest or banker in reach");
        }
        ctx.sleepUntil(() -> ctx.shouldAbort(epoch) || ctx.bank.isOpen(), 5_000);
        if (ctx.shouldAbort(epoch)) {
            return true;
        }
        openedEpoch = epoch;
    }
    step = Step.DEPOSIT;     // isOpen() was a hint; the first count that moves is the proof
    return true;
}

If the deposit or withdraw that follows moves nothing, count a failure and go back to Step.OPEN with openedEpoch = -1: the bank was not really open.

Recipe: deposit and withdraw with count proof

private boolean depositStep(MyTaskContext ctx) {
    long epoch = ctx.runState.sessionEpoch;
    ItemContainerSnapshot before = ctx.inventory.snapshot();
    if (!before.available) {
        return fail("Inventory unreadable");
    }
    if (before.size() == 0) {
        step = Step.WITHDRAW;
        return true;
    }
    if (!ctx.bank.depositInventory()) {
        return fail("Deposit inventory was not accepted");
    }
    boolean moved = ctx.sleepUntil(() -> {
        ItemContainerSnapshot now = ctx.inventory.snapshot();
        return ctx.shouldAbort(epoch) || (now.available && now.size() < before.size());
    }, 3_000);
    if (!moved) {
        openedEpoch = -1;
        step = Step.OPEN;
        return fail("Deposit did not move anything");
    }
    step = Step.WITHDRAW;
    return true;
}

private boolean withdrawStep(MyTaskContext ctx) {
    long epoch = ctx.runState.sessionEpoch;
    ItemContainerSnapshot before = ctx.inventory.snapshot();
    if (!before.available) {
        return fail("Inventory unreadable");
    }
    Supply next = ctx.supplies.nextShort(before);           // your plan: name + amount still missing
    if (next == null) {
        step = Step.CLOSE;
        return true;
    }
    if (before.freeSlots(28) == 0 && before.count(next.name) == 0) {
        return fail("No free slot for " + next.name);
    }
    int held = before.count(next.name);
    if (!ctx.bank.withdraw(next.name, next.amount)) {
        return fail("Withdraw " + next.name + " was not accepted");
    }
    boolean landed = ctx.sleepUntil(() -> {
        ItemContainerSnapshot now = ctx.inventory.snapshot();
        return ctx.shouldAbort(epoch) || (now.available && now.count(next.name) > held);
    }, 3_000);
    if (!landed) {
        // Out of stock, a wrong name, or the bank was not open. Do not guess which.
        return fail("Withdraw " + next.name + " did not land");
    }
    failures = 0;
    return true;                                             // next tick: the next short item
}

private boolean closeStep(MyTaskContext ctx) {
    long epoch = ctx.runState.sessionEpoch;
    ctx.bank.close();                                        // never gated on isOpen()
    ctx.sleepUntil(() -> ctx.shouldAbort(epoch) || !ctx.bank.isOpen(), 1_200);
    step = Step.DONE;                                        // the next equip/eat proves the bank is gone
    return true;
}

Supply is your own value class (name, amount). ctx.bank.withdrawAll(name) takes the whole stack; ctx.bank.depositAll(name) deposits one item kind; ctx.bank.depositEquipment() empties the worn slots.

Recipe: hold one journey to the bank

private NavigationSession journey;      // touched only on the worker

public boolean travelStep(MyTaskContext ctx) {
    long epoch = ctx.runState.sessionEpoch;
    if (journey == null) {
        Places.Place bank = ctx.places.bank();               // nearest bank configured for this server
        if (bank == null) {
            return fail("No bank configured for this server");
        }
        NavigationOptions options = new NavigationOptions();
        options.arriveRadius = bank.radius;
        journey = ctx.travel.session(bank.anchor, options, NavigationSession.Policy.defaults());
    }
    NavigationSession.Result r = journey.step(() -> ctx.shouldAbort(epoch));
    status = journey.status();
    if (r == NavigationSession.Result.PENDING) {
        return true;
    }
    journey = null;                                          // terminal results are sticky: drop it
    return r == NavigationSession.Result.ARRIVED || fail("Could not reach the bank: " + r);
}
// On Stop, death and disconnect: NavigationSession j = journey; if (j != null) j.cancel(); journey = null;

ctx.travel.toBank() is the one-call version: it blocks the worker until arrival (or a 2-minute timeout) and returns true on arrival. It is fine for a short, quiet trip; hold a session when eating or escaping must be able to interrupt.

Pitfalls for banking plugins

  • ctx.bank.isOpen() can read true after the bank closed on some servers. Never skip open() because of it (lint W002) and never treat it as proof. Proof is a count that moved.
  • Bank content reads answer 0 or false when they cannot read. ctx.bank.count(name) and ctx.bank.has(name) cannot tell "none in the bank" from "unreadable", and on some servers bank contents stay readable after the interface closed. Decide "out of stock" only after a withdraw that did not land, repeated up to your limit.
  • Read the inventory with ctx.inventory.snapshot() after a withdraw, and check available.
  • Close before you equip or eat. Wield and eat from a bank screen behave differently per server.
  • Stackables need one slot only when already carried. Use freeSlots(28) and the current count.
  • Names. ItemContainerSnapshot.count(String) is an exact, case-insensitive name. Supply lists with (4) doses or charges must match the in-game name.
  • Bank verbs are partial on several servers as of 2026-11-04. Treat a [PrivBot API] unsupported log as "not here" and stop with a reason. ctx.capabilities.supports(Capability.BANK_WITHDRAW) tells you before you start; the per-server table is What works on each server.
  • ctx.restock.to and ctx.loadouts work on every server and are the first choice; the older ctx.restock.run is deprecated (Impact and Elorin only, unproved). Check ctx.capabilities for RESTOCK and LOADOUT per server.

The example node and service in your starter project show the same one-operation-per-execute shape at teaching size.

Unit-test this with the testkit, see Testing plugins.