This page follows the path of a plugin author: download a starter project, open it in any IDE, build it, load it into your running PrivBot client, let an AI coding agent help, and upload it. Plan on 15 minutes. Everything you need is in the project you download; you do not need a checkout of anything.
1. Get the starter project
On the developer page, https://privbot.dev/account/developer#starter-project:
- Sign in with your PrivBot account.
- Name the plugin and pick the servers it supports:
Impact,Elorin,Orion,SpawnPKorRoat Pkz. - Download the starter project and unzip it. Open the folder in IntelliJ IDEA, VS Code, Eclipse or any IDE that reads a Maven project.
Your plugin id is already filled in. It has the form u-<ownerTag>-<slug>: your owner tag, then the slug of the
name you gave it. The client loads only ids in your own namespace from your machine, so leave the prefix alone.
The project holds your plugin, its test, the build, the SDK and the files your AI agent reads:
chicken-killer/
├── pom.xml parent privbot-plugin-parent; writes the jar manifest
├── mvnw, mvnw.cmd, .mvn/ the Maven wrapper
├── README.md
├── AGENTS.md, CLAUDE.md rules for AI coding agents
├── .mcp.json, .cursor/ the agent's PrivBot tools and Cursor rules
├── .vscode/, .run/ IDE build tasks (VS Code, IntelliJ)
├── sdk/ the PrivBot API, test kit and parent POM
│ sdk/repository/ the API jars and javadoc your IDE reads
│ sdk/docs/ these pages
│ sdk/tools/ the command-line tool (privbot-cli.jar)
└── src/
├── main/java/com/example/chickens/
│ ├── MyPlugin.java entry point: DI, Start/Stop, sidebar, settings, HUD, event forwarding
│ ├── MyConfig.java settings (@ConfigGroup is your plugin id)
│ ├── events/MyEventDispatcher.java game events: stopped-plugin tick gate, disconnect, reconnect
│ ├── state/MyRunState.java session state and the session epoch
│ ├── tasks/MyTaskContext.java ctx.* facades + config + state + services
│ ├── tasks/MyTaskTree.java owns the TaskNodeRunner; register nodes here
│ ├── tasks/survival/EatFoodNode.java
│ ├── services/SupplyService.java
│ ├── ui/MyPanel.java sidebar from the UI kit
│ └── ui/MyOverlays.java in-game HUD from the UI kit
└── test/java/com/example/chickens/tasks/EatFoodNodeTest.java
Your package is the one you chose, not com.example.chickens. Read concepts.md for what each layer
does and why.
2. Build and test it
You need a JDK 11 or newer, and nothing else: the Maven wrapper and the SDK are inside the project. Your IDE
completes ctx.* and shows its javadoc from sdk/repository.
./mvnw test # Windows: .\mvnw.cmd test
./mvnw package # Windows: .\mvnw.cmd package
mvnw test runs the example node's test against the fake game (see testing.md), so it passes before
you have written anything. The first run of the wrapper downloads Maven 3.9.9 once, so that run needs internet
access. Offline, install Maven 3.9 or newer and run mvn instead.
If the build says runelite-parent:pom:1.11.12 (present, but unavailable), your Maven cache already holds RuneLite's
own copy of version 1.11.12 (from building RuneLite plugins), and Maven reads it instead of the one in sdk/. Delete
the 1.11.12 folders under ~/.m2/repository/net/runelite/runelite-api and ~/.m2/repository/net/runelite/client,
then build again: the jars come back from sdk/repository.
mvnw package writes target/<slug>-0.1.0.jar. The parent POM sets the manifest entries the client checks:
| Entry | From |
|---|---|
Plugin-Id |
your plugin id, u-<ownerTag>-<slug> |
Plugin-Class |
the entry point in your package (MyPlugin) |
Plugin-Version |
the project version (semver) |
Plugin-Provider |
privbot.plugin.provider in pom.xml: change Your Name |
Plugin-Api-Version |
the PrivBot API version in sdk/ |
Plugin-Servers |
the servers you picked |
The client refuses a plugin whose API version it cannot run, or that does not list the current server. Orion needs
its own build: mvnw package -Porion.
3. Add your first node
The project already wires the plugin class, the task tree, the settings, the run state, the example node and its
test, the sidebar, the settings studio and an overlay. You add nodes. The samples below use the package
com.example.chickens; replace it with your project's own package.
A node makes one decision. shouldExecute only reads. execute makes one bounded call to a service. The
service dispatches the action and then waits for proof that it happened. Here is an attack node for the chicken
killer. It goes in tasks/combat/AttackNode.java:
package com.example.chickens.tasks.combat;
import privbot.task.SimpleNode;
import privbot.task.TaskPriorityBands;
import privbot.wrappers.PrivNPC;
import com.example.chickens.tasks.MyTaskContext;
public final class AttackNode extends SimpleNode<MyTaskContext> {
public AttackNode() {
super("Attack", TaskPriorityBands.COMBAT_ATTACK);
}
@Override
public boolean shouldExecute(MyTaskContext ctx) {
return ctx.runState.enabled && !ctx.combat.isInCombat()
&& ctx.npcs.query().withName("Chicken").alive().nearest() != null;
}
@Override
public boolean execute(MyTaskContext ctx) {
long epoch = ctx.runState.sessionEpoch;
PrivNPC chicken = ctx.npcs.query().withName("Chicken").alive().nearest(); // re-acquire: it may be gone
if (chicken == null || !chicken.attack()) {
status("No chicken to attack");
return false;
}
// true from attack() means the click was accepted. The fight starting is the proof.
boolean engaged = ctx.sleepUntil(() -> ctx.shouldAbort(epoch) || ctx.combat.isInCombat(), 3_000);
status(engaged ? "Fighting" : "Attack did not start a fight");
return engaged;
}
}
Register it in MyTaskTree: runner.addNodes(new EatFoodNode(), new AttackNode());. Priorities decide which
eligible node runs; eating (HAZARD_SECONDARY_HIGH) outranks attacking (COMBAT_ATTACK). In a real plugin, move
the targeting into a service, as the template's SupplyService does for food; see
cookbook/combat-slayer.md.
Test it without a game
privbot-api-testkit runs your nodes against a fake game: you script the world, and every action your plugin
sends is recorded. Add src/test/java/com/example/chickens/tasks/AttackNodeTest.java:
@Test
void attacksTheNearestChickenAndConfirmsTheFight() {
try (FakeGame game = FakeGame.builder().at(3235, 3295).commonReactions().build()) {
FakeNpc chicken = game.npcs().spawn(1173, "Chicken", 3236, 3295).actions(null, "Attack");
MyRunState state = new MyRunState();
MyTaskTree tree = new MyTaskTree(game.ctx(), state, new MyConfig() {});
state.resetSession();
state.enabled = true;
assertTrue(game.step(tree.getRunner()) instanceof AttackNode);
assertEquals(chicken.index(), game.lastDispatch().identifier());
assertTrue(game.player().isInCombat());
tree.shutdown();
}
}
Run the tests again with ./mvnw test. testing.md covers scripting the world, reactions, time and the
threading model.
4. Edit and reload without restarting
Developer mode loads your own jar into the running client.
- Turn on Developer mode in the launcher (Settings, Developer) before you start the client. Any active subscription can.
- Run
mvnw package. It copies the jar to~/.privbot/sideload/. Point it elsewhere with-Dprivbot.sideload.dir=<folder>, or set-Dprivbot.app.root=<folder>to use<folder>/sideload. Turn the copy off with-Dprivbot.sideload.skip=true. - The client sees the new jar within about 2 seconds, stops the old copy and loads the new one. Press Start yourself; a reloaded plugin always comes back stopped.
- The first time the client sees a new jar, it asks you to confirm and shows what the scan found. The plugin carries the badge Unverified local plugin until you upload it.
Only ids in your own namespace, u-<ownerTag>-<slug>, load from the sideload folder. For Orion build with
-Porion. The folder holds the variant you built last, so rebuild with the profile your client needs.
5. Work with an AI coding agent
The project is ready for Claude Code, Cursor and other agents. AGENTS.md, CLAUDE.md,
.cursor/rules/privbot.mdc, .mcp.json and .cursor/mcp.json are already in it, so open the folder in your agent
and start asking.
The agent's PrivBot tools come from java -jar sdk/tools/privbot-cli.jar agent-bridge. It serves API search
offline and forwards game and plugin tools to your running client, which must have Developer mode on (the client
publishes its address to ~/.privbot/dev/agent-bridge.json). The AI can read, build and reload. It never presses
Start, acts in the game or clicks: you start and stop the plugin.
ai-agents.md has the setup for each agent, every tool and what the AI cannot do.
6. Upload it for your own use
Run java -jar sdk/tools/privbot-cli.jar upload in the project folder (java -jar sdk/tools/privbot-cli.jar help
lists its options), or upload a zip of the project on the developer page; leave sdk/ and target/ out of the zip.
The command sends only your source.
PrivBot builds it against the published API, scans it (the lenient profile: network, file and reflection findings
are warnings) and signs it. The command makes the new version active (unless you pass --no-activate), and the
active version reaches every machine on your license. A plugin's first version activates by itself; a later version
uploaded on the developer page waits until you press Activate there. Build errors come back per file and
line. The plugin stays private to you. uploading.md has the flags, exit codes and how to read a
diagnostic.
7. List it in the community
Listing a plugin makes it available to every PrivBot customer.
- Accept the developer agreement first.
- Listing re-scans the plugin under the strict rules, so a plugin can pass privately and fail here.
- PrivBot reviews it. Once approved, it is free in every customer's hub under your display name.
- Each new version is reviewed again, and you can unlist the plugin at any time.
Where next
- concepts.md: the layers, the
ctx.*facades and which thread runs what. - threading-and-pitfalls.md: the rules that keep plugins working. Read it before your first real plugin.
- cookbook/: combat and slayer, skilling, banking, boss mechanics, PvP, overlays and UI.
- testing.md: the test kit in full.
- versioning.md: API versions and what a new SDK changes.
- compatibility.md: which API calls work on which server.
- The API reference: https://privbot.dev/javadoc/.
- A newer SDK: close your AI agent and run
java -jar sdk/tools/privbot-cli.jar sdk-update.
