Kraken Plugins

Appearance

Building & Installing the API ​

The API is packaged as a JAR file and will be required to be on your classpath in order for your plugins to reference it within RuneLite. You generally have two options for this:

  • Run your plugin inside the Kraken client, which already puts the API on RuneLite's classpath, and load your plugin by sideloading it or through an external repository
  • Provide the API yourself, either by bundling it into a "fat jar" with your plugin classes or by adding it to RuneLite's classpath in your own launcher

This document isn't intended to cover integrating the API into your plugin build and release process. The API will come packaged as a standard JAR file. How you choose to integrate and provide the API to your plugins is up to you and your build process. The published jar bundles the shortest-path pathfinding library and its data; everything else it uses (RuneLite, Guice, Guava, Gson, SLF4J, Lombok) is provided by RuneLite at runtime.

Gradle Example ​

To use the API jar file in your plugin project you will need to either:

  • export GITHUB_ACTOR=<YOUR_GITHUB_USERNAME>; export GITHUB_TOKEN=<GITHUB_PAT>
  • or add the following to your gradle.properties file: gpr.user=your-github-username gpr.key=your-personal-access-token

More information on generating a GitHub Personal Access token can be found below.

Authentication ​

Since the API packages are hosted on GitHub Packages you will need to generate a Personal Access Token (PAT) on GitHub to authenticate and pull down the API.

You can generate a GitHub PAT by navigating to your GitHub Settings and clicking "Generate new Token." Give the token a unique name and optional description with read-only access to public repositories. Store the token in a safe place as it won't be viewable again. It can be used to authenticate to GitHub and pull Kraken API packages.

⚠️ Do NOT share this token with anyone.

groovy
plugins {
    id 'java'
    id 'application'
}


// Replace with the package version of the API you need, e.g. '5.0.0'.
// You can also float on the latest release with '+' or '5.0.+' so you don't have to bump the version by hand.
def krakenApiVersion = 'X.Y.Z'

allprojects {
    apply plugin: 'java'
    repositories {
        // Pulls a locally built API first (see "Building from source")
        mavenLocal {
            content {
                includeGroup "com.github.kraken"
            }
        }

        // You must declare this maven repository to be able to search and pull Kraken API packages
        maven {
            name = "GitHubPackages"
            url = uri("https://maven.pkg.github.com/Kraken-Plugins/kraken-api")
            credentials {
                username = project.findProperty("gpr.user") ?: System.getenv("GITHUB_ACTOR")
                password = project.findProperty("gpr.key") ?: System.getenv("GITHUB_TOKEN")
            }
        }

        // Jitpack is an alternative means of accessing the API Jar file
        maven { url 'https://jitpack.io' }
    }
}


dependencies {
    compileOnly group: 'com.github.kraken', name:'kraken-api', version: krakenApiVersion
    // ... other dependencies
}

Note: GitHub Packages keeps only the five most recent API versions. Pin to a recent release or use a floating version.

Maven Build Example ​

Here is an example of a Maven pom.xml using the Kraken API.

xml
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="
           http://maven.apache.org/POM/4.0.0
           https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.example</groupId>
    <artifactId>kraken-client</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <packaging>jar</packaging>

    <properties>
        <maven.compiler.source>11</maven.compiler.source>
        <maven.compiler.target>11</maven.compiler.target>
        <!-- Replace with the package version of the API you need -->
        <kraken.api.version>X.Y.Z</kraken.api.version>
    </properties>

    <repositories>
        <repository>
            <id>github</id>
            <name>GitHubPackages</name>
            <url>https://maven.pkg.github.com/Kraken-Plugins/kraken-api</url>
            <releases><enabled>true</enabled></releases>
            <snapshots><enabled>true</enabled></snapshots>
        </repository>
    </repositories>

    <dependencies>
        <dependency>
            <groupId>com.github.kraken</groupId>
            <artifactId>kraken-api</artifactId>
            <version>${kraken.api.version}</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>
    
    <!-- Rest of your build goes here -->
    
    <!-- Configure GitHub Packages authentication -->
    <distributionManagement>
        <repository>
            <id>github</id>
            <name>GitHubPackages</name>
            <url>https://maven.pkg.github.com/Kraken-Plugins/kraken-api</url>
        </repository>
    </distributionManagement>
</project>

Since Maven doesn't support inline credentials like Gradle does, you will need to edit your ~/.m2/settings.xml file with the following:

xml
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                              https://maven.apache.org/xsd/settings-1.0.0.xsd">
  
  <servers>
    <!-- GitHub Packages authentication -->
    <server>
      <id>github</id>
      <username>${env.GITHUB_ACTOR}</username>
      <password>${env.GITHUB_TOKEN}</password>
    </server>
  </servers>

  <profiles>
    <profile>
      <id>github</id>
      <repositories>
        <repository>
          <id>github</id>
          <url>https://maven.pkg.github.com/Kraken-Plugins/kraken-api</url>
          <releases><enabled>true</enabled></releases>
          <snapshots><enabled>true</enabled></snapshots>
        </repository>
      </repositories>
    </profile>
  </profiles>

  <activeProfiles>
    <activeProfile>github</activeProfile>
  </activeProfiles>
</settings>

Building from Source ​

The API is a Java 11 project built with the Gradle wrapper (8.11) and compiled against RuneLite 1.12.38. Clone it with submodules so the shortest-path dependency is present:

shell
git clone --recurse-submodules https://github.com/Kraken-Plugins/kraken-api.git
cd kraken-api

# Build, run the unit tests, and install to ~/.m2
./gradlew clean build publishToMavenLocal shadowJar

# Optionally build under a specific version
VERSION=5.0.0-SNAPSHOT-LOCAL ./gradlew clean build publishToMavenLocal shadowJar

The jar lands in ~/.m2/repository/com/github/kraken/kraken-api/<version>/ and in build/libs/. With VERSION unset the version is 1.0.0. Reference it from your plugin with the mavenLocal repository shown in the Gradle example above.

Other useful tasks:

shell
./gradlew test                          # JUnit 5 unit tests only (src/test/java/unit)
./gradlew runelite                      # Launch RuneLite with the in-client API test plugin loaded

Building the Example Plugins ​

The example plugins build against the published API and put every plugin JAR in build/plugins:

shell
export GITHUB_ACTOR=<github-username>
export GITHUB_TOKEN=<github-personal-access-token>

./gradlew clean buildAndCollectSimpleJars --stacktrace --parallel

Set KRAKEN_API_VERSION to build against a different API version than the default pinned in build.gradle.

API Versioning ​

Each release of the API publishes a new semantic version. CI bumps the patch version on every merge; minor and major bumps are made by editing version.txt in the repository. Tags are the bare version number (for example 5.0.0). You can check the latest versions of the API here. Release notes are published on that page and in the Kraken Discord. Breaking releases get a migration guide; see Migrating to 5.0.