Resource icon

Setting up a Pokered or Pokecrystal disassembly with Cygwin and GitHub Desktop

Pokémon Essentials Version
What is Pokered/Pokecrystal?
They are disassembly of Pokémon Red and Pokémon Crystal. "What are disassemblies?", you might ask. Well, to make it sound simple, think of a game as a box, usually a file with a .GB or .GBC extension, right? Well, modifying the disassembly would be opening the box so that you may edit its contents. A group of people decided to "unbox" those games, so that they can be edited, then "assembled" back into a working box (rom).

Why should I want to use any of those?
They are compatible with emulators, for instance. They are much harder to use for everyday stuff compared to Pokémon Essentials, that's for sure.

Other important disassembly projects (not covered in this tutorial)


What do I need?
I'm assuming you are running Windows, for which this tutorial was written. Download the following, but don't install them just yet.
Cygwin (x32) (x64)
rbgds (x86) (x64)
GitHub Desktop

Step 1: Installing Cygwin
Run your cygwin installer. Next.


Customize "Root Directory" and whether you want Cygwin to be installed for all users. Next.

This field doesn't matter. You can just click Next. If a pop-up says it doesn't exist and whether the folder should be created, say Yes.

Next. You'll see a list of links. Just click Next, leaving whatever was the default.

An initial download will begin.

Okay, this is where it gets a little complicated:
These are "packages", and we'll need 3: make, git, and gcc-core. Yopu can use the search bar to search for those names, and you can click the + and - buttons to open those dropdown menus, but this is where those packages will be found:


Click the "Skip" text in order to shuffle between package versions, until you get to 4.2.1-2.


Try to get to version 2.17.0-1.


Hit next once you've found all three and clicked to get the right versions.


The download of all of our packages will begin. This will take a while. After that, choose whether you want a Desktop icon and so on, and click Next. We're done with Cygwin!
Step 2: Installing rgbds
Remember the folder you specified early on? the "c:/anything" one? Scroll above if you don't. Well, let's travel there. By default, the folder we need to browse should look like "C:\anything\usr\local\bin". Once you've found it, copy the contents of the rgbds.rar file we downloaded earlier, and paste them into this folder.

(Optional) Step 3: Forking a repository
What is "forking"? There's username/repository, such as pret/pokered. Well, you can make a copy of pokered that would look like gela/pokered and then, you can use GitHub Desktop (Step 4) or any similar client to upload your changes (commits) so that they can be saved there, much like Dropbox. The other advantage to using commits like this is that commits (changes you push online) can be rolled back very very easily. This means, if you screw up really badly, you can just go back to the last time everything was working fine.

Go to the link of the repository you wish to make a hack of (pokered, pokecrystal,...) and click Fork.
You might need to make a GitHub account. Do so.

After a short while, you'll be on (your username)/pokered (in the case of forking pokered). Now find the big green button that says Clone.

Copy that URL!
Now, open Cygwin. You'll see a box like this.

Hacker voice: "I'm in."
To finally clone the repository we just forked, type this into Cygwin:
"git clone (paste the URL here)"
For example:
"git clone"
Cygwin will begin to download it. Marvelous! If your fork is named "pokered", then it will be installed under "C:\anything\home\Your User Name\pokered". You can browse that folder to find the entire repository there! Sweet. Want to test it? In Cygwin, type "cd pokered" where "pokered" is just the name of the folder we want to open. Now type "make". After a while, it'll be done, and you'd find "" in your pokered folder. That's your rom! You can go ahead and test it. Yes, the command "make" is what "builds" the box again, generating a new rom file with whatever code changes you've made. Test your rom. I always have a VBA shortcut around and I tend to paste it into these folders, for ease of use.

(Optional) Step 4: GitHub Desktop

Install GitHub Desktop and log in. Now click File>Add local repository on the topleft, or press CTRL+O. Now browse your folder and click okay. You're almost done. Just let me roughly explain commits.

See, I've made a change to a file, just painted some random lines on paint, don't actually ever do that.

GitHub has detected that I've changed that file. If I right click the file on that left column this will drop down:

Now, if I want to revert this individual change, I can just click Discard changes or Discard all changes. GitHub Desktop works in such a way that it will make a local backup of your project, so that if you discard a change, it will grab the backed up files to restore them. Pretty neat, huh? If I changed more files, I'd see more listed there, and I'd see the differences on the right side.

So, what about commits?

You can give a name and a description to your commit, which will be very helpful when looking back to fix something, or just to describe what you did at a certain point in time. After clicking "Commit to master", you can "push" the commit from your computer to your GitHub fork.

Now, if I go to my GitHub fork, I'll see my change has been saved there as well:

Now, if when playtesting I find out I've really screwed something up, there's no need to worry. Go to GitHub Desktop, then click View>History.

Now you can just revert the commit and be back where you started!

GitHub Desktop, cygwin and such have more tricks you (and I) can master, but these are what I consider the basics.

I'm going to call these "templates" because they are a good starting point to start making a pokered, pokecrystal, etc, hack, without having to worry about porting more or less "essential" mechanics into them. If you use any of them, remember to check for credits.

pokered-gbc: A pokered project with complete GBC support, meaning full colour overworld, among other things.
pokered-gen-ii: A pokered project with GBC graphics, including experience bars. A similar version of pokeyellow exists.
redstarbluestar: A pokered project using Spaceworld graphics and features.
pokecrystal-optimization: pokecrystal but with more free space, as some (unused) features have been removed, such as Japanese GBC-to-mobile phone support.
None required.
Keep in mind in the disassembly community it's usually alright to grab code from someone's repository, but never omit crediting said individual or individuals and do ask if in doubt. Most of the code from pokered and pokecrystal hacks, such as Polished Crystal are open source (correct me if I'm wrong), but don't claim anything as your own. You're also free to contribute to those projects too. Do you know how to fix a certain bug? Perhaps you think a bit of code could use some documentation on how it works, so people can understand it in the future?
Mr. Gela
First release
Last update
5.00 star(s) 1 ratings

More resources from Mr. Gela

Latest reviews

Clean and professional, very easy to follow and execute every step. Everything you need to have and need to know is in this tutorial.
I wish there were more tutorials like this.