Developer docs

Getting started: from a download to a running plugin

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:

  1. Sign in with your PrivBot account.
  2. Name the plugin and pick the servers it supports: Impact, Elorin, Orion, SpawnPK or Roat Pkz.
  3. 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.

  1. Turn on Developer mode in the launcher (Settings, Developer) before you start the client. Any active subscription can.
  2. 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.
  3. 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.
  4. 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