Page 1 of 1

Donkey Kong Land 2 & 3 Map Dumper

PostPosted: January 5th, 2013, 7:21 am
by Blaziken257
Hello everybody, I have created a program that rips level maps from Donkey Kong Land 2 and 3. Yes, it works for two games at the same time, since DKL3 was heavily built off DKL2 (not too surprising, it has the same physics, similar graphics and sound effects, etc.) It works for all versions of these two games, so you can use this on the Japanese and English versions, the DKL3 prototype, various ROM hacks, etc. Here is a list of various features it has:

- Ability to rip level maps
- Color palettes for Super Game Boy and Game Boy Color, as well as a monochrome palette for Game Boy
- Accurate water shading
- Ability to rip 8x8 tiles in each level type (harder than it sounds, since decompression is required)
- Ability to rip 32x32 tiles in each level type (made up of 8x8 tiles)
- Logs for map decompression routine
- Raw, decompressed map data in hexadecimal

Unfortunately, it doesn't support sprites yet. I'd like to add that in some future release, though, because it would be very helpful. It also doesn't rip bonus stages yet, though I'm thinking of adding that in too. But this is the first release, so you can't expect everything yet.

Now, here is how to run it:

- You need Python 2.7.3 (NOT 3!). Download it here, then install it: http://python.org/download/releases/2.7.3/
- Decompress the ZIP folder that's attached, then double-click on map_dump.py. Don't touch any of the other .py files (with the optional exception of settings.py, more on this below).
- A command line window will open up.
- You'll first be prompted to enter a file name of the ROM (you can just drag the file into the window).
- You'll then be prompted to enter the level you want to dump.
- You'll next be prompted to choose between SGB or GB palettes (for DKL2 and English DKL3), or GBC or GB palettes (for Japanese DKL3).
- That's it! Once it's done, go to the Maps folder (under the folder of the game you used) and you will see it there!

You can also change various settings by editing settings.py. In Windows, don't double-click it; instead right-click it and click Edit with IDLE. (Alternately, you can open it in Notepad like you would open a .txt file.) In Ubuntu, you can double-click it, then click Display on the window that appears.

These are what the various settings do:

Spoiler!
hexdump: If True, a hex string of the decompressed map data will show up in the Hexdumps folder. This is the same data as the data that appears somewhere after 0xC600* in RAM in DKL2 and DKL3. Useful for research.
*Exactly where it ends up in RAM depends on the level height.

maptiles: If True, a PNG image with 32x32 tiles for the map will show up in the Maptiles folder.

tileset: If True, a PNG image with 8x8 tiles for the map will show up in the Tileset folder.

maplog: If True, a (rather lengthy) log of the summary of what took place when decompressing the map data will show up in the Logs folder. Quite useful for reverse engineering and research.

warnings: If True, the program will warn the user whenever too many tiles are read as a result of decompressing map data. This can be either an error in the program or an error in the game itself having more data than what can appear on screen (this occurs in Chain Link Chamber and Krazy KAOS, for example). As of this writing, this program's map decompression routine has no known errors, so this is False by default.

spriteboxes: If True, black boxes will appear where sprites are supposed to be. This is a makeshift solution for displaying sprites for now. This is False by default because the boxes make the maps look ugly, but setting this to True can be useful for knowing where sprites are in the first place, or for determining differences between similar ROMs (e.g. Prototype DKL3/Final DKL3, or English DKL2/Japanese DKL2).
This program has been tested on Windows and Ubuntu, but I've been unable to test this on Mac since I don't have access to a Mac computer. Hopefully it will work there somehow, though. If you're stuck on how to use this program, look at the README file or ask here. Also, feel free to report any issues here.

(I'm also painfully aware that the source code is messy, by the way! I don't need to hear that.)

Download:
http://www.mediafire.com/?h53pej7ey7tvv7s

Re: Donkey Kong Land 2 & 3 Map Dumper

PostPosted: January 6th, 2013, 1:13 pm
by Nintendo Player
Wow, this is fantastic. I was able to rip all of the DKLIII prototype's level maps and easily compare them to the retail version. I found a number of new differences as a result. In fact, I already managed to update the article on Nintendo Player with some maps (along with a plug for this program!). Thanks! You've officially made me geek out! Keep up the great work! :nicework:

I'm super impressed by how many talented people there are at DKC Atlas.

Re: Donkey Kong Land 2 & 3 Map Dumper

PostPosted: January 6th, 2013, 5:58 pm
by Qyzbud
Astonishing work! I knew you had a project in the works, but I didn't realise it would be something this valuable. :D

I guess I'll have to add a DKL trilogy mapping project to the Atlas now, as you've made it a far-more-accessible goal than it ever was before. ;)

...and you said you'd been lazy lately. HA! :P


Thanks for this; in fact, I'm going to add a feature to the forum that will allow everyone to say thanks for your efforts. Stay tuned!

Re: Donkey Kong Land 2 & 3 Map Dumper

PostPosted: January 7th, 2013, 10:55 pm
by Raccoon Sam
I knew you could do it!! YES!
Absolutely stunning. Once you get the sprite routine (oh god) nailed down, you might want to submit these to vgmaps.com.

Amazing job, Blaziken. Amazing job.

now for the editor

Re: Donkey Kong Land 2 & 3 Map Dumper

PostPosted: January 10th, 2013, 3:43 am
by Blaziken257
Thanks, everyone! This was hard work -- in fact, I started it before there was even any public knowledge of the DKL3 prototype. (Incidentally, I had to do very little to make the tool work on the prototype -- mainly, I made the program create a separate folder for it once it was released.) The tool was difficult to make because of the decompression with both the maps and the tiles, and required extensive testing. It was also hard work getting the SGB and GBC palettes (GBC in particular) and giving the tiles the right colors. And of course, I had to make it work for two games at once, which have different water shading mechanisms and sometimes different pointers as well.

I still need to work on sprites, of course, but this isn't going to be easy either. I'm slowly figuring out the format, but I wouldn't be surprised if there were separate cases for different sprites. And making the program find the right offsets on ROM based on sprite data won't be easy, either. And of course, I have to make it work on two games at once, and I need to get the positions and starting points all accurate! But it is something that I want to do, so it will be done... slowly. (I really don't like the black boxes, they're not aesthetically pleasing, but when the games uncompress the maps, it initially sets all sprite-based tiles to 0x80.)

I'd also like to make a map editor, but that's going to be even harder -- I need to come up with a nice GUI, and learn how to code one (I really should get into wxPython sometime, I've been putting this off for a long time). Another problem is re-compressing maps, due to all the cases involved. Of course, I can leave them uncompressed, expand the ROM, and put each level in its own bank, assuming they fit in 16KB. I'll have to figure out what to do with that sometime.

Also, I need to make the program work with bonus stages, but this will be relatively easier (I just need to make it find the right offsets).

In addition, I'd like to make similar tools for DKL, and perhaps DKC GBC sometime (the latter might be a bit easier, actually, since the tiles are uncompressed).

There's something else I forgot to mention, but I'm going to bring it up now before anybody asks. You may notice that when dumping the maps of Lockjaw's Locker, Lava Lagoon, and Glimmer's Galleon, the water looks weird (especially in Lava Lagoon, where the shading doesn't match up well with the waves). This is because when the water graphics are loaded, it's initialized with unique tiles, but then, when the water is animated (which starts before the screen is fully loaded), it replaces these tiles with the tiles that Arctic Abyss and Clapper's Cavern use, leaving the initialized tiles unused. (See here!) And of course, the map dumping tool only rips initial tiles, not animated ones. If you want to see these tiles in-game yourself, go to a hex editor, go to offset 0x7CF21, and change the value from 01 to 00. This tool is how I discovered these unused graphics in the first place -- I wasn't expecting it either, so it was a surprise!

Finally, Raccoon Sam, does this program work on a Mac? I'm unable to test it there since I don't have one. Also, Nintendo Player, I'm glad you found many other differences with this tool! To Qyzbud, I'm looking forward to seeing the DKL map pages! :D