How to contribute

Various development-related discussions
Post Reply
User avatar
Posts: 2
Joined: Sun Oct 29, 2023 9:33 pm
Has thanked: 2 times
Been thanked: 3 times

How to contribute

Post by ovenbread »

This is my definitive guide to contributing to 2009scape.

So you want to make 2009scape better, but you don't know where to start.
Fret not! This guide will give an overall idea of what to do :)

---------- WAYS TO CONTRIBUTE ----------

You could contribute to 2009scape by:
1. FILLING A BUG: File bugs With video sources. Be detailed, or it will be thrown out.
2. TESTING: Test new features to be added to 2009scape.
3. JSON EDITING / TEXT CORRECTION: You could change position/drops of mobs or fix dialogue if you see something out of place.
4. CODE IMPROVEMENTS: Re-write some parts of the code, convert Java to Kotlin and use ContentAPI.kt as the central dependency.
5. CODE FEATURES: Add new mob functionality, skill interactions, client interfaces, unimplemented features to 2009scape
6. QUEST WRITING: Add an entire unimplemented quest to 2009scape. Combines the above 3 points.

For 2.TESTING, we have a very detailed guide here: viewtopic.php?t=348-testing-a-cheatshee ... and-tricks

I recommend starting small from 1, then working your way up once you are familiar with the code to 5/6.
I assume that you have read and done README which contains the project setup and background.
Please note you may need to know quite a bit of coding from 3 onwards.
Also, try not to burn yourself out, go touch some grass once in a while.

Lets begin!


There are 3 sections below: SOURCES, NON-CODING, CODING

---------- SOURCES ----------

Before anything else, we should be clear about what SOURCES are.
TLDR: YouTube Videos in 2009.

We are trying to replicate 2009 Runescape - the lore, the gameplay, the feel of the game in 2009, so your contribution should reflect close to what happened during that time, making it authentic.
To do that, the only window into the past are, unfortunately, videos/clips of the game made in 2009.
Some of the more obscure features that no one uses are lost to time, so you will have to derive it, but be a last resort if you need to.
Otherwise, please do not contribute non-authentic code/"your own fancy ideas"/something you remembered from your great-grand-uncle, unless agreed upon or guarded by a flag.
Remember, others who are downloading the game want to experience Runescape in 2009, not some fancy fuckshit private server.

---------- WHAT IS A CLIENT ----------

Lets start with the game client. In the most ELI5 term, it is the game window you see that contains all of the "pictures" and "animations" stored locally on your PC. In website terms, this is your "front-end". Clients are versioned with build numbers like 530, which is like a "snapshot of a website's front-end at a point in time", in this case Jan 2009. This would be the limit of what you can control/show code-wise in that specific snapshot.

The two build numbers ( we are specifically targeting are:
530 (28 January 2009) Current Client version you are playing on.
578 (11 January 2010) Potentially what we want our Client to upgrade to after some quests are implemented.

So for example, if you wanted to implement Forgiveness of a Chaos Dwarf launched on 9 September 2009, you would have to wait till we upgraded our clients to 578, as our current clients 530 (28 January 2009) do not contain the "pictures" and "animations" of the Chaos Dwarf quests yet. This is important to know as quests implemented later, cannot be brought into the current game unless modifications to the client are made(which we do not do). Anything past 578 (11 January 2010), is considered inauthentic for this server.

---------- HOW DO I FIND VIDEOS ----------

With YouTube/Vimeo?, which 2009scape consider to be the most authentic, you would have to search for runescape during that time period.
The way I like to do it is like this in the search bar:
"runescape after:2008 before:2010 canoe" (canoe ride videos after 2008 and before 2010)
"rs after:2008 bkd" (black king dragon videos after 2008)
Mix and match to hopefully get videos you are looking for.
These will get you the most authentic video sources to the 2009 era. The worst the music/mic, the better.
Remember to copy these URLs down, so that you can paste it in your commits when you contribute.

---------- WHAT ARE DUMPS ----------

Another set of sources you could depend on is right in your 2009scape code.
There is a folder named "dumps" which are reversed engineered from Clients of a specific version (498/530/562).
As mentioned above, they are "cached" or stored in your PC so that they are easier to retrieve, rather than be fetched from a server every time when they are needed.
However, not all the information you need will be in the client. Quite a fair bit sits on the server, which Jigglyflex would obviously not reveal.

Clients contain stuff like:
- Interface names and button IDs
- NPC names, related animation
- Animations
- Music locations
- Object name configs/animations
- Varps/varbits (explained later)
Which you can easily search through that folder for.

Server contains stuff like:
- NPC Spawn points and locations
- NPC Drops percentages and tables
- Dialogues
- NPC Functionality
- Quest Functionality
Which are not what we have and should be implemented from video sources.

One exception here is the "scripts" folder you find in dumps.
The quick explaination here is some files containing code features are sent to the client to be ran locally.
These are written in Runescript and are denoted by the cs2 file extension. More info here:

---------- RUNESCAPE WIKI SOURCES ----------

So you can't find them sources? Well our fallback is unfortunately a set of wikis known to be the Runescape Wikis
These two are the first things you will see if searching for anything Runescape.
These wikis are unfortunately not authentic as they are a reflection of what the game is of TODAY rather than in 2009 and are written by random people who do not work for Jigglyflex, but with some derivation, you could extract quite a bit of information out of it.

---------- RUNESCAPE VERSION HISTORY ----------

Why are there two versions? Well here's a short history run-down that is VERY IMPORTANT to understand. There are two Runescape versions today:

A: Runescape (RS)
RS 1 : a.k.a. Classic
RS 2 : 29 March 2004 - 25 June 2013 <-- Our 530 client falls into here.
EOC: 20 November 2012 (Evolution of Combat: where they proceeded to fuck health numbers up)
RS 3 : 22 July 2013 - TODAY

B: Old School Runescape (OSRS)
OSRS 10 August 2007 : Rerelased 22 February 2013 - TODAY (because people miss old school shit)

Both RS and OSRS have diverged from 2009 in terms of content. RS has stuff like minigames, Anachronia and yada while OSRS has stuff like Great Kourend and Forestry just to name a few.

If you were to turn back time on the not OSRS) by clicking on History at the top right, you could get information closest to 2009 e.g. for the canoe stuff, find the line closest to 11 January 2010
02:30, 10 January 2010‎ XX.XX.XX.XX talk‎ 3,284 bytes +32‎ →‎How to make canoes undo | report

Unfortunately, most of the info during that time were rather sparse. This is where you can start widening your search timeframe like 2007 - 2012.
After countless videos, I've come to the realization that the Runescape devs later were pretty lazy (I am too).
Not much would change after a certain thing has been implemented, so for example Canoes currently in Runescape 3 are EXACTLY the same as what they were in 2009.
That's where you can start looking for videos before/after 2009/2010 with cautious cross-referencing.
In addition to that, you could also use OSRS to see if things had change between it and RS. Canoes were present in 2007, and nothing has changed through the years, so why would they?
Not everything follows this logic though, which is why I stress on searching very hard for 2009 Runescape videos.

---------- OTHER SOURCES ----------

Alright now that you know the distinction between RS and RS3 (abbreviation from now on), here are some more sources that I generally use for things:

For NPC positions/Ground item spawns:
(RS3 2018)
(OSRS 2018)
You can lookup NPC names at the bottom left, but you have to be EXACT with the name (e.g. "Giant bat" not "Giant Bat").
You don't have to be super exact with the positions, and definitely not the facing either because most of them walk around anyway.
Those that do not walk, you would usually derive the direction they face from videos.
Also note: this is a snapshot from 2018. Obviously some positions have changed over time. You will have to guess.

For Drop tables:
There are more sites, but I'm shit at drop tables. More elaboration here when someone explains it in details to me.

For Dialogues, NPC values, NPC functionality:
This is video heavy, but since most people do not care about other dialogue branches other than the main one just to get the quest done, some derivation is needed from the wikis. Both wikis take dialogue snapshots from 2016/2018, so do mind that they may not be exactly the same.
I love the for dialogues as this dude clicks on EVERYTHING just to get some semblance of a dialogue out of them. Do note unfortunately this is in 2014 and some things have changed.

For everything else:
There are more Wikis you could find too: - this Fandom wiki has info similar to runescape wiki. - This has drop tables and some sparse data. - You can find lots of obscure shit here like rare scenery animation ids and varbits. (THIS WAS USEFUL)
Videos - Cannot stress this enough. Videos are king, search harder.
The forums/chatrooms - Lots of people you could ask, but please do not harass with dumbass questions.
The live RS/OSRS game - Sometimes, you just gotta see what they actually did in game.

At this point, you should have a surface level understanding of what 2009scape is, how it works and where to get sources.

---------- NON-CODING ----------

You suddenly found that while playing 2009scape, that something is pretty off.
You want to correct it, but that shit is hard to find, what do you do?

Well if you do not have any coding experience, fret not. You can still contribute by:
- Filling a bug with a YouTube source to us and explain why it is not authentic.
- Filling a bug with transcribe dialogue for a quest, npc, anything as long as with a YouTube source.
- Use Zaros Tool(Thanos Tool originally) but you need to know how to use Git.

Note that I didn't say come onto Discord or the Forums and complain? Yeah, don't do that.

Do not harass developers to do work for you. We aren't fucking paid to do any god damn shit for you. Ask nicely and accept NO as an answer.


In order to use Zaros(Thanos' new name), you need to learn Git.
This is because you will need to pull both: (the server) (the tool)
and check in your changes.

More on how to use Zaros in the wiki, but I'll explain it here next time.

---------- CODING ----------

Welcome to the coding section!
You must know how to write Java & Kotlin. Otherwise, Google/Bing/Duckduckgo is your friend.
We are trying to make the switch to run fully on Kotlin so, absolutely no more Java should have to be written.
However, there are still cases in which you may need to touch legacy code, which is why Java is still necessary.
It's not easy, but hey you wanted to code right?
I do assure you that once you get some programming concepts down, there isn't much you have to think about.
If you are confident coding, it would make the following parts much easier to understand.


As mentioned before, the codebase of 2009scape (or literally any other open-sourced project) isn't perfect.
Short history, this code was inherited from another project and many of the initial implementation are sometimes diarrhea inducing.
That's where you come in. To un-fuck stuff.
To give credit where it's due, that project kickstarted this. So some kudos is warranted.


The first thing I want to explain is the overall architecture.

There are 3 folders you would generally care about as a content dev. If you do touch on architecture, every file is fair play then.
- 2009scape/Server/data/configs (Contains your jsons that inserts nps/drops/shops)
- 2009scape/Server/src/main/content (Implmentation for all npcs, quests, items, travel)
- 2009scape/Server/src/main/core (Implementation for core features, skills, health, packets, ge, and most importantly ContentAPI.kt)
I would recommend implementing small pieces of content before attempting to modify architecture, just so that you can learn the ropes before waterboarding yourself with code.

The entire Server runs on an event based system. If a player clicks on something, that's an event. If he shits himself in game, that's also an event.
You write functions listening to those events via Plugins/Listeners.

The old style, uses Plugin classes.
Uses Java Annotations @Initializable for a class to be picked up and you have to register OptionHandler and the likes to it.
See 2009scape/Server/src/main/content/global/handlers/item/

The new style, that we are trying to move to are called Listener classes (InteractionListener, InterfaceListener).
They are generally much less verbose to implement without the need for initialization and require only one function override call on defineListeners.
They OVERRIDE Plugin implementation. So be careful what functionality you override. (Ladders and staircases are quite common.)
See 2009scape/Server/src/main/content/global/handlers/item/ToyHorseyListener.kt

We recommend writing Listeners (e.g. somethingListeners.kt) EXCEPT for the following classes
- Quest Plugins (class SomeQuest : Quest(...))
- - 2009scape/Server/src/main/content/region/asgarnia/burthorpe/quest/deathplateau/DeathPlateau.kt
- NPC Dialogue Plugins (class SomeDialogue(player: Player? = null) : DialoguePlugin(player)
- - 2009scape/Server/src/main/content/region/asgarnia/burthorpe/dialogue/BernaldDialogue.kt
As these will be batch converted in the near future. They still are written in kotlin though.

As long as you have a class extending Listeners, or a class extending Plugins that has the @Initializable annotation to it, it will be picked up by the framework.


A simpler way would be to follow how recent commits do things. They give off clues on how to write, organize and implement functionality in 2009scape.
Here's some of mine:
Data Edits(via Zaros) + Dialogue: ... 1317/diffs
Convert java to kt: ... 1219/diffs
Interfaces: ... uests/1214
Quest writing: ... uests/1627

Basically follow patterns that others have done through their MRs.


The next thing I want to explain are Varp/Varbit/Varc


But for you lazy fucks: here is a quick rundown

Parts of the visual control of the world runs off a set of flags/states known as Varbits.
The client for the player would show/hide npcs/scenery/quests in the world according to those Varbits.
Varbits are sub-groupings of Varps. Varbits can be more than 1 bit long (allows for storing 0,1,2,3,4...).

e.g. Player pours shit into a fountain in Runescape.
Varbit 1234 will be set to:
0 if the fountain has clear water
1 if the fountain has shit water
2 if the fountain cracked after you smash the shit out of it
3 if the fountain is no longer there because the quest person removed it out of the stench
So on. They are just states of the world usually for a single player.
Some sceneries/npcs change automagically for you once you set a bit like that, which makes it all the more useful.
Also since this is for one player, only that player sees it as brown water. All other players sees it as clear water.

Varbit - VARiable BITs (1-32 bits in length)
Varp - VARiables for Players (Always 32 bits)
Varc - VARiables for Clients
We care about Varbits and Varps and less so about Varcs which are too obscure for now.

Here is an attempt on how Varps and Varbits relate to each other

Code: Select all

* Varp (32 bits)
* ...         Varbit 5033 (2 bit variable in Varp 1271 offset from bit 7 to 9)
*             |-|
* 1271 00000000 00000000 00000000 00000000
* ...
* 1306 00000000 00000000 00000000 00000000
* ...
Rarely are varbits not defined. If it is the case, you would want to use varps as the last resort.


A useful thing to do in order to find out what values to use are In-Game Commands.
For example, you can use in-game admin commands locally to view varbit effects by typing these into the chatbox in-game.

::define_varbit 5033
-->5033 ConfigFileDefinition [id=5033, configId=1271, bitShift=7, bitSize=9] <-bitSize mistake, it is bitEnd non inclusive

::setvarbit 5033 1
(hides npc 7972 and shows 7973, change value to 0,1,2,3 for different results)

::setvarp 1271 7 1
(does exactly the same as setvarbit but bitshifts 1 by 7)

::setQuestStage 41 0
(Quest 41 - Creatures of Fenkenstrain set to stage 0)

(view all quests available)

::npc 7972
(spawn npc on your location)

(get your current coordinates x,y,z)

and a lot more which you can see in


Along with varbits that saves player states that I've explained above, there are playerAttributes which are essentially data you want to store with the player.
Long story short, you can save whatever type of data for a player just by calling setPlayerAttribute(...) and getPlayerAttribute(...)
if you set the string with "/save:" in front, the data persists even if you log out and log back in.
This is VERY useful for quests.


Finding this varbit number, that animation id, this quest config, that dialogue, this npc...

This is where the data mining starts.
Refer to the folder named "dumps", see all the sources I've mentioned above, or as a last resort shoot out a friendly request to people in chat.
Most of them have tools to help you out.
I wrote a tool to help you copy paste the basic OSRS/RS3 dialogue from the wikis to split out kotlin code.
Others have written Quest config finders, grep varbits, decompiled cs2 and all the other wonderful stuff.
Ask. Nicely. Lots of it you can find in the forums already. We are fine explaining it again if you aren't a dick about it.


One last thing I want to mention is core.api.ContentAPI.kt
You should use this as much as you can.
The general idea here is to centralize and abstract all content implementation from the underlying engine that runs it.
As a content implementer, I do not want to care about how the engine runs so long as I can call functions like
- hasLevelStat(player, Skill.THIEVING, 20)
- inInventory(player, Items.COINS_995, 10)
- sendMessage(Player, "sup")

Either way, new MRs should depend on the ContentAPI as much as possible.

If you see things like
chances are, you probably can replace it with a ContentAPI equivalent version.

Do that.

Feel free to improve ContentAPI, but with caution that it will be heavily scrutinized as many developers depend on it.


Quest Writing

Since this was the original intent of this doc, I'll show you my workflow that you could follow.

1. Find video sources in 2009 to understand the quest. Lay out the general stages a quest would go through.
2. Get the quest log (you can sometimes see it in the wiki, you can rarely see it in videos unless the person was diligent about it, derive)
3. Fill up NPCs/Drops via 2009scape/Server/data/configs using Zaros (you may find npcs missing in game)
4. Get the general success path transcript of NPCs (later with branches) (you can get it from the wiki, but some contributors already submitted transcripts from videos)
5. Implement the chat of each NPC involved with the quest. Doesn't have to be perfect.
6. Implement the general boss fights of main NPCs. This is usually the fun part of quests, but one of the hardest.
7. Implement item listeners of the quest (keys to doors, buying from shop, unique drops).
8. Be able to complete from start to end the quest that you've implemented. Implement the Quest Complete screen.
9. Polish time!
10. Implement all edge cases of NPC chats (this is super difficult as most videos in 2009 do not remotely give a shit about the story)
11. Implement all the edge cases of item listeners and quest stages
12. Implement cutscenes! They aren't difficult, but tedious (and I tend to skip this).
13. Fix all odds and ends (NPC features, drop tables, npc positions)
14. Submit and wait for testing. Double check with your sources.

15. Draw the rest of the fucking owl.

This requires a lot of context. So don't look to writing quests unless you've done little parts here and there first.
This can be quite a burnout, so please please please take breaks or complete smaller tasks first.


In closing, though I sound rather strict with what I've said above, I rather you would have learn a thing or two than absolutely nothing at all, by trying.
Sending MRs would get you to learn the ropes from others who are willing to help you out, but you have to put in that effort too. Everyone is contributing voluntarily.
Be open minded about criticism. Some of us are blunt, but have hung about for many years and are already allergic to all kinds of bullshit from the public.

I do have to say, it has been pretty rewarding contributing to an open source version of the game that was once part of my childhood.

Go fucking enjoy 2009scape.

- Ovenbread
Last edited by ovenbread on Wed Jan 03, 2024 10:52 pm, edited 3 times in total.
User avatar
Site Admin
Posts: 573
Joined: Wed Aug 10, 2022 11:48 pm
Location: Draynor Village
Has thanked: 81 times
Been thanked: 93 times

Re: How to contribute

Post by Ceikry »

"Note that I didn't say come onto Discord or the Forums and complain? Yeah, don't do that.

Do not harass developers to do work for you. We aren't fucking paid to do any god damn shit for you. Ask nicely and accept NO as an answer."

What an absolute godking
You dropped your crown m'lord
User avatar
Tech Support
Posts: 40
Joined: Thu Aug 11, 2022 11:43 pm
Location: Snow Mexico
Been thanked: 4 times

Re: How to contribute

Post by bushtail »

banger of a post - only thing missing is the fact that you can also contribute to 2009scape by testing new written content :)
Resident chad Winblows user
User avatar
Posts: 2
Joined: Sun Oct 29, 2023 9:33 pm
Has thanked: 2 times
Been thanked: 3 times

Re: How to contribute

Post by ovenbread »

Oh yeah! Forgot to put that in. I'mma link Chimkin's post
User avatar
Tech Support
Posts: 40
Joined: Thu Aug 11, 2022 11:43 pm
Location: Snow Mexico
Been thanked: 4 times

Re: How to contribute

Post by bushtail »

ovenbread wrote: Thu Nov 16, 2023 11:13 pm Oh yeah! Forgot to put that in. I'mma link Chimkin's post
good idea!
Resident chad Winblows user
User avatar
Posts: 478
Joined: Thu Aug 11, 2022 12:25 am
Location: ɐᴉlɐɹʇsn∀
Has thanked: 35 times
Been thanked: 93 times

Re: How to contribute

Post by ryannathans »

another way to contribute: testing!
User avatar
Tech Support
Posts: 40
Joined: Thu Aug 11, 2022 11:43 pm
Location: Snow Mexico
Been thanked: 4 times

Re: How to contribute

Post by bushtail »

ryannathans wrote: Fri Nov 17, 2023 1:03 am another way to contribute: testing!
bout a week too late for that mate
Resident chad Winblows user
User avatar
Posts: 478
Joined: Thu Aug 11, 2022 12:25 am
Location: ɐᴉlɐɹʇsn∀
Has thanked: 35 times
Been thanked: 93 times

Re: How to contribute

Post by ryannathans »

bushtail wrote: Fri Nov 24, 2023 1:49 am
ryannathans wrote: Fri Nov 17, 2023 1:03 am another way to contribute: testing!
bout a week too late for that mate
I think you are the one a week late.
Post Reply