Build your own plugins.
Already have a project? Open your developer workspace.
One API, every supported server.
Write against ctx facades and the task framework once. Each server's mapping does the rest, and the capability matrix says what is supported where.
Built, scanned and signed by PrivBot.
You upload source, never binaries. The build service compiles against the published API, runs lint, a policy scan and your tests, then signs the result.
Private by default.
Your plugins live in your own namespace and install only on your license. Nobody else sees them in their catalog.
From idea to your client.
The front page of the SDK guide: what is in the starter project, where to read next, and how to upload.
Build your own PrivBot plugins against the same API the catalog plugins use: a task tree of small nodes, the
ctx.* facades for reading the game and acting in it, and a shared UI kit. Plugins are Java 11 RuneLite
plugins built with Maven.
Every API on these pages exists in the PrivBot client today. The API reference (Javadoc) covers each method: https://privbot.dev/javadoc/.
Start here
| Page | What it covers |
|---|---|
| Getting started: from a download to a running plugin | From nothing to a running plugin: the starter project, a first node, a test, the jar, developer mode and upload. |
| PrivBot plugin concepts | The authoring model: Plugin, RunState, TaskContext, TaskTree, TaskNodeRunner, nodes, services; every ctx.* facade; the threading model. |
| Threading and pitfalls | The rules that keep plugins working: confirm actions, poll for death, unreadable is not "no", client-thread reads, stopped plugins cost nothing, reconnects. |
| Testing plugins with privbot-api-testkit | privbot-api-testkit: unit-test nodes and services against a scripted fake game. |
| Working with an AI coding agent | Build with an AI coding agent (Claude Code, Cursor, any MCP client): the project's agent files, the read-only tools, setup, privacy, troubleshooting. |
| Uploading your plugin | java -jar sdk/tools/privbot-cli.jar upload: what is uploaded, signing in, the flags, exit codes and how to read a build error. |
| PrivBot plugin cookbook | One page per plugin type: combat and slayer, skilling, banking loop, boss mechanics, PvP, overlays and UI. |
| PrivBot plugin API: versioning and compatibility | API versions and compatibility rules. |
| What works on each server | Which API capabilities work on which server. |
| The API index (api-index.json) | api-index.json: the API as data, for search and AI tools. |
Your starter project holds a working plugin to build on (an example node with its test, the sidebar, the settings studio and a HUD overlay), the unit-test kit and the tools these pages mention. Download it from https://privbot.dev/account/developer#starter-project.
The API reference for the author packages (privbot.context, privbot.hooks, privbot.task, privbot.query,
privbot.wrappers, privbot.ui*) lists every method; the API index is the same content as JSON.
The model in one picture
MyPlugin (RuneLite Plugin: DI, Start/Stop, UI, events; never reads the client)
|
+-- MyEventDispatcher event policy: stopped-plugin tick gate, disconnect, reconnect
+-- MyRunState volatile session state, sessionEpoch
+-- MyTaskTree owns the TaskNodeRunner (worker thread, selection, reconnect grace)
|
+-- nodes shouldExecute: read only execute: one bounded service call
|
+-- services dispatch through ctx.*, then confirm the change, bounded retries
Three rules cover most bugs:
truefrom an action means the click was accepted. Confirm the change.- A read you cannot make is "cannot tell", never "no".
- Game-tick handlers signal; the worker does the work. A stopped plugin reads nothing.
What works on each server.
Counts of SDK capabilities by support level, from the verified capability matrix. Anything not yet verified is unknown, not unsupported.
| Server | Supported | Partial | Unsupported | Unknown |
|---|---|---|---|---|
| Impact | 15 | 20 | 3 | 5 |
| Elorin | 23 | 11 | 1 | 8 |
| Orion | 21 | 4 | 1 | 16 |
| SpawnPK | 14 | 16 | 3 | 10 |
| Roat Pkz | 26 | 3 | 0 | 16 |
| Ragnar | 32 | 0 | 0 | 14 |
Generated 2026-11-10T05:44:13.658330600Z.
What a plugin may use.
Every build is scanned at the bytecode level. The build report lists each finding with its class and member; it is the authority on what passed.
This is the community (STRICT) profile: a plugin listed for everyone must pass it with no finding. Private plugins (your own uploads, installed only on your license) are scanned with the same rules but get warnings only, except license, Unsafe and class-loader use, which stay errors.
Allowed
- The PrivBot API packages: privbot.actions.confirm, privbot.api, privbot.behavior, privbot.config, privbot.context, privbot.effects, privbot.hooks, privbot.hooks.bank, privbot.hooks.container, privbot.hooks.shop, privbot.mechanics, privbot.movement.pathing, privbot.query, privbot.restock, privbot.sdk, privbot.task, privbot.ui, privbot.ui.fx, privbot.ui.overlay, privbot.wrappers; act in game through ctx.*
- java.util, java.time, java.text, java.math and most of java.lang
- Swing, JavaFX and java.awt for your own panels and overlays (their core, event, layout, geometry and image packages, plus Swing tables and trees: javax.swing.table and javax.swing.tree), using images bundled in your jar
- In-memory streams, readers and writers from java.io (buffered, data and print wrappers over them), and InputStreamReader/OutputStreamWriter with a charset from java.nio.charset, to read bundled text such as a resource in your jar
- RuneLite API, events, input, callback, UI and overlay packages, plus the plugin and config base types
- Reading and writing your own config group (name it after your plugin id)
- Guice, javax.inject, SLF4J and Lombok
Flagged by the scan
- Networking of any kind (java.net, sockets, OkHttp, WebView). Community plugins cannot contain web addresses either; code that needs the network belongs in a private plugin
- Loading remote content in the UI: web views, images or HTML that fetch from an address
- Driving or reading the desktop: Robot (AWT and JavaFX), the clipboard, Desktop, drag and drop, key bindings, global key and mouse listeners, screen capture
- Reaching the client's windows from your own components (parents, root panes, scenes, focus), the game canvas, and the client's callbacks
- Window enumeration and the global paint and window-stacking hooks, so a plugin cannot reach or cover the client's own windows
- Raw-client control: of the client only plain reads (get/is/has/can), and not the login details; no menu actions, menu entries, scripts, packets, world hops or event posting. Use ctx.* instead; a community plugin can trade only when your license holds a trade permit for it
- Other plugins' config groups, and the client's profile and config machinery
- System properties, environment variables and JVM-wide settings (including UIManager)
- Files (including java.io file streams and PrintWriter/PrintStream on a file name), processes, System.exit and native libraries
- Classes that reuse a client, library or Java class name, or sit in a reserved package (java.*, javax.*, javafx.*, net.runelite.*, privbot.* and the client's libraries): put your classes in your own package
- Reflection, method handles, class loaders, Unsafe, Guice injectors, java.beans, Synth and FXML, and serialization tricks
- License and credential classes, and PrivBot internals outside the public API
