{"id":20646687,"url":"https://github.com/cbartram/kraken-api","last_synced_at":"2026-02-06T18:23:49.720Z","repository":{"id":310519923,"uuid":"1039719249","full_name":"cbartram/kraken-api","owner":"cbartram","description":"API for creating RuneLite plugins supporting client interactions (clicking things in the game)!","archived":false,"fork":false,"pushed_at":"2026-01-16T22:22:57.000Z","size":6771,"stargazers_count":2,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-01-17T11:23:19.924Z","etag":null,"topics":["client","interaction","kraken","plugin","runelite"],"latest_commit_sha":null,"homepage":"https://kraken-plugins.com","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cbartram.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-17T20:55:10.000Z","updated_at":"2026-01-13T19:03:16.000Z","dependencies_parsed_at":"2025-08-18T17:35:43.353Z","dependency_job_id":"7aba3c7d-ae52-4a00-8284-c76b1d61a70b","html_url":"https://github.com/cbartram/kraken-api","commit_stats":null,"previous_names":["cbartram/kraken-api"],"tags_count":318,"template":false,"template_full_name":null,"purl":"pkg:github/cbartram/kraken-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cbartram%2Fkraken-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cbartram%2Fkraken-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cbartram%2Fkraken-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cbartram%2Fkraken-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cbartram","download_url":"https://codeload.github.com/cbartram/kraken-api/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cbartram%2Fkraken-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28642695,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-21T18:04:35.752Z","status":"ssl_error","status_checked_at":"2026-01-21T18:03:55.054Z","response_time":86,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["client","interaction","kraken","plugin","runelite"],"created_at":"2024-11-16T16:26:47.883Z","updated_at":"2026-01-25T19:19:10.948Z","avatar_url":"https://github.com/cbartram.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- PROJECT LOGO --\u003e\n\u003cbr /\u003e\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://kraken-plugins.com\"\u003e\n    \u003cimg src=\"lib/src/main/resources/kraken.png\" alt=\"Logo\" width=\"128\" height=\"128\"\u003e\n  \u003c/a\u003e\n\n\u003ch3 align=\"center\"\u003eKraken API\u003c/h3\u003e\n\n  \u003cp align=\"center\"\u003e\n   An extended RuneLite API for creating plugins that support client interactions.\n    \u003cbr /\u003e\n\u003c/div\u003e\n\n[![Release Kraken API](https://github.com/cbartram/kraken-api/actions/workflows/release.yml/badge.svg?branch=master)](https://github.com/cbartram/kraken-api/actions/workflows/release.yml)\n[![Contributors][contributors-shield]][contributors-url]\n[![Forks][forks-shield]][forks-url]\n[![Stargazers][stars-shield]][stars-url]\n[![Issues][issues-shield]][issues-url]\n\n---\n\n# Getting Started\n\nKraken API is designed to extend the RuneLite API with additional client interaction utilities for writing automation-based plugins that are fully compatible with RuneLite.\nThis API uses network packets to perform \"click\" interactions within the game client and is based on mappings defined by the [EthanVann API](https://github.com/Septharoth/EthanVannPlugins/tree/master). It's also worth shouting\nout the [Vitalite](https://github.com/Tonic-Box/VitaLite/) client and project as their open source expertise of the game client helped make some of the Kraken API possible!\n\nSpecifically credit to Vitalite's Dialogue, G.E., and World Map API's and inspiration on Kraken's `TaskChain` and `ReplayStrategy` for mouse movement!\n\n## API Usage\n\nThe following RuneLite \"plugin\" is purely for an example of the API's capabilities and isn't a full-fledged automation script.\n\n```java\n@PluginDescriptor(\n        name = \"Example\",\n        description = \"Example plugin\"\n)\npublic class ExamplePlugin extends Plugin {\n    \n    @Inject\n    private Context ctx;\n    \n    @Inject\n    private BankService bank;\n    \n    @Inject\n    private MovementService movement;\n    \n    @Inject\n    private PrayerService prayer;\n    \n    @Subscribe\n    private void onGameTick(GameTick e) {\n      Player local = ctx.players().local().raw();\n      \n      if(local.isInteracting()) {\n          return;\n      }\n      \n      if(!bank.isOpen()) {\n          // Open a bank\n          ctx.gameObjects().withName(\"Bank booth\").nearest().interact(\"Open\");\n      } else {\n          // Withdraw a Rune Scimitar\n          ctx.bank().nameContains(\"Rune scimitar\").first().withdraw();\n      }\n      \n      // Wield a Rune Scimitar\n      ctx.equipment().withId(1333).first().wield();\n      \n      // Move to a new position\n      movement.moveTo(new WorldPoint(1234, 5678));\n      \n      // Activate a protection prayer\n      prayer.activatePrayer(Prayer.PROTECT_FROM_MELEE);\n      \n      // \"Click\" on a Goblin and attack it.\n      ctx.npcs().withName(\"Goblin\")\n            .except(n -\u003e n.raw().isInteracting())\n            .nearest()\n            .interact(\"Attack\");\n      \n      \n      // Take the goblin bones\n      ctx.groundItems().reachable()\n              .within(5)\n              .filter(item -\u003e item.name().equalIgnoreCase(\"bones\"))\n              .first()\n              .take();\n      \n      // Bury the bones\n      ctx.inventory().withName(\"Bones\").first().interact(\"Bury\");\n    }\n}\n```\n\nTo use the API in an actual RuneLite plugin, you should check out the [Kraken Example Plugin](https://github.com/cbartram/kraken-example-plugin)\nwhich shows a best practice usage of the API within an actual plugin.\nTo set up your development environment, we recommend following [this guide on RuneLite's Wiki](https://github.com/runelite/runelite/wiki/Building-with-IntelliJ-IDEA).\n\nOnce you have the example plugin cloned and setup within Intellij, you can run the main class in `src/test/java/ExamplePluginTest.java` to run RuneLite with\nthe example plugin loaded in the plugin panel within RuneLite's sidebar. See [consuming the API](#consuming-the-api) section for more information on\nintegrating the API into your plugins and build process.\n\n![example-plugin](./images/example-plugin.png)\n\n\u003e If you are just looking to use pre-existing plugins, you can skip this repository and head over to our website: [kraken-plugins.com](https://kraken-plugins.com). \n\u003e For more documentation on the API and Kraken plugins please see our [official documentation here](https://kraken-plugins.com/docs/).\n\n### Prerequisites\n- [Java 11+](https://adoptium.net/) (JDK required)\n- [Gradle](https://gradle.org/) (wrapper included, no need to install globally)\n- [Git](https://git-scm.com/)\n- [RuneLite](https://runelite.net) (for testing and running plugins)\n\n### Building\n\nYou can build the project with Gradle:\n\n```bash\n./gradlew clean build\n```\n\nThe output API `.jar` will be located in:\n\n```\n./lib/build/libs/kraken-api-\u003cversion\u003e.jar\n```\n\n## Gradle Example (Simple)\n\nAlthough we recommend using the [Github packages approach](#gradle-example-recommended) to access the API since it is more reliable, [Jitpack](https://jitpack.io/) can get you set up with\nthe Kraken API without a personal access token.\n\n```groovy\nplugins {\n    id 'java'\n    id 'application'\n}\n\n// Replace with the package version of the API you need\ndef krakenApiVersion = 'X.Y.Z'\n\nallprojects {\n    apply plugin: 'java'\n    repositories {\n        maven { url 'https://jitpack.io' }\n    }\n}\n\n\ndependencies {\n    compileOnly group: 'com.github.cbartram', name:'kraken-api', version: krakenApiVersion\n    // ... other dependencies\n}\n```\n\n## Gradle Example (Recommended)\n\nTo use the API jar file in your plugin project you will need to either:\n- `export GITHUB_ACTOR=\u003cYOUR_GITHUB_USERNAME\u003e; export GITHUB_TOKEN=\u003cGITHUB_PAT`\n- or add the following to your `gradle.properties` file: `gpr.user=your-github-username gpr.key=your-personal-access-token`\n\nMore information on generating a GitHub Personal Access token can [be found below](#authentication).\n\n###  Authentication\n\nSince the API packages are hosted on [GitHub Packages](https://docs.github.com/en/packages/learn-github-packages/introduction-to-github-packages) you will\nneed to generate a [Personal Access Token (PAT)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens?versionId=free-pro-team%40latest\u0026productId=packages\u0026restPage=learn-github-packages%2Cintroduction-to-github-packages) on GitHub\nto authenticate and pull down the API.\n\nYou can generate a GitHub PAT by navigating to your [GitHub Settings](https://github.com/settings/personal-access-tokens)\nand clicking \"Generate new Token.\" Give the token a unique name and optional description with read-only access to public repositories. Store the token\nin a safe place as it won't be viewable again. It can be used to authenticate to GitHub and pull Kraken API packages.\n\n\u003e :warning: Do **NOT** share this token with anyone.\n\n```groovy\nplugins {\n    id 'java'\n    id 'application'\n}\n\n\n// Replace with the package version of the API you need\ndef krakenApiVersion = 'X.Y.Z'\n\nallprojects {\n    apply plugin: 'java'\n    repositories {\n        // You must declare this maven repository to be able to search and pull Kraken API packages\n        maven {\n            name = \"GitHubPackages\"\n            url = uri(\"https://maven.pkg.github.com/cbartram/kraken-api\")\n            credentials {\n                username = project.findProperty(\"gpr.user\") ?: System.getenv(\"GITHUB_ACTOR\")\n                password = project.findProperty(\"gpr.key\") ?: System.getenv(\"GITHUB_TOKEN\")\n            }\n        }\n\n        // Jitpack is an alternative means of accessing the API Jar file\n        maven { url 'https://jitpack.io' }\n    }\n}\n\n\ndependencies {\n    compileOnly group: 'com.github.cbartram', name:'kraken-api', version: krakenApiVersion\n    implementation group: 'com.github.cbartram', name:'shortest-path', version: '1.0.3'\n    // ... other dependencies\n}\n```\n\n## API Design \u0026 Methodology\n\nThe API is broken up into 2 distinct ways of accessing game information:\n\n- Services (`com.kraken.api.service`)\n- Query System (`com.kraken.api.query`)\n\nEach API paradigm has its strengths, and it's likely you will need both when building semi and fully autonomous RuneLite\nplugins. Read more about each API paradigm below to see which one (or a combination of both) suites your plugin needs.\n\n### Services\n\nServices leverage the software design pattern of dependency injection. This is the exact same pattern adopted by RuneLite \nto ensure that plugins get exactly what they need to run from RuneLite and nothing more. As the developer you will declare to \nyour script what you need from the Kraken API and the dependencies will be directly injected into your script at runtime.\nDependency injection ensures that your script classes remain lightweight, testable, and easy to debug.\n\nThe Service API paradigm is useful for static widgets or global game entities, for example:\n\n- Bank interface - There is only a single bank interface to open, close, and set withdrawal modes on\n- Prayers - A finite number of static prayer widgets\n- Spells - A fixed number of in-game spells\n- UI - Static utilities for calculating UI element bounds, interfacing with Dialogue, and switching client tabs\n- Camera - A single camera exists and is centered around your local player (`ctx.cameras().first()` doesn't really make much sense!)\n- etc...\n\nIf you needed to toggle a prayer, cast a spell, or close the bank then the service API paradigm would suite your plugin\nwell.\n\n### Query System\n\nThe query system allows you to flexibly \"query\", refine, and filter for dynamic game entities like:\n\n- Players\n- NPC's\n- Game objects\n- Ground Items\n- Widgets\n- Worn equipment (in the interface as well as your inventory)\n- Inventory items\n- and Bank items\n\nThe query paradigm wraps familiar RuneLite API objects with an `Interactable` interface allowing you to not\nonly __find__ game entities but also __interact__ with them in a straightforward fashion. \nAll interactions use network packets to communicate directly with the game servers.\n\nThe API utilizes method chaining to filter for specific game entities loaded within the scene and exposes all methods on the underlying RuneLite \nAPI objects using the `raw()` method on every wrapped game entity class. \n\nThe entire query API is exposed through a single class called the game `Context`.\nThis singleton class allows you to have one lightweight dependency which functions as a facade to query just about any game entity you would want for plugin development.\n\nFor example, to attack a nearby Goblin: \n\n```java\n@PluginDescriptor(\n        name = \"Example\",\n        description = \"Example plugin\"\n)\npublic class ExamplePlugin extends Plugin {\n    \n    @Inject\n    private Context ctx;\n    \n    @Subscribe\n    private void onGameTick(GameTick e) {\n        Player local = ctx.players().local().raw();\n        \n        if(local.isInteracting()) {\n            return;\n        }\n\n        ctx.npcs().withName(\"Goblin\")\n                .except(n -\u003e n.raw().isInteracting())\n                .nearest()\n                .interact(\"Attack\");\n    }\n}\n```\n\nThe entire query API is designed to be thread safe so any queries, filters, or interactions can be run on non-client threads. \nWhen callable methods need to execute on RuneLite's client thread they will be scheduled there, blocking until the method executes. \nThis helps ensure your plugin code is fully thread safe, predictable, and easy to read.\n\nTo see specific examples of various queries check out the [API tests](https://github.com/cbartram/kraken-api/tree/master/lib/src/test/java) which utilize a real RuneLite plugin to query and find\nvarious game entities around Varrock east bank.\n\n\u003e :warning: When running on non-client threads the action must be scheduled on the client thread and is thus asynchronous in nature.\n\n## Structure\n\nThe Kraken API exposes both high and low level functions for working with\ngame objects, NPC's, movement, pathing, simulations, network packets, and more. \nThe documentation below describes the most likely packages developers will use when writing scripts or plugins.\n\n- `core` - The package contains abstract base class logic which is used internally by different API methods and exposes the `Script` class.\n  - `core.packet` - The package includes low and high level API's to send network packets to game servers for automation actions.\n    - `core.packet.entity` - Generally most packet layer use cases will use the `core.packet.entity` API for interaction with Game Objects, NPC's, interfaces, and players.\n- `service` - The package contains high level API's for directly interacting with static/global game elements such as (banking, prayer, spells, etc...) and use the `core.packet` package to form the backbone for the interactions\n- `input` - Contains classes to help process and use input devices like mouses and keyboards.\n- `query` - Contains the query API classes for finding and interacting with dynamic game elements like: inventory, npcs, players, game objects, and more.\n- `overlay` - Contains simple and common overlays which can be directly used in RuneLite plugins e.g. Mouse position\n- `sim` - Includes classes for simulating game ticks, NPC pathing, movement, line of sight, and players. This is useful for advanced\n  plugins which evaluate hundreds of potential outcomes every game tick to determine the best \"decision\". e.g. Inferno and Colosseum plugins\n\n## Scripting\n\nFor more information on writing scripts using the Kraken API \ncheck out the detailed [scripting guide](docs/SCRIPTING.md).\n\n## Mouse Movement\n\nFor more information on mouse movement in the API check out the\ndetailed [mouse movement guide](docs/MOUSE.md)\n\n## Game Updates\n\nPlease see the game updates and [how to update the API guide](docs/UPDATING.md) for more detailed information.\n\n## Running Tests\n\nPlease see the [testing guide](docs/TESTS.md) for more information on running tests.\n\n## Development Workflow\n\n1. Create a new branch from `master`\n2. Implement or update your plugin/feature for the API\n3. Add tests for new functionality\n4. Run `./gradlew build` to verify that the API builds and tests pass\n5. Commit your changes with a clear message `git commit -m \"feat(api): Add feature X to Kraken API\"`\n6. Open a Pull Request\n\n---\n\n## Deployment\n\nThe Kraken API is automatically built and deployed via GitHub actions on every push to the `master` branch.\nThe latest version can be found in the [releases](https://github.com/cbartram/kraken-api/releases) section of the repository.\n\nThe deployment is fully automated and consists of:\n\n-  Building the API JAR\n- Publishing a new version to the GitHub Releases section\n  - This will be picked up by Github Packages for easy integration into other gradle projects.\n- Uploading the JAR file to the Minio storage server used by the Kraken Client at runtime.\n\n---\n\n## 🛠 Built With\n\n* [Java](https://www.java.org/) — Core language\n* [Gradle](https://gradle.org/) — Build tool\n* [RuneLite](https://runelite.net) — Used for as the backbone for the API\n\n---\n\n## 🤝 Contributing\n\nPlease read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.\n\n---\n\n## 🔖 Versioning\n\nWe use [Semantic Versioning](http://semver.org/).\nSee the [tags on this repository](https://github.com/cbartram/kraken-api/tags) for available releases.\n\nCI will automatically bump the patch version on each merge to master i.e. `1.1.4` -\u003e `1.1.5`. If you want to bump \na minor or major version then update the `version.txt` file in the root of the repository with the new version you\nwant to use as a base.\n\nFor example, moving from: `1.3.5` -\u003e `1.4.0` the `version.txt` should be `1.4.0`.\n\n---\n\n## 📜 License\n\nThis project is licensed under the [GNU General Public License 3.0](LICENSE).\n\n---\n\n## 🙏 Acknowledgments\n\n* **RuneLite** — For API's to work with and view in game data for Old School RuneScape\n* **Packet Utils** - [Plugin](https://github.com/Ethan-Vann/PacketUtils) from Ethan Vann providing access to complex packet sending functionality which was used to develop the `core.packet` package of the API\n* **Vitalite** - Vitalite for showing some incredible open source examples of dialogue, GE interactions, packets, mouse movement, and just working with the client in general\n* **VitaLite Mappings** - Huge shoutout for the VitaLite devs to maintain and publish these mappings for obfuscated classes and methods\n* **Microbot** — For clever ideas on client and plugin interaction using reflection.\n* **[Lucid](https://github.com/lucid-plugins/SideloadPlugins) \u0026 [Kotori](https://github.com/OreoCupcakes/kotori-plugins/blob/master/kotoriutils/src/main/java/com/theplug/kotori/kotoriutils/rlapi/table/TableComponent.java) plugins** — For their open source implementation on the Table UI element. \n\n[contributors-shield]: https://img.shields.io/github/contributors/cbartram/kraken-api.svg?style=for-the-badge\n[contributors-url]: https://github.com/cbartram/kraken-api/graphs/contributors\n[forks-shield]: https://img.shields.io/github/forks/cbartram/kraken-api.svg?style=for-the-badge\n[forks-url]: https://github.com/cbartram/kraken-api/network/members\n[stars-shield]: https://img.shields.io/github/stars/cbartram/kraken-api.svg?style=for-the-badge\n[stars-url]: https://github.com/cbartram/kraken-api/stargazers\n[issues-shield]: https://img.shields.io/github/issues/cbartram/kraken-api.svg?style=for-the-badge\n[issues-url]: https://github.com/cbartram/kraken-api/issues\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcbartram%2Fkraken-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcbartram%2Fkraken-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcbartram%2Fkraken-api/lists"}