Developer docs

PrivBot plugin cookbook

One page per plugin type. Each page gives the node layout with real TaskPriorityBands values, the services to write, short recipes against the API, and the pitfalls that hit that type.

Read PrivBot plugin concepts first (the layers, threads and ctx.* facades) and keep Threading and pitfalls open while you write.

Page For
Cookbook: combat and slayer Fighting NPCs: targets, food, prayer, loot, tasks
Cookbook: skilling Gathering and processing: object loops, full inventory, make-X
Cookbook: banking loop Travel to a bank, deposit, withdraw, return
Cookbook: boss mechanics Encounters with telegraphed attacks, hazards and phases
Cookbook: PvP Fighting players: opponent reads, gear switches, prayers
Cookbook: overlays and UI Sidebar, settings studio, HUD and scene overlays

Shared shape

Every page uses the same layers:

MyPlugin -> MyRunState -> MyTaskContext (extends PrivTaskContext) -> MyTaskTree -> TaskNodeRunner -> nodes
                                  |
                                  +-- services/<capability>/  (dispatch + bounded proof + retry limit)
  • A node is one decision: a read-only shouldExecute, one service call in execute, status(...).
  • A service dispatches once, waits for proof with ctx.sleepUntil(() -> ctx.shouldAbort(epoch) || proof, ms), counts failures, and exposes status() and reset().
  • Priorities come from privbot.task.TaskPriorityBands where a band fits. Higher wins; give top-level nodes distinct values.

Testing

Unit-test services and nodes with the privbot-api-testkit; see Testing plugins. Report compile, unit tests and in-game behaviour separately: one does not imply another.

Server-aware facades

Capabilities (ctx.capabilities, ctx.server()), id translation (ctx.ids), privbot.api.Outcome, tri-state Observed<T> reads and the teleport / loadout / restock / recovery services are described in Server-aware facades. Check ctx.capabilities before you rely on a verb that not every server has.