Plugins written by customers, by the community and by the AI builder will outlive many PrivBot releases. This page says what the API promises, how its version moves, and what the client does with a plugin built against another version.
What is covered
- The supported surface is every package in the public API list: the packages of the API reference,
https://privbot.dev/javadoc/. Each one carries
@privbot.api.PublicApion itspackage-info.java. - Inside those packages, a type or member marked
@privbot.api.Internalis not covered. It is public only for technical reasons, such as a facade constructor that takes an adapter, or a server-specific helper. - Everything else in the PrivBot client is internal, whatever its Java visibility. The plugin policy scanner refuses
references to it in strict builds (rule
INTERNAL_API), and it may change in any release. ctx.getClient()is a documented escape hatch, not a promise: what the RuneLiteClientreturns differs by server and by client build.- RuneLite types (
net.runelite.api.*) appear in the API but are RuneLite's to change. PrivBot pins one RuneLite version per API line:runelite.versionin theprivbot-plugin-parentPOM in your starter project'ssdk/repository. When it moves,sdk-updatebrings the new parent.
Version numbers
The API has its own semantic version, MAJOR.MINOR.PATCH, starting at 1.0.0. It is separate from the version of any single jar.
| Bump | When | Examples |
|---|---|---|
| MAJOR | A binary-incompatible change to the covered surface. | Removing or renaming a public member; changing a parameter or return type (void to boolean is a break); making a class final; narrowing visibility. |
| MINOR | New covered API, binary-compatible. | A new facade method, a new type in a public package, a new public package, a new deprecation. |
| PATCH | No API change. | Bug fixes and behaviour corrections behind the same signatures. |
- The API version your project builds against is in
sdk/sdk.properties(apiVersion). - Plugins record the version they compiled against as
Plugin-Api-Versionin their jar manifest.privbot-plugin-parentwrites it, together withPlugin-Id,Plugin-Class,Plugin-Version,Plugin-ProviderandPlugin-Servers.
Compatibility rule
ApiVersion.isCompatible(pluginApiVersion): a plugin may load when it has the same major as the runtime
and its minor is not newer than the runtime's. Patch levels and qualifiers (-SNAPSHOT) never matter.
| Plugin built against | Runtime 1.4.2 | Runtime 2.0.0 |
|---|---|---|
| 1.0.0 | loads | refused: rebuild against 2.x |
| 1.4.9 | loads | refused |
| 1.5.0 | refused: update PrivBot | refused |
| 2.0.0 | refused: update PrivBot | loads |
| (none) | first-party only | first-party only |
latest (malformed) |
refused | refused |
ApiVersion.check(pluginApiVersion, channel) returns the decision with a message fit to show the user. The
client loader and the build service use it. A version that does not parse is refused, never guessed.
Legacy plugins (no Plugin-Api-Version)
Every plugin built before 1.0.0 lacks the entry. Such a plugin is legacy:
- It loads only from the
first-partychannel, so PrivBot's own catalog keeps working while it is rebuilt. - From
private,communityandlocalit is refused, with a message to rebuild it usingprivbot-plugin-parent. - First-party plugins should gain the entry on their next rebuild. The allowance for legacy first-party plugins ends with the first major release (2.0.0).
Deprecation window
- Deprecate first. A covered member may be removed only in a major release, and it must have been
@Deprecated(with a@deprecatedjavadoc that names the replacement) in at least one earlier minor release of the current major. - Announce it. The API reference lists every deprecated member on its Deprecated page,
https://privbot.dev/javadoc/deprecated-list.html, with the
@deprecatedtext that names the replacement. Your IDE shows the same text from the javadoc jar insdk/repository. - Keep it working. A deprecated member keeps working until its removal. "Deprecated" is not a licence to break it in a minor or patch release.
- Mark wrong-but-public types
@Internal; don't just remove them. Marking takes them out of the promise for the next release. Plugins that used them still compile, and they show up in the policy scan.
Supported versions: N and N-1
- Inside a major line: every older minor of the same major is supported. A 1.0 plugin runs on every 1.x client.
- Across a major (N and N-1):
- When major N ships, the hub keeps serving the N-1 build of each plugin to clients still on N-1.
- Authors may publish both builds for at least one minor release of N.
- The build service compiles uploads for N, and for N-1 on request, for the same window.
- After that, N-1 builds are no longer accepted. Existing N-1 builds stay installable until N+1 ships.
- No mixing: a client never loads a plugin from another major. A plugin that needs both lines ships two builds.
PrivBot checks every release against the previous one before it ships; a break needs a major version.
Artifacts
All three are versioned with the API. Your starter project already has them in sdk/repository/.
| Coordinates | What it is |
|---|---|
com.privbot:privbot-api |
Compile-only signatures of the public packages (the API jar): every method body throws UnsupportedOperationException("PrivBot API stub"), and the client supplies the real classes at run time. A -javadoc.jar documents the same packages; there is no sources jar. Its manifest carries PrivBot-Api-Version and PrivBot-Api-Stub: true. Always provided. |
com.privbot:privbot-bom |
Aligned versions of privbot-api, privbot-api-testkit, the privbot-runtime the test kit runs on and the Orion client stub, for builds that do not use the parent. |
com.privbot:privbot-plugin-parent |
The parent for plugins you build yourself. It sets Java 11 and the provided dependencies, writes the manifest entries from privbot.plugin.id, privbot.plugin.class, privbot.plugin.servers and privbot.plugin.provider, and has an orion profile for the Orion variant. |
Publishing to a public Maven repository is not set up; the artifacts ship inside your starter project.
