This is a disassembly of Game Boy game "The Jungle Book". Additionally, this repository contains tools to understand and modify the game.
This project does not promote piracy and requires a copy of the original game to compile. For more information see "Building". Note that this project is still work in progress with contributions being welcome :)
To avoid problems with copyright, this project just provides some kind of skeleton code without any assets, such as sprites and logos.
In the code, these assets are represented by external dependencies (INCBIN <path_to_asset>
).
To get everything compiled, you need to extract the assets from an original copy of the game with the following script:
./utils/asset_extractor jb.sym <path_to_original_copy>
This will create a directory assets
including the subdirectories of bin
and gfx
.
Subsequently, copy bin
and gfx
to src
:
cp -r assets/bin src/bin
cp -r assets/gfx src/gfx
Now everything is in place and you can start the compilation using the RGBDS toolchain. Assuming RGBDS is installed, the game can be compiled with:
cd src
make all
The compiled game can then be found as game.gb
.
If you didn't modify the source code of this repository, game.gb
should be a bit-exact copy of the original game.
This can quickly be verified with an MD5 hash:
md5sum original_game.gb
md5sum built_game.gb
The result should be e5876720bf10345fb2150db6d68c1cfb
.
The project is still work in progress with the following status per file:
File Name | Labels identified |
---|---|
bank_000.asm | 42.8% (277/647) |
bank_001.asm | 33.9% (151/445) |
bank_002.asm | 95.5% (63/66) |
bank_003.asm | 100.0% (40/40) |
bank_004.asm | 100.0% (20/20) |
bank_005.asm | 100.0% (46/46) |
bank_006.asm | 100.0% (26/26) |
bank_007.asm | 5.1% (21/408) |
In total, the progress 37.9% (644/1698)
Initially, this project was started to extract the level maps from the game's ROM.
Because having a map with all gem locations is a significant aid to beat the game and also helps to plan speed runs.
I anticipated there would just be a memory location containing the map indices and map tiles.
It turns out I was wrong as the game uses way too many tricks to cram the 10+2 maps into the 128 kiB of the cartridge.
Nevertheless, after spending way too much time on reverse-engineering decompression algorithms and meta tiles the final product can be found under utils/level_renderer.py
.
Provide the original game as an argument and execute it as:
./level_renderer.py <path_to_rom>
The maps can then be found in the directory lr_tmp
.
For instance, the map of the first level looks like this:
Many assets of the game are LZ77 decompressed.
Use the decompressor.py
script to decompress the binary data. Optionally, the data can be rendered as tiles.
For example, when decompressing and rendering the font data:
./decompressor.py CompressedFontTiles.bin
You get:
The object analyzer extracts all object data for each level and prints the corresponding attributes. This includes an object's position, type, the loot it drops, and its X position limits in case the object moves. Example:
Level 1
X pos Y pos Type Loot X limits
------------------------------------------------------------
24 408 CHECKPOINT - -
1568 472 CHECKPOINT - -
732 474 CATAPULT - -
3004 474 CATAPULT - -
384 480 BOAR PINEAPPLE 256-512
816 480 BOAR BOOMERANG 752-944
1488 480 BOAR GRAPES 1360-1616
824 256 COBRA DIAMOND -
1112 416 COBRA SHOVEL -
...
The file jb.sym
is a symbol file following the file format from RGBDS.
It can be loaded into many Game Boy tools, such as Gearboy, for an improved debugging experience.