khdays-decomp

A work-in-progress matching decompilation of Kingdom Hearts 358/2 Days (Nintendo DS). The goal is C source that recompiles to a binary byte-for-byte identical to the original game code.

Disclaimer

This repository does NOT contain the game ROM, any game assets, or any of the original binary/assembly. An existing, legally-obtained copy of the game is required to extract and build it.

This repository is a matching decompilation only. It does not contain or produce a playable build or any redistributable game binary, and building it requires an original, legally-obtained copy of the game. All trademarks and the original game are property of their respective owners.

Status

Every function of the EU (YKGP) ARM9 program and its overlays is matched, and all of the initialized data is reconstructed: the rebuilt modules are byte-identical to the game's (306 of 306). All of the game's own code is C except two functions that need the clz instruction, which the compiler cannot produce from C. The rest of the assembly is library code (NitroSDK, the CodeWarrior runtime, MobiClip) whose original source was assembly too.

The work now is making that C readable: declaring the game's shared structures once in include/ instead of in every file that uses them, naming what is still named by address or offset, and grouping functions back into the files they came from. Progress is split into categories so that assembly is never counted as C decompilation.

Category	Count	Meaning
Real C-decompiled matched functions	23,125 / ~23,233 (~99.5% by function count)	Functions implemented in C and verified byte-exact
Complete functions (C + verified original library assembly)	23,231 / ~23,233 (~100.0%)	Real C, plus library functions whose original source is assembly (NitroSDK/MSL asm, BIOS veneers): C cannot express them, so they count once integrated as that assembly and byte-verified with source evidence in config/arm9/report_asm_matches.json.
Real C-decompiled matched bytes	4,716,202 / 4,728,788 (~99.73% by code bytes)	Real-C-only byte progress; asm_stubs/, inline ASM and nonmatching/ are excluded. decomp.dev additionally counts source-hashed, verified SDK assembly and authorized CLZ exceptions as matching, not as C. See progress policy.
Inline ASM / ASM stub matched functions	108 / ~23,233 (~0.5%)	ASM implementations: the libraries' own assembly and the authorized inline exceptions (two game functions that need clz); never counted as real C. Only explicitly verified manifest entries contribute to decomp.dev matching coverage.
SDK/library byte-match identifications	0 / ~23,233 (~0.0%)	NitroSDK or library functions identified separately by byte matching
Named but not decompiled	0 / ~23,233 (~0.0%)	Functions known to the project but not implemented as C
Initialized DATA	188,336 / 188,340 (100.00%)	Byte/relocation-verified .rodata/.data; includes the separately reported MobiClip executable payload at 26,012/26,012 bytes.
Total known functions	23,240	Function index for the EU YKGP target
Region	EU (YKGP)
Compiler	CodeWarrior mwccarm 3.0 build 139	Per-module progress is in PROGRESS.md. A few precompiled-middleware translation units (e.g. the ov028 anti-tamper crypto core) build with an older mwccarm via a per-file compiler override (config/arm9/file_compilers.json).

The current counts are generated by python tools/audit_progress.py. See docs/PROGRESS_POLICY.md for what counts as real decompiled progress.

Progress reporting policy

Only real C implementations are counted as C-decompiled progress. Assembly, whether a library's own or an authorized inline exception, is counted separately, and so is anything under nonmatching/.

SDK/library byte-match identifications are tracked separately from game-code decompilation. See sdk/README.md for the SDK identification workflow.

Repository layout

src/engine/                 the main module's game code (ITCM included); data/ holds its DATA
src/overlays/scenes/        overlays loaded through the scene table (title, field, camp menu, ...)
src/overlays/screens/       screens and menus a scene loads (shop, game over, ...)
src/overlays/field/         modules loaded inside the field scene: battle, event script, pickups, ...
src/overlays/players/       playable characters, one overlay per character and load slot
src/overlays/enemies/       one overlay per enemy class (ovNNN_enemy_<class id>)
src/overlays/system/        boot, wireless, MobiClip video, DS Protect, shared enemy framework
include/                    shared headers: basic types, NitroSDK/NitroSystem declarations, and
                            the game's shared structures (game/: enemy actor, AI task, ...)
libs/nitro/ libs/nns/       NitroSDK and NitroSystem
libs/msl/ libs/mobiclip/    Metrowerks runtime and C library, MobiClip middleware
config/                     dsd project config (symbols / delinks / relocs per module)
docs/                       layout.md maps the binary to this tree; renames/ lists symbol renames
tools/                      Python tooling (build, verification, reports)
sdk/                        NitroSDK byte-match identification harness (see sdk/README.md)
build/                      generated manifests and reports; build output is git-ignored

Every function is one .c file named after it, in its module's directory: src/engine/ for the main module, the overlay's own directory otherwise. An overlay directory keeps the FS overlay id the game loads it by (ov114_enemy_00); overlays whose purpose is not established yet keep the bare ovNNN. docs/layout.md explains what each overlay is and on what evidence.

Library code under libs/ keeps auto/ and calls/ for C and asm_stubs/ for the libraries' own assembly (the NitroSDK's hand-written routines, the CodeWarrior runtime). That assembly may match the original bytes, but it is counted separately from real C decompilation progress, see docs/PROGRESS_POLICY.md.

Structures the game shares between files are being moved into include/game/ (the enemy actor, the AI task, the Mission Mode session, ...). A source that still declares a partial view of a structure locally only declares the fields it touches; tools/structconv.py moves such sources onto the shared declaration and keeps the change only when the source still compiles to the same bytes.

The ROM, the extracted data (dsd_extract/, asm/), build artifacts, and the proprietary toolchain are intentionally not tracked; see .gitignore.

Building / verifying

You need your own copy of the game plus the toolchain (see CONTRIBUTING.md for setup). Then, to verify a single function:

python tools/getcand.py func_XXXXXXXX        # prints disasm + the verify command
python tools/match.py <your.c> <...>          # compiles and byte-compares

A green >>> MATCH <<< means your C reproduces the original exactly. python tools/verify_idx.py <file.c> checks a source already in the tree, and bash tools/gate.sh rebuilds every module and compares the whole program.

Toolchain

• dsd - DS ROM extraction / delinking
• mwccarm 3.0 (CodeWarrior for Nintendo DS) - the matching compiler
• arm-none-eabi-as (GNU binutils) - assembling the libraries' own assembly routines
• Python 3 with capstone, pyelftools, ndspy

See the Nintendo DS decompilation guide.

Credits

• The DS Protect 1.10 sources in ov028 (src/overlays/system/ov028_dsprotect/dsprot/) and tools/dsprot_decrypt.py are reconstructed after taxicat1's decompilation of DS Protect, taxicat1/dsprot (branch 1.10).
• The NitroSDK identification harness in sdk/ compiles the NitroSDK sources of pret's decompilation of Pokémon Diamond, pret/pokediamond, and several libs/nitro routines were cross-checked against its matched C.

Contributing

Contributions are very welcome; see CONTRIBUTING.md. Every matching function must pass byte-exact verification, and public C decompilation progress only counts real C implementations. Progress per module and how to claim one is in PROGRESS.md.

License

The decompilation and tooling in this repository are dedicated to the public domain under CC0 1.0. This applies only to the contributors' own work; the original game and its assets remain the property of their owners.