Developer docs

PrivBot plugin API: versioning and compatibility

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.PublicApi on its package-info.java.
  • Inside those packages, a type or member marked @privbot.api.Internal is 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 RuneLite Client returns 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.version in the privbot-plugin-parent POM in your starter project's sdk/repository. When it moves, sdk-update brings 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-Version in their jar manifest. privbot-plugin-parent writes it, together with Plugin-Id, Plugin-Class, Plugin-Version, Plugin-Provider and Plugin-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-party channel, so PrivBot's own catalog keeps working while it is rebuilt.
  • From private, community and local it is refused, with a message to rebuild it using privbot-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

  1. Deprecate first. A covered member may be removed only in a major release, and it must have been @Deprecated (with a @deprecated javadoc that names the replacement) in at least one earlier minor release of the current major.
  2. Announce it. The API reference lists every deprecated member on its Deprecated page, https://privbot.dev/javadoc/deprecated-list.html, with the @deprecated text that names the replacement. Your IDE shows the same text from the javadoc jar in sdk/repository.
  3. 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.
  4. 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.