For a while now, I have been casually working with the RuneLite project. Mostly I write plugins for extracting or gathering data from Old School RuneScape (OSRS). Some examples are extracting item information, dumping information about other players equipment, and extracting NPC world location information. If you have read any of my other blog posts, you have probably noticed how much I like gathering and analyzing data!
Along the way I have done lots of part-time researching, reading and gaining knowledge about Java. I had never really programmed in Java or had much experience with general best practices, project structure, and building projects. I just went headfirst trying RuneLite development using the IntelliJ IDE, because that’s what the RuneLite Wiki suggested. This has worked fine for a long time, but I have just moved city, am traveling and living out of a suitcase. This means that I no longer have a powerful Desktop computer… so I have been starting to change my development workflow. Enter a new need: how to easily compile RuneLite and have access to my compiled version on my very-minimum-specs laptop. This post outlines how I compile and run the RuneLite client development version using Maven (the mvn
command specifically) and run the client from the terminal.
I set up my new development environment on a laptop installed with Ubuntu 18.04.2. However, you can probably follow this tutorial on other Linux-based operating systems, and the instructions should be highly similar. I have never done a similar setup on a Windows-based machine or OS X, so there is no information covering these systems in this tutorial.
We are going to start with the usual updating of the database of apt
packages:
Lucky for us… in this setup we can use software versions that are available directly using apt
. Run the following command to install the openjdk-8-jdk
package as it is the recommended Java version to build RuneLite, the maven
package used to build RuneLite, as well as the git
package to download the RuneLite source code.
It is important to check that Java is installed correctly and that you are using the correct version when executing the java
command. First, check the Java versions that are installed on your system by running: sudo update-java-alternatives -l
. My output is provided below as a reference:
As you can see I have two Java versions (JDK) installed. Java version 11 and Java version 8. You might only see java-1.8.0-openjdk-amd64
. If you have two versions like me, you can use sudo update-java-alternatives -s java-1.8.0-openjdk-amd64
to make sure Java version 8 is used by default. When ready, it is preferable to check the version used when running the java
command by executing java -version
. Example output is provided below:
Now that we have Java ready we can download the RuneLite source code and compile the client. You should have git
installed, as we did this in the previous step. Clone the RuneLite client repository using the following command:
To compile the project we can use the Maven command-line tool or the mvn
command. I had never really used Maven before, but I knew there must be some command-line tool for managing/building a Maven project. If you are new to Maven, I found the official Apache Maven in 5 Minutes tutorial to be brief, yet sufficient documentation to get an idea of how to use it. You can use the mvn
command to execute different Maven lifecycles such as compile
, test
, and install
. These are the same lifecycles available in IntelliJ when building RuneLite.
To compile the RuneLite project, and the client, start by making sure you are in the freshly downloaded RuneLite repository. Then run the following mvn
command:
As a quick summary:
mvn
: Is the Maven command-line toolinstall
is the lifecycle option which automatically compiles the source code and packages it into a JAR file-Dskiptests
: As it sounds, skip the unit tests to speed up the build time.So what does this do?! It compiles the entire RuneLite project and creates a JAR so we can run the client. Since we are running this in the root project directory, it will build the entire project - not just the client. Maven even tells you this when you run the command above:
My usual workflow is to just build the entire project. You could also be specific and only build the client if you are continually making changes and don’t want to compile and package the entire project. To achieve this, just change into the runelite-client
directory and run the same command: mvn install -DskipTests
. You can also add a -o
to use the libraries from the local repository (on your system) instead of re-downloading them again.
This build method is excellent as it is fast! A very informal test on my laptop for building the entire project:
mvn
: 15 secondsThese tests were performed using the same build method: install -DskipTests
and I took a guestimated average from multiple builds, and always made sure I built the project once before testing. My laptop struggles to run the IntelliJ IDE efficiently, it sounds like my laptop is a rocket trying to launch to Mars. Even on my old desktop, it was slow at loading on startup, and slow compiling the project. In comparison, the mvn
command is fast and generally seems less resource heavy. So far, it has been working well when developing on my new minimal-specs set up.
Now that we have compiled and packaged the client, we want to run it! I mean, that was the entire point. You can find the JAR file for the RuneLite client in the runelite/runelite-client/target
folder. This is similar to the other projects in the root runelite
folder, each will have a target
sub-folder with the compiled JAR file.
The client has two different versions that are compiled and packaged into JAR files, both called client-<version-number>
and one with a suffix of shaded
. I had no idea why this version was such a big file size, and why it was called shaded
. After reading the pom.xml
file for the client, I realized the maven-shade-plugin
is used to create an uber-jar file with all dependencies included in the single file, which has the shaded
suffix. So there are two options: run the non-shaded JAR and include all the dependency JAR files, or run the single, shaded JAR file. The second seems much simpler, and saves us from entering in a large number of dependencies in the classpath.
Unfortunately, the command needed is not the simple java -jar RuneLite.jar
command that can be used to run the installed RuneLite with the launcher. This is because the launcher takes care of many details behind-the-scenes. To run the client, we will need to specify a collection of important arguments. The full command I use is:
As a quick summary:
java
: Run the client using Java-ea
: Enable assertions-cp net.runelite.client.RuneLite
: Set the classpath to specify where the main
method for the JAR file is loctaed-jar client-1.5.30-SNAPSHOT-shaded.jar
: Specify the JAR file to run, and use the shaded JAR file (you will need to change the version number to match the updated client)--debug
: Turn on debugging messages, which is optional but useful--developer-mode
: Turn on developer tools, which is optional but usefulThis command is a bit of a nightmare to run, so I like to create a command alias to get this done. You can put the following code in your ~/.bash_aliases
or ~/.bashrc
file to start the client using an easier method:
With this command, you set the file path for the compiled RuneLite client version, then create an alias named runelite-dev
to start the client. I find this a nice method, but there are probably other options available.
When I read a tutorial, I like multiple examples. I find them useful. So I thought I would include an example of how to run the RuneLite Cache tool after compiling the RuneLite project using the mvn
command.
The cache tool does not have the same shaded
version. Instead, there is a JAR file that has the jar-with-dependencies
suffix. This tool can be run using a very similar method to what we did for the client. The command I use has been listed below for reference:
As a quick summary:
java
: Run the cache tool using Java-cp cache-1.5.30-SNAPSHOT-jar-with-dependencies.jar net.runelite.cache.Cache
: Set the classpath and JAR file-cache ~/jagexcache/oldschool/LIVE
: Tell the cache tool where the cache is-items ~/items-json
: Dump the Item Definitions into the ~/items-json
folderThis command will run the Cache tool and dump all the Item Definition data to a folder. Then you can review the item information that is extracted directly from the game cache and stored in JSON files.
I hope you have made it this far and got an idea about how to compile RuneLite using Maven and get away from that resource-hungry IntelliJ IDE… jokes! I quite like the IntelliJ IDE, and find the syntax highlighting and other built-in features nice for helping development - expecially for a Java noob like me. But I have never been an IDE fan. Some of this tutorial may be simple if you are a Java/Maven expert, but for me, it was a learning curve and something that I could not find documented elsewhere specifically for RuneLite. So I really hope it is helpful.
If you have any questions, feedback or discovered any issues with this documentation please leave a comment below. I am happy to help if I can. And as usual, happy scaping everyone.