A work-in-progress decompilation of Pokémon Black 2 and White 2. Both USA/Europe ROMs rebuild byte for byte from the same source tree.
Progress updates automatically from CI. ByteMatch shows it for each version, for ARM9 main and the overlays, and for the game's code and each library.
Requires Linux, WSL or macOS, Python 3.11+, ninja, and LLVM (clang and llvm-objcopy on your PATH).
-
Place your own ROM dumps in
orig/, using the filenames below. -
Configure and build:
python3 configure.py ninja
The first run downloads the remaining tools. Every available version is built and checked against its SHA1. ROMs are not included or provided.
| ROM (USA/Europe, NDSi Enhanced) | Input file | SHA1 |
|---|---|---|
| Black 2 | orig/baserom_b2_us.nds |
e51e6dfb8678a3d19dcd2a10691b96a569ca0abb |
| White 2 | orig/baserom_w2_us.nds |
b5d7490be7b415b8f1e672a53e978a9cc667e56a |
Output: build/pokeblack2_us.nds and/or build/pokewhite2_us.nds.
See Build details for macOS setup, toolchain options and modified builds.
Read CONTRIBUTING.md for the workflow and rules. Claim an overlay's issue before starting work. CI compiles every C file for both versions; fork PRs must verify ROM matching locally.
| Guide | Covers |
|---|---|
| Build details | Setup and build options |
| Decompiling | Workflow and tools |
| Matching | MWCC behavior and matching techniques |
| Code organization | Source layout, libraries and names |
| Native port notes | Recovered platform assumptions and open porting questions |
| Source files | Overlay files and boundary evidence |
| Nonmatching functions | Remaining mismatches |
| Game data | Data formats and archives |
| Cells and animations as JSON | The sprites' cells, animations and MCSS files as JSON |
| Scripts | Trainer AI, battle animation and field scripts |
| Configs and ROMs | dsd configuration and ROM structure |
| Tools | Tool reference |
This project builds on the work of others:
- Names: swan by DS Pokémon Hacking, the source of the symbol, type and field names imported here.
- References: pret's pokeplatinum, pokeheartgold, pokediamond and pokeemerald, whose layout, build and conventions this project follows; ntrtwl's NitroSDK and NitroSystem reconstructions; and aletheia, the Black 1 decompilation, whose map of the SDK libraries' objects placed many of our library files.
- Tools: ds-decomp and ds-rom by AetiasHax, used through our forks; the MWCC packages from decomp.aetias.com; objdiff and sjiswrap by encounter; wibo by decompals; decomp-permuter by simonlindholm; Apicula by scurest, for exporting models; and ByteMatch for progress tracking.
- Data and assets: the cell and animation converter
nitro_cells.pyby Michael Neuberger, from pokegrey; the whole-model writer, new map models and texture imports by bjayers, from Paper White 2; and the per-species folder layout of pokeemerald-expansion.
GNU GPL v3.0, including the symbol names imported from swan.