OpenOSRS Plugins

This guide requires you to have followed the Building with IntelliJ-IDEA article.

Configure IntelliJ

It is recommended to set the external.system.substitute.library.dependencies setting which allows IntelliJ to associate the client and plugins repositories with each other. To do so press Ctrl+Shift+A and enter registry and press enter.

Locate external.system.substitute.library.dependencies in the list, check the box and restart IntelliJ.

Configure client build

The client build must be configured to publish the required artifacts to your local maven repository. This will allow the plugin builds to use these artifacts.

Edit the build configurations:

And ensure the runelite [build] configuration has the following Tasks:

build publishToMavenLocal :runelite-client:publishToMavenLocal :runelite-api:publishToMavenLocal :http-api:publishToMavenLocal

Press Ok and run the runelite [build] configuration. You will have to re-run this whenever you make code changes to the client which you require from a plugin.

Initial plugin repository setup

Note: The following steps can be repeated for each plugin repository you wish to work on. You should always start with the official https://github.com/open-osrs/plugins repository, as many others depend on it.

Back at the IntelliJ welcome screen choose Get from Version Control and clone the https://github.com/open-osrs/plugins repository. Take note of where it is downloaded to.

Wait for IntelliJ to finish importing, indexing, updating dependencies, etc (see status in the bottom right).

Go to File > Close project and choose the OpenOSRS project (the client).

Adding plugins to the client build

Expand the Gradle panel on the right side of the IntelliJ window. Click the + symbol and navigate to the plugin repository folder, and select the build.gradle.kts

Wait for the import to complete, then in the Gradle panel navigate to OpenOSRS Plugins > Tasks > build > build, right-click and select Create 'plugins [build]'.

Change Tasks to: build copyDeps publishToMavenLocal

Note: The above tasks work for the official OpenOSRS Plugins repo. If you're building another repo, they might not have the copyDeps or publishToMavenLocal goals available. If you get errors regarding these goals, you can omit them here or contact the repository owner.

You may also choose to skip the tests by changing Arguments to: -x test

Press Ok and run the build to verify.

Using your locally built plugins

There are several options to actually play using the plugins you just built.

Manual copy

The most simple option is to manually copy the plugin files from the plugins/release folder into your $HOME/.openosrs/plugins folder.

Automatic copy

Note: The following works for the official OpenOSRS Plugins repo. If you're building another repo, they might not have the releaseToExternalmanager property available.

You can have Gradle automatically copy the plugin file to your externalmanager folder every time you build. To do so modify your plugins [build] configuration and add -PreleaseToExternalmanager=all to Arguments. Alternatively you can provide a comma-separated list of plugin names to copy (e.g. -PreleaseToExternalmanager=worldmap,xpglobes).

Running from source

Note: The following works for the official OpenOSRS Plugins repo. If you're building another repo, they might not be structured correctly or have the copyDeps build goal available.

This will allow you to make full use of IntelliJs hot reload functionality, allowing you to develop your plugin while almost never having to restart the client.

Modify your runelite [run] configuration's environment variables:

Set the PLUGIN_DEVELOPMENT_PATH environment variable to a semicolon separated list of your plugin repositories.

For example, if your folder stucture is:

C:\code\openosrs\
├──runelite
├──plugins
└──some-other-plugin-repo

Then you could set PLUGIN_DEVELOPMENT_PATH=../plugins\;../some-other-plugin-repo. Alternatively you could use absolute paths.

Once done run a build:

Then start the project in debug mode:

You should see all plugins get loaded, and the Configuration tab should have a reload symbol next to each plugin. This button will disable the plugin, unload it, reload it, and re-enable it.

Hot reloading example

When making code changes in your plugin you can recompile just that plugin module, which will be considerably faster than recompiling the entire project:

IntelliJ will ask you if you want to hot reload:

Say Yes.

Depending on your changes you will either see a green prompt:

Or a red prompt:

When the prompt is red you must do a full reload of your plugin, by clicking the reload button in the client's Configuration tab.

When the prompt is green your change was successfully hot reloaded. However, depending on the kind of change, you must still restart your plugin using the reload button in the client's Configuration tab.