Pokemon HeartGold Decomp: A Work in Progress With a Crash Warning

By Indie Kings | October 28, 2026

Updated October 28, 2026: pret/pokeheartgold, the work in progress disassembly of Pokemon HeartGold and SoulSilver, merged a pull request on October 27, 2026, and its README carries two warnings that most fan projects would rather not print: the tree is unstable enough that symbol names and code structure can change without warning, and because the ROM is not fully decompiled, modifications that shift the size or layout of a function or data structure can crash the game.

Image: an original Nintendo DS, the launch model of the hardware HeartGold and SoulSilver shipped on, via Wikimedia Commons.

What the warnings actually mean

The first warning is about churn: names and structures can change drastically and without warning, so anyone treating the repository as a stable base for a mod accepts the risk. The second is more specific and more useful, because it explains the failure mode. In a partial decompilation, part of the game is C that has been matched against the original binary and part is still assembly or unresolved data. The linker places everything according to the original layout. If a modification makes a matched function longer, or adds a field to a structure that other code indexes into, the layout shifts and code that still expects the old addresses reads the wrong bytes. The game does not politely report a mismatch. It crashes.

Printing that in the README is a mark of maturity rather than a weakness. The alternative, a project that advertises itself as ready for modding while silently shifting data, produces bug reports from people who cannot tell whether their change was wrong or the base was. The warnings set expectations precisely: this is a preservation project first, a modding base second, and the second role comes with constraints until the matching work is finished. For readers outside the scene, it is also a useful correction to the assumption that a decompilation is either done or useless. Partial projects are genuinely useful, just not for every kind of change.

Two games in one 418 MB tree

The repository was created on June 18, 2021 and now weighs roughly 418 megabytes, a figure that says as much about the DS era as any commit message. HeartGold and SoulSilver are two versions of the same game with different encounter tables and version exclusives, so the tree has to support both, and the build produces pokeheartgold.us.nds at SHA1 4fcded0e2713dc03929845de631d0932ea2b5a37 and pokesoulsilver.us.nds at f8dc38ea20c17541a43b58c5e6d18c1732c7e582. Both are US releases, and both hashes are published in the README, which is the project's claim to accuracy in one line.

Activity is steady rather than explosive: 745 stars, 239 forks, 44 contributors, 22 open issues, and a merge on October 27, 2026 whose commit line reads Merge pull request 564 from scbroede/nopad2electricboogaloo. The branch name is a joke, the merge is real, and the pull request number is a useful scale marker once you remember that GitHub shares one counter between issues and pull requests. This project has reached 564 in that counter in five years, while the younger Platinum repository has passed 1,300. Different games, different difficulty, different contributor pools, and a reminder that decompilation progress is not a single curve.

Why the DS titles lag behind

The Game Boy Advance decomps had two advantages that the DS projects do not. The hardware is simpler, so a matching build depends on one well understood compiler and a small set of libraries, and the games are small enough that the whole binary can be held in one person's head. HeartGold and SoulSilver sit on the other side of that line: a dual region campaign spanning Johto and Kanto, a script and event system with far more content, two screens, touch input, wireless features and a peripheral in the Pokewalker that shipped with the games. Every one of those systems is more code to match and more data to identify.

That is why projects like this one spend years in a state where the C is readable in places and opaque in others, and why the practical value arrives in stages. Documented structures make save editing and small logic changes feasible long before the last function is matched. Each merged pull request converts another piece of assembly into something a person can reason about, and the README's warning is really a description of where that process currently stands: far enough to be useful, not far enough to be safe for arbitrary edits. For a 2009 game with a devoted competitive and shiny hunting community, that middle state is still the best source level view anyone has had.

Project card

FAQ

What is pokeheartgold?
A community disassembly of Pokemon HeartGold and SoulSilver that rebuilds the US DS ROMs from source and data, with published SHA1 hashes for both versions.

Is it finished?
No. The README describes it as a work in progress and warns that symbol names and code structure can change without notice.

Why can mods crash the game?
Because parts of the ROM are still unmatched, the build depends on the original layout. Changes that alter function sizes or structure layouts can shift addresses that remaining code still relies on.

What does the repository build?
pokeheartgold.us.nds and pokesoulsilver.us.nds, each verified against a hash listed in the README.

How active is the project?
It merged pull request 564 on October 27, 2026, with 44 contributors and 22 open issues.

Is a partial decompilation useful?
Yes, for reading code, documenting structures and small logic changes. Large structural edits are the category the warnings are aimed at.

Bottom Line

The most valuable sentence in this repository is the warning, because it tells you exactly what stage the work is at and what it is safe for. HeartGold and SoulSilver are enormous games, and a five year old project with 418 megabytes of tree, two verified builds and a counter past 560 is making real progress on a problem the GBA decomps never had to face at this scale. It is not a modding platform yet, and it says so. That honesty, plus a merge landing on October 27, is more convincing than any roadmap.

Sources

• GitHub pret/pokeheartgold README warnings, build list and hashes, accessed October 28, 2026
• GitHub API metadata for pret/pokeheartgold, stars, forks, contributors, issues, size and latest commit, accessed October 28, 2026

Related: Dead Cells: First PS5 Game Runs Natively on Windows via AnyPS5 | We Lurk Below Mod: It Lurks Below Gets a Fan Decompilation and Native Port