LADX-Disassembly, Link's Awakening DX rebuilt from assembly source

The build reproduces the original ROMs, not a copy of them

The LADX-Disassembly repository is a disassembly of Legend of Zelda: Link's Awakening DX for the Game Boy, written in z80 assembly. The project's own framing is understated, describing itself as a disassembly of one of the author's favourite games, taking it easy for now.

What it produces is the interesting part. It builds ten complete ROMs across three languages and three revisions, each with an md5 checksum recorded next to it so the output can be verified against the original: azlj.gbc for Japanese v1.0, azlj-r1 and azlj-r2 for Japanese v1.1 and v1.2, azle.gbc and its r1 and r2 revisions for English, azlg.gbc and azlg-r1 for German, and azlf.gbc and azlf-r1 for French. It also builds four Virtual Console patches, azlj-r2.patch, azle-r2.patch, azlg-r1.patch and azlf-r1.patch, for the later revisions.

The distinction that matters is between a disassembly and a dump. This repository contains no game data. It contains assembly source, graphics as PNG files, encoded tile and attribute maps, and the build system that turns them back into a byte-identical ROM. If you never had the original cartridge, running the build produces nothing resembling the game, and that is exactly the property that makes such projects legally and technically interesting.

Alongside the ROMs, the project ships a wiki with a high-level overview of the game engine and technical information on the data formats used throughout the game, in particular the maps data format. That documentation is where the reverse engineering becomes usable rather than merely complete.

Building it needs rgbds and Python 3

The usage section is two steps. Install Python 3 and rgbds, with version 1.0.0 or later required, then run the build:

make all

That builds both the games and their debug symbols. Once built, the README says to use BGB, the Game Boy emulator, to load the debug symbols into the debugger. The debug symbols are the reason to care about the build process: they carry the names of every routine and every constant that the reverse engineering has identified, so the debugger shows labelled functions rather than raw addresses.

The default make target is narrower than make all. The Makefile states that the default target builds and tests only the US 1.0 revision, and that make all builds and tests all targets. The distinction is worth knowing because the full build produces ten ROMs and four patches, and a contributor working on one revision will usually want the fast path.

The style rules live in STYLE.md at the root of the repository, and the tree also carries ladx.md5 for the checksum verification, a revisions/ directory, src/, tools/ and docs/. The project uses CircleCI, with a .circleci/ directory at the top level, so the build and its checks run the same way for everyone.

The Makefile spells out the whole toolchain

The Makefile is the most instructive file in the repository, because it shows exactly which tool does what and with which flags.

The RGBDS suite provides the four binaries. rgbasm assembles the source with --export-all, which exports every label so the linker and the debugger can see them, plus -Weverything to turn warnings into errors and -Wtruncation=1 to catch values being silently truncated. rgblink links the objects, and rgbfix produces the final cartridge image with --color-compatible and --sgb-compatible, a RAM size of 0x03, an MBC type of 0x1B, a pad value of 0xFF, and --validate, so a broken header fails the build rather than shipping.

Graphics go through two paths. Most PNGs are converted to 2BPP with rgbgfx, which the Makefile notes is much faster than the project's own tool. Object attribute sprites take a different route, through tools/gfx/gfx.py with the --invert and --interleave options, because those need the palette inverted and the tiles de-interleaved, which rgbgfx does not do.

The Makefile also finds the PNGs, the encoded tilemaps and attrmaps under src/data/backgrounds with a recursive wildcard function written in make syntax, and it is careful to note that src/constants/hardware.inc is the only .inc file in the repository, so the dependency list stays explicit.

Contributions are small, labelled improvements

The contribution guide describes a workflow built around incremental reverse engineering, and the examples are unusually concrete.

Fork the repository, find a little piece of code to improve, then submit a pull request. The kinds of improvement named are a typo, a missing constant, an obvious label that could be renamed, or following a thread such as Link's animations, the island fade-out special effect or the trading items constants, and documenting the details you find along the way as you read.

The project also points at its known improvements issue list, and specifically at the good first issues, which is a good place to start if you have never contributed to a disassembly before. The theme running through the examples is that the work is not only about adding new code, it is about making existing code legible, and that naming a constant or a routine correctly is a real contribution to a shared artefact.

That framing has a practical consequence for anyone planning to use this repository. A disassembly is a description of a game that is being refined over time, and the API of that description changes as names are corrected and missing pieces get identified. Code that depends on specific labels will need updating as the project moves.

Questions are handled on Discord, and the wiki carries the disassembling how-tos, with a series of blog posts at zladx.github.io covering progress reports along the way.

Where the reverse engineering ground is documented elsewhere

The README lists external resources, and they are worth reading because they show how much of the surrounding knowledge is community-owned rather than proprietary.

Artemis251's Link's Awakening Cache provides the ROM map and the maps data format, and Xkeeper's Link's Awakening depot covers the map tilesets and the save format information. The LALE level editor project by anotak contains notes on the map data format, and the Link's Awakening and DX speedrunning wiki holds information on wrong warps and on map data.

The most interesting entry is the Zelda III Disassembly, which is described as a good source on Zelda SNES source code with many similarities to LADX. A Game Boy game and a Super NES game sharing an engine family is a rare thing, and it is the kind of connection that shortens reverse engineering work considerably.

The list of contributors in the README, from mojobojo, Xkeeper, Rangi42 and others, matches the list of people behind those external resources, which tells you that the LADX disassembly and the wider documentation effort are the same body of work.

That also frames the licence position honestly. The repository does not declare a licence in its metadata and the README does not state one, so if you intend to reuse the disassembly output, the labels or the tooling in a project of your own, that is a question to raise with the project rather than one you can answer from the README.

Editorial conclusion

LADX-Disassembly suits Game Boy hackers, speedrunners and reverse engineers who want to read how a commercial game works at the instruction level and then change it. It does not suit anyone who wants a ready-made copy of the game, because the repository contains source and build tooling rather than the copyrighted data, and it does not suit a project that needs a stable API to build on, since a disassembly changes as the reverse engineering progresses. Before you start, install rgbds version 1.0.0 or later and Python 3, then run make all and compare the output against the md5 hashes listed in the README to confirm your toolchain reproduces the expected ROMs.

Frequently asked questions

Official sources

1. Issues
2. README
3. zladx/LADX-Disassembly on GitHub