Found something wrong? Edit on GitHub!

RuneLite OSRS Cache dumping

Tutorial on dumping cache information with RuneLite

By Loading...

On this tutorial we are going over on how to dump all kinds of information from the OSRS cache with the help of RuneLite cache tools plus, for our purpose here, my modified version of them.

Downloads and resources summary

While not strictly required, java knowledge is useful, especially on how the whole java development works. You don’t need to know how to code in Java, but knowing how to compile a .jar file and what’s needed for that may be helpful.

The first thing you will need to follow this tutorial is to install IntelliJ IDEA or some other kind of Java IDE. For this tutorial I’m going to assume you are using IntelliJ IDEA which you can get from here, it will also make it following this tutorial easier:

Once you have it installed, you now need to download RuneLite source code, specifically, my fork of it if what you want to do is dumping data for Simba:

You can download it however you like, git, as a zip and unzip it, even use IntelliJ Idea if you know how. Anyway, just have a “RuneLite” folder somewhere in your computer with all the contents of that repository inside.

Now before going forward, let’s compile RuneLite and launch it to be sure everything so far is good.

For this, I’m going to do something a bit odd. I’m going to tell you to follow the official RuneLite tutorial on it which you can find here:

  • Building RuneLite There’s a good reason I’m linking you the official tutorial, things may change overtime and it will probably be more up to date than whatever I write here. The only difference from their tutorial for this tutorial is that you will be using my fork instead.

In any case, once you are done with that tutorial, you should have compiled and ran RuneLite with IntelliJ IDEA.

ItemFinder

The first thing you will notice from my fork that is different from the official RuneLite is that once you run it, it will start dumping itemfinder assets: img0 If you go to the folder mentioned on the IntelliJ IDEA console, you will find the files for itemfinder.

As far as itemfinder is concerned, to update it all you have to do is running RuneLite like this and then run the generator file in SRL-T to build the hashes file.

Data dumping

Now we are going to get into other kind of dumps. First you will want to visit OpenRS2Archive caches page.

OpenRS2Archive is a very interesting project, one that is used by the RuneScape developer community as a caches archive.

You can get the game cache from your computer, but the XTEA keys which to put it simply, are keys that decrypt the cache can normally only be obtained from Jagex servers.

The way it works is that when you walk into a region in game, you receive a key for that chunk (basically when you see the map loading for example) that will unlock the information needed for that chunk on your cache.

So in other words, to unlock the entire game cache, you would have to walk through every region in the game to get all keys, which makes it not feasible, especially considering that the keys update with the weekly game updates.

However! Thanks to the awesomeness of RuneLite, this process is automated and crowdsourced to every RuneLite user and the result of that is uploaded in OpenRS2Archive 😁

Even thanks to RuneLite it’s rare that a cache gets unlocked to 100% but we get 93+% unlock very often and for our use case that’s really good enough.

Anyway! On the OpenRS2Archive Caches page, you will see they also host RS3 caches and some other game versions, so first we are going to filter them for what we want:

  • Game: oldschool
  • Env: live
  • Lang: en And then sort them by timestamp to find the oldest.

On the keys column you can see the percentage of unlocked cache available, anything above 93% should be fine. If you find a pink square on your dumped map later, that’s due to the missing keys. If you really need that maybe try an older cache and see if that works for you. Do keep in mind that older caches may have the most recent stuff missing.

Anyway, click the download button and you will want to download both:

  • Cache (.dat2/.idx)
  • Keys (json) If the keys open on a tab on your browser instead of downloading the file like they do to me, simply right click the page and Save as... and save the page as .json.

Now you are going to want to create the following folders somewhere on your computer:

├─ cache/
│  ├─ input/
│  ├─ output/

This is exclusive to my fork of RuneLite, but I like to have things organized and the way I made things is that it will take stuff from the input folder and place the dumped things into output.

Now you will want to extract you cache .zip into the input directory. Then, on the newly created folder you want to put your .json file inside. The currently latest cache is cache-oldschool-live-en-b222-2024-06-05-11-15-05-openrs2#1819. I usually leave things named as is to not waste much time but going forward I’ll refer to this cache as only openrs2#1819 so it’s not so large. So your file tree should look like this:

├─ cache/
│  ├─ input/
│  │  ├─ cache-openrs2#1819/
│  │  │  ├─ cache/
│  │  │  │  ├─ main_file_cache.dat2
│  │  │  │  ├─ main_file_cache.idx0
│  │  │  │  ├─ ...
│  │  │  │  ├─ ...
│  │  │  │  ├─ ...
│  │  │  │  ├─ main_file_cache.idx255
│  │  │  ├─ keys-openrs2#1819.json
│  ├─ output/

Every time you want to update your dumps you don’t have to delete the old folders if you don’t want to. You can just unzip it to the input folder, put the .json file inside of the new cache folder and have it organized like above. When you dump, in this case, a new folder in output will be created with the name cache-openrs2#1819 and everything related to that dump will be placed there.

Now, let’s go back to IntelliJ IDEA.

On the left-side panel, you have your project tree, open the following:

  • cache > src > main > java > net.runelite.cache This is where all the cache classes are. If you scroll down a little you will see right away that some are named with Simba. Simba classes This are the ones I used, modified by me for our purposes.

You can use them individually, the way you use them is exactly the same, but for simplicity sake, on this tutorial we are going to use the unified dump class SimbaCacheDumper.

SimbaCacheDumper doesn’t do everything, but it uses:

  • SimbaMapImageDumper which dumps maps
  • SimbaHeightmapDumper which dumps heightmaps
  • SimbaCollisionMapDumper which dumps collision maps
  • SimbaObjectInfoDumper which dumps object information

One thing to keep in mind is that this does take some time, especially the unified dumper, but for modern hardware shouldn’t take more than 5 minutes. If you are taking more than 5 minutes, consider updating your hardware 😉

Anyway first, I’ll explain how to see what kind of arguments you can and should use with this so open the file and search for the main function:

public static void main(String[] args) throws IOException
{
	Options options = new Options();
    options.addOption(
		Option.builder("p").longOpt("path").hasArg().required().build()
    );
	options.addOption(
		Option.builder("c").longOpt("cache").hasArg().required().build()
	);
	options.addOption(
		Option.builder("o").longOpt("output").hasArg().required().build()
	);

  //...
  //...
  //...
}

I’ve formatted this slightly different so it’s easier to see but usually you can see the arguments the class takes in the main function and they are usually self explanatory.

All my Simba classes take the exact same arguments everytime:

  • path
  • cache
  • output

If you want to use the built-in RuneLite cache tools you will have to go see which arguments they take and figure out how to use them yourself but after this tutorial you should already have enough insight for that.

Anyway, on the top right side of IntelliJ IDEA, go to Edit configurations...: Edit configurations...

Click the + sign and then Application: Add configuration

Now you have to fill in these fields:

  • Name: whatever you want, but something that makes sense is good
  • -cp: cache which should auto-fill java 11 on the left, if not select it.
  • Main class: net.runelite.cache.SimbaCacheDumper, you may click the small icon on the right if you prefer to select it from a list instead of writing.

And lastly, the arguments which is what we were looking at earlier:

-cachedir
"C:path\toyourcacheinput"
-cachename
"cache-openrs2#1819"
-outputdir
"C:path\toyourcacheoutput"

And finally click Ok.

Now on the configurations drop down, select your newly created configuration and click the green play arrow and let it run.

This will take some time, depends on your hardware really but expect it to take 3/4 minutes at least. maps.zip and collision.zip are by far the slowest.

It will tell you about it’s progress on the IntelliJ IDEA console. When it’s finished you will see:

Process finished with exit code 0

Now if you go to your output folder you will see a new folder there with the cache name, open it and you should have 4 .zip files in there: ![zipped files](https://db.waspscripts.com/storage/v…