Tutorial to the Pokecrystal Disassembly

I’ve started working with the Pokecrystal Disassembly, a complete disassembly of the classic Pokemon Crystal, one of my all time favorite games. This disassembly gives anybody the opportunity to edit the game however they please, it is however quite hard to understand, and there’s a big lack of tutorials.

I’m hoping to fix that lack of tutorials by writing this as I learn it myself. I’m a complete beginner, so this is most likely going to go trough every dumb small mistake and even the smallest questions.

2. Editing Maps

Editing and adding maps is thankfully one of the easiest jobs to do thanks to tools developed by the community, however it might still be kind of tricky, so I’m going to try to explain everything.

1. Add Maps

Assuming that you already have your Cygwin set up and the disassembly downloaded, adding maps should be fairly easy. In this we will be adding a new area connected to New Bark Town, so that it will be easier for you to test out.


Let’s start it off simple enough by setting up Crowdmap, this neat little program will give you a visual of your maps without having to build the game every time, it will also help you add new maps and edit them. You can find the download here, drop the crowdmap folder into your pokecrystal directory, it should look something like this pokecrystal/crowdmap/. The instructions to start Crowdmap are fairly simple and are explained dirctly in the github page.

Once set up, you should be able the fairly simple to use interface. Let’s click on + New Map to add a new map. I’m going to set the name to Route101, you can use whatever you want. The map group is going to define how your map is ordered with the others, I set Mapgroup24, since it’s the one where New Bark Town already is.

This will automatically add the lines I explain how to add next, so when following those steps, make sure not to add any additional lines, but edit the already existing one instead. CTRL+F should find your newly added map fairly easily.


There are a few .ASM files that you will need to edit to add a new area, these are:




Open up your map_header.asm, to make it easier, we’re going to copy what has already been set-up for Route 29. Let’s just ctrl+f the file, and find this line:


Once you find it, copy it and paste it right under it. Let’s, of course, change the name so that it won’t interfere with the already existing one. I’m going to call my new area Route 101, you can call it whatever you want, just make sure the name isn’t already used. Once edited you should have something similar to this:


This not only sets the name for the map, but also the tileset it’s using (TILESET_JOHTO_1), the name your map is going to be referred to in the code (ROUTE_101), the music (MUSIC_ROUTE_29). The other entries can be looked over, these are the most important.

Once that is done, open up constants/map_constants.asm, as with before, ctrl+f to find the already existing ROUTE_29 entry, copy it and paste a copy right under it. It should look something like this:

mapgroup ROUTE_101, 10, 10

This is going to be used to define the size of your map, 10 and 10 being my X and Y.

Once that is done move over to maps/second_map_headers.asm, as we alrady did before, let’s copy the already existing Route 29 entry and trim it down a little bit, since we won’t need all the entries it has. Our route only has one entry point, from the south of New Bark Town, which means that New Bark Town will need a connection to the south, and our map will need one to the north. Your area entry should look something like this.

map_header_2 Route101, ROUTE_101, $5, NORTH
connection north, NEW_BARK_TOWN, NewBarkTown, 0, 0, 10, ROUTE_101

Of course here you have the name of your route, the name of your file, what defines what fills the sides of your map ($5), and where the connection is going to be (NORTH). On the next line you will define the connection to the north. NEW_BARK_TOWN, of course, is the name of the file you want to connect to, NewBarkTown is the name of the map. 0/0/10 are what defines where your connection starts, let’s call them X, Y and Z. X will move where the connection to the map starts, 0 will be perfect center, 1 will move it to the right, and -1 moves it to the left. Y does the exact thing as X, just on another axis, 1 will move it up, -1 will move it down and 0 will be exactly at the center. Z is probably the most important, it’s what defines the size of the connection.

This might require you some fiddling, but you should be able to figure it out fairly easily trough trial and error.

This just added a connection from your area to New Bark Town, but obviously you also need a way to go to your area from New Bark. So let’s just add a connection to the already existing code. At the moment it should look something like this:

map_header_2 NewBarkTown, NEW_BARK_TOWN, 5, WEST | EAST

Let’s add a connection to the south by adding | south.

map_header_2 NewBarkTown, NEW_BARK_TOWN, 5, WEST | EAST | SOUTH

And then just add a connection under that:

connection south, ROUTE_101, Route101, 0, 0, 10, NEW_BARK_TOWN

Should be the same as the first one you added for your area, just with the names inverted.

I’m going to make it perfectly clear that despite Crowdmap being listed as an option, it is an extremely powerful tool that YOU SHOULD USE. Download it and set it up, it will help you a lot.

2. Edit Maps

I’m going to go trough the editing by using Crowdmap. It’s not essential to edit maps, but it is the best tool to use. Without it you’d have to edit hexes, a map would essentially look like this

As you can see it’s hard to make out what everything is, unless you know what each hex means.

I suggest trying to get used to crowdmap by just editing your new map. In my case it looked something like this.

I added a sign, a door and some tall grass for later. Now might be a good time to try to build your ROM to see if everything is working fine. You might encounter a few problems with the make command (such as data_*.asm is too big), fixes for these are explained at the bottom of the page.

As you can see, thanks to crowdmap, editing things around is fairly easy, what becomes more of a challenge is adding scripts to handle NPCs, warps, and events. So let’s try to do some of that stuff now, shall we?

 3. Warps

Warps are probably the most simple thing to add into a map. All the warps are contained directly into the ASM for the map you’re currently editing, in our case, Route101.asm.

If your file was created through Crowdmap, this is what you’re going to see the first time you open it up to edit it:

As you can probably immagine, your warps are going to be placed under .Warps: db 0

Let’s add a warp between New Bark Town and the new map. First off, let’s add a way to visually tell the player that there is a warp in New Bark, this can be done by many means, I decided to go for the pink patterns:

Next, in the map for New Bark town (NewBarkTown.asm), and under warps let’s add two warps generating at coordinates 1, 1 that connect themselves to our new map, ROUTE_101:

.Warps: db 6
warp_def 3, 6, 1, ELMS_LAB
warp_def 5, 13, 1, KRISS_HOUSE_1F
warp_def 11, 3, 1, KRISS_NEIGHBORS_HOUSE
warp_def 13, 11, 1, ELMS_HOUSE
warp_def 1, 1, 1, ROUTE_101
warp_def 1, 1, 1, ROUTE_101

Did you notice that I also changed db 4 to db 6? The number after db should always be the same number as the number of events listed after it.

Now you have two options: Either manually change the X and Y values of your warps to bring them to where you want them OR go into crowdmap and drag them where you need them. As you can see, right now, the warps are positioned at X1 and Y1:

So let’s just move them. Here they are where we want them:

Now let’s move on to our new map and do what we just did for New Bark here. This is pretty straight forward, the editing is pretty much the same, but in a different file. The only thing you should look out for is the third number used after the X and Y positions that we will call Z. Z is there to tell the game on which warp the player should come out once they walk into one. If Z is 1, once the player enters in the warp in ROUTE_101, he will end up coming out of Elm’s Lab. In this case you either want to set Z as 5 or 6, so that the player will come out of the same warp they came in.

4. Signs

Signs are fairly simple, and will give you a general understanding of how text works. Similarly to warps, they are added from the map’s ASM file. Find this line:

.BGEvents: db 0

And add this dummy placeholder right under it. Of course, don’t forget to edit db 0 to the number of events you will add under BGEvents,

signpost 3, 11, SIGNPOST_READ, TestMapSign

As discussed with warps, the two numbers after signpost are the X and Y coordinates of the event. You can either edit them from the code, or move them around in crowdmap.

Now, for whatever reason, you can’t directly point a sign directly to the test, so before going on to writing the text, you will have to add a way to jump to the text on the sign. It doesn’t matter where you add this, but you will need to do it this way, any other way will crash the game. Add this at the bottom of the code:

jumptext TestMapSignText

text "TEST MAP"

para "This is actually"
line "Working!"

para "I can hardly"
line "believe it"
cont "myself!"

Text is the start of the text, it should always be what starts your text. Para will start a new paragraph, while Line will continue writing automatically under para without input. Cont will instead only appear if input is received. Done is of course what ends the text, it should always be at the end.

?. Bugfixes

1. ‘Tileset Data *’ is too big

I first encountered this right after adding my first map. This is caused by problems with the compression script that handles some of the tilesets, and unfortunately there isn’t an easy fix.

What you can do is open up all your Data_*.asm files and move things between them until the error isn’t there anymore. This might take a while, but it’s unlikely you will experience it again once fixed. It’s mostly done trough trial and error, so I can’t help you much on that front.

2. Unable to load fixed ROMX section

This is a similar problem to the one described before. As far as I’ve noticed, it’s caused because too much data is being uploaded to a single Bank. The fix for this is the same for the one before, but unlike with the previously described error, the terminal will not tell you which file is too big, and it will be up to you to figure out.

But, luckily enough, I stumbled upon what defines the $XX numbers the error gives out and was able to understand what file they’re connected to. Here’s the possibilities:

BANK $06 = Data_1.asm

BANK $07 = Data_2.asm

BANK $08 = Data_3.asm

BANK $0C = Data_4.asm

BANK $2D = Data_5.asm

BANK  $37 = Data_6.asm

BANK  $77 = Data_7.asm

BANK  $78 = Data_8.asm

3. Nothing to be done for ‘all’

Pretty simple fix. Just write:

rm pokecrystal.gbc

In your Cygwin terminal, and then run “make” again.