Table of Contents

• Getting started
• Importing the project
• Installing Lombok
• Building the project
• Running the project
• Conclusion
• Advanced
  • RS Injection Assist
• Troubleshooting
  • Missing git
  • JDK Issues
  • Client failing to start
  • Enable annotation processing
  • Update your fork
  • Skip gradle tests

Getting started

For working with this project, IntelliJ IDEA is our recommended IDE and the one used by most collaborators. The free community edition has everything you'll need to start testing and contributing real improvements to the project.

You can build OpenOSRS locally using JDK 11 as the codebase supports language features up to Java 11. RuneLite mixins are the exception - these are are limited to Java 7.

Direct JDK download links:
Linux (x64)
MacOS (x64)
Windows (x64)
Windows (x86)

Importing the project

After launching IntelliJ IDEA for first time, you will see IntelliJ welcome window. You will now need to clone OpenOSRS repository from git:

After clicking on that you will be greeted with prompt. You can either enter the OpenOSRS repository https://github.com/open-osrs/runelite or your own GitHub fork, if you've created one.

NOTE: If you plan to make a Pull Request, you must fork the OpenOSRS repository, and clone from your fork. You can do this by navigating to https://github.com/open-osrs/runelite and clicking the fork button.

The prompt should look something like this (if you have issues with finding git.exe see Troubleshooting section):

Click Clone. Now IntelliJ should start cloning the repository:

If everything went well, you should be able to see something like this:

The current status is shown at (1). Wait until this finishes and no longer shows any text like "Indexing" or "Importing dependencies".

The gradle sync status is shown at (2). This should show success. If not check the JDK Issues section under Troubleshooting.

The project view is shown at (3). If this is not visible you can click "Project" in the sidebar to reveal it.

The gradle sidebar is shown at (4). This will show all Gradle tasks, which we'll get back to later.

Press the Build button (5) to test if the import succeeded.

Installing Lombok

When first viewing the project in IntelliJ IDEA you may come across this error:

This is because you do not have the Lombok Plugin installed.

Navigate to the Plugins tab under the File > Settings menu (IntelliJ IDEA > Preferences for Mac). Click the Marketplace button and search for Lombok to find it. Install the plugin and restart IntelliJ IDEA.

If you then get the following dialog, click Enable:

If you did not see this dialog but still have issues, see Enable annotation processing.

Success! You should no longer be getting Cannot resolve symbol or Cannot resolve method errors.

Building the project

OpenOSRS is using Gradle as build tool. It is used for dependency management, resource generation, running tests and any other tooling needed to properly build, run and deploy OpenOSRS.

So, to actually run OpenOSRS, we first need to invoke Gradle.

Locate Gradle on right-side of the screen until you open something like this:

Navigate to Tasks > build > build, right-click and select Modify run configuration:

A window like this should pop-up.

Modify the Tasks and change it to:

build publishToMavenLocal :runelite-client:publishToMavenLocal :runelite-api:publishToMavenLocal :http-api:publishToMavenLocal -x test -x checkstyleMain

You can choose to skip running the unit tests for each build, which will speed them up greatly. However, if you intend to submit a pull request you must ensure the tests pass! If you do choose to skip the tests you can append -x test to the Arguments. Tests are current out of date and will fail on build. Disable them until fixed.

If you intend to to submit a pull request, you must remove the -x checkStyleMain argument and fix the checkstyle errors before submitting a pull request.

Finally press the icon that looks like a play button and wait until you have a build success

If you are having issues see the Troubleshooting section.

Now, we need to tell IntelliJ to pick up changes based on Gradle build (it should do that automatically, but sometimes it doesnt). So, still in same Gradle window, just click the Refresh icon:

Running the project

Running the project is very simple, simply do the same as the build steps, but navigate to Tasks > openosrs > run instead, then set up this task like you would for build. Then you can run it, and OpenOSRS will open!

If you are having any issues with this step see the Troubleshooting section.

Conclusion

Success! You can switch between running and building the client by selecting the build configuration:

Finally if you intend to contribute to the project, check out the Code Conventions.

Advanced

RS Injection Assist

There is a custom IntelliJ plugin that aids navigating the runescape-client and runelite-mixins repository their imports & exports: https://plugins.jetbrains.com/plugin/14808-rs-injection-assist

Demo video

Troubleshooting

Missing git

If you are getting error about git.exe (or git on linux and mac) missing, you will need to first download and install Git for your OS. Git is version control software and implementation that OpenOSRS uses to store and track history of it's source code. To download git, just go here and select your OS version.

JDK Issues

If you are getting errors about missing or incorrect JDK versions, make sure to install JDK 11 (see the start of this page).

Then navigate to File > Settings > Build, Execution, Deployment > Build Tools > Gradle and ensure the Gradle JVM is set to Java 11 (or later):

Also navigate to File > Project Structure and ensure the Project SDK is set to Java 11 (or later):

Client failing to start

If the client fails to boot or if the applet does not appear, try to rebuild the project by running the Gradle builder again. If that doesn't work, try closing IntelliJ and re-opening it again and running RuneLite class again. If that also doesn't work, feel free to ask for helping the discord server. Here are few helpful tips:

Enable annotation processing

Open up settings and go to Build, Execution, Deployment -> Compiler -> Annotation Processors and then enable annotation processing

Update your fork

To sync your fork simply run

git fetch upstream
git merge upstream/master

or update the project from IntelliJ:

Skip gradle tests

This will skip the tests, which may

Typically your build will look like tasks: build Arguments: -x test

Happy development!

Check jre/lib/security/cacerts file

If you are getting otherwise unexplained errors with Gradle, especially after updating/replacing openJDK installation. I was getting obscure errors about being unable to read file stream of "checkstyle.xml". Ended being because the xml doctype pointed to "https://checkstyle.org/dtds/configuration_1_3.dtd" which was unreachable.

It was only after nuking my .gradle and .m2 folders and trying to build from scratch that I received a useful error message.

Exception in thread "main" javax.net.ssl.SSLException: java.lang.RuntimeException: Unexpected error: java.security.InvalidAlgorithmParameter
Exception: the trustAnchors parameter must be non-empty

I managed to fix the problem by copying the cacerts file from IntelliJ's default jre to openjdk-9/lib/security and overwriting the existing file.