Developer docs

Cookbook: skilling

A plugin that gathers (trees, rocks, fishing spots, stalls) or processes (fletching, cooking, smithing), then drops or banks when the inventory is full. Read PrivBot plugin concepts first.

Node layout

TaskPriorityBands has no skilling band. Keep the survival and travel bands, and give the skilling nodes your own distinct values below them, declared in one place with a comment.

Node Priority shouldExecute (read-only) execute calls
DeathRecoveryNode (dangerous areas only) RECOVERY_MIN (240) Polled HP is 0, or recovery active recovery.step(ctx)
TravelNode MOVEMENT (150) Not at the work area or the bank the plan needs navigation.step(ctx)
EatFoodNode / HealNode (if the activity hurts) HAZARD_SECONDARY_HIGH (95) HP below threshold supplies.heal(ctx)
BankNode (bank mode) PREP_HIGH (35) Inventory observed full, at the bank banking.step(ctx) (see Cookbook: banking loop)
DropNode (drop mode) PREP_LOW (30) Inventory observed full inventoryPolicy.dropStep(ctx)
ProcessNode your value, e.g. 28 Materials carried, product wanted processing.makeStep(ctx)
GatherNode your value, e.g. 26 Inventory observed not full, a target in range gathering.gatherStep(ctx)

A stall-thieving plugin, for example, might use 80 (heal), 60 (open coin pouch) and 40 (steal). A plugin that trains several skills can group its skill nodes under a privbot.task.Parent so the children compete only with each other.

Services to write

Service Owns
gathering The target (object or NPC by action and name), the interact, the start proof, the "done" wait
processing Opening the make interface and confirming materials turned into product
inventoryPolicy What counts as full, what to keep, drop or bank
banking One bank operation per execute (Cookbook: banking loop)
navigation A NavigationSession between the work area and the bank

Recipe: one gather step with proof

public boolean gatherStep(MyTaskContext ctx) {
    long epoch = ctx.runState.sessionEpoch;
    ItemContainerSnapshot before = ctx.inventory.snapshot();
    if (!before.available) {
        status = "Inventory unreadable";
        return false;
    }
    String product = ctx.config.productName();
    int held = before.count(product);

    PrivObject spot = ctx.read(() -> ctx.objects.query()
            .withAction(ctx.config.action())
            .withName(ctx.config.objectName())
            .withinTiles(ctx.config.maxDistance())
            .nearest());
    if (spot == null) {
        status = "No " + ctx.config.objectName() + " nearby";
        return false;
    }
    if (!spot.interact(ctx.config.action())) {
        return recordFailure(ctx.config.action() + " " + spot.getName() + " was not accepted");
    }
    // Start proof: the player began working.
    if (!ctx.sleepUntil(() -> ctx.shouldAbort(epoch) || ctx.user.isAnimating(), 2_500)) {
        return recordFailure(spot.getName() + " did not start");
    }
    // Done: gained product, went idle, or something more urgent needs the worker.
    ctx.sleepUntil(() -> ctx.shouldAbort(epoch)
            || gained(ctx, product, held)
            || ctx.user.isIdle()
            || ctx.supplies.needsHeal(ctx), 20_000);
    failedAttempts = 0;
    return true;
}

private static boolean gained(MyTaskContext ctx, String product, int held) {
    ItemContainerSnapshot now = ctx.inventory.snapshot();
    return now.available && now.count(product) > held;
}

The wait exits on needsHeal: while execute waits, no other node can run, so a long wait must also end on whatever another node would need to do.

Recipe: full inventory, drop mode

/** Selection: full only when the inventory was actually read. */
public boolean observedFull(MyTaskContext ctx) {
    ItemContainerSnapshot carried = ctx.inventory.snapshot();
    return carried.available && carried.freeSlots(28) == 0;
}

public boolean dropStep(MyTaskContext ctx) {
    long epoch = ctx.runState.sessionEpoch;
    String product = ctx.config.productName();
    ItemContainerSnapshot before = ctx.inventory.snapshot();
    if (!before.available || before.count(product) == 0) {
        return false;
    }
    int held = before.count(product);
    ctx.inventory.dropAll(product);                    // void: no acceptance signal at all
    boolean dropped = ctx.sleepUntil(() -> {
        ItemContainerSnapshot now = ctx.inventory.snapshot();
        return ctx.shouldAbort(epoch) || (now.available && now.count(product) < held);
    }, 6_000);
    status = dropped ? "Dropped " + product : "Drop of " + product + " did not land";
    return dropped;
}

Do not use ctx.inventory.isFull() as the gate: it reads false when the inventory cannot be read, and isEmpty() reads true. Use the snapshot. To keep tools, use ctx.inventory.dropAllExcept("Bronze axe") and confirm the same way.

Recipe: process with a make-X interface

public boolean makeStep(MyTaskContext ctx) {
    long epoch = ctx.runState.sessionEpoch;
    ItemContainerSnapshot before = ctx.inventory.snapshot();
    if (!before.available) {
        return false;
    }
    int materials = before.count("Logs");
    if (!ctx.production.isCreationMenuOpen()) {
        if (!ctx.inventory.useOn("Knife", "Logs")) {
            return recordFailure("Knife on Logs was not accepted");
        }
        if (!ctx.sleepUntil(() -> ctx.shouldAbort(epoch) || ctx.production.isCreationMenuOpen(), 3_000)) {
            return recordFailure("Make menu did not open");
        }
    }
    // Blocking: selects the product, then waits for the work to settle. Worker only.
    if (!ctx.production.make("Arrow shaft").all().run()) {
        return recordFailure("Arrow shaft not offered in the make menu");
    }
    ItemContainerSnapshot after = ctx.inventory.snapshot();
    boolean used = after.available && after.count("Logs") < materials;   // proof: materials consumed
    status = used ? "Fletching" : "Make did not consume Logs";
    return used;
}

Production.Make also has times(n) and openWith(itemId, objectName) (use an item on an object to open the menu). run() returns true once the make action was dispatched; confirm the materials moved.

Recipe: rate and XP

ctx.user.getExperience(Skill) reads total XP, but it answers 0 when it cannot read. Use it only as a difference between two readable values:

int before = ctx.user.getExperience(Skill.WOODCUTTING);
// ... later ...
int now = ctx.user.getExperience(Skill.WOODCUTTING);
if (before > 0 && now >= before) {
    ctx.runState.xpGained += now - before;
}

ctx.skills.xp(Skill) is the tri-state alternative: an Observed<Integer> that says when the read is unavailable, so you do not need the > 0 guard.

Pitfalls for skilling plugins

  • A long wait blocks every other node. Bound it, and exit on the conditions other nodes need (heal, full inventory, a threat).
  • Resources deplete. The tree or rock found in selection may be gone at use. Re-acquire in execute, and treat "did not start" as a counted failure with back-off, not a reason to spin.
  • withName and withAction match substrings, case-insensitively. "Oak" matches "Oak tree" and also "Cloak rack". Narrow with .where(o -> "Oak tree".equalsIgnoreCase(o.getName())) when it matters.
  • Full and empty must be observed, not inferred from a failed read (rule 3).
  • Animation is not proof of the product. An animation can start and be interrupted. Prove the gather with the inventory count, and use idle only to end the wait.
  • Make interfaces differ by server. Make.run() returns false when the product row is not found. Count it, stop with a reason after the limit, and keep the product name in config.

The banking half of the loop: Cookbook: banking loop.

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