ZevyaDev/dqix-decomp-kit

Tools for matching Dragon Quest IX (Nintendo DS, USA) functions to byte-exact C++ in
ZevyaDev/dqix-decomp, branch decomp-matching. Usable by
hand, from a single AI session, or as an autonomous fleet of Claude Code workers.
The kit compiles a candidate with the build's own mwccarm and flags, compares it against the
original ROM bytes, names the class of whatever still differs, applies meaning-preserving rewrites,
and lands matches through one serialized, gated path that commits to the decomp.
Platform
Tested on Windows 11, Git Bash, Python 3.10. The per-function tools are plain Python but run the
decomp's mwccarm.exe directly; untested on any other system. The fleet scripts list processes with
PowerShell Get-CimInstance and run only on Windows.
Quickstart
Clone both repositories side by side. The kit finds the decomp at ../dqix-decomp, or at
$DQIX_REPO.
git clone -b decomp-matching https://github.com/ /dqix-decomp.git # your fork of ZevyaDev/dqix-decomp
git clone https://github.com/ZevyaDev/dqix-decomp-kit.git
Build the decomp once. Supply your own base ROM and place it as the decomp README says
(extract/baserom_dqix_usa.nds).
cd dqix-decomp
python -m pip install -r tools/requirements.txt ninja
python tools/configure.py usa
ninja min
Initialise the kit:
cd ../dqix-decomp-kit
python -m pip install capstone pyelftools
python kit_init.py --slow
python selfcheck.py
--slow runs the end-to-end crack tests once; selfcheck.py fails until they have run.
The kit is updated continuously. Start every session with python kit_update.py; agents are told to
in AGENTS.md.
The checkout holds code only. Your attempts, logs, claims and staged matches live in a separate
state directory, ../dqix-kit-state by default (python kit_init.py --state to put it
elsewhere), so no git command run in the checkout can touch them.
Match one function. Module is main or a 3-digit overlay; addresses are 8 hex digits without 0x.
export KIT="$(pwd -W 2>/dev/null || pwd)" SP="$(python kitpaths.py state)"
python claim.py 017 --peek 5 # next candidates in overlay 017; claims nothing
A=021bb1a4 # one of them
F="$SP/wip/ov017/$A.cpp"; mkdir -p "$SP/wip/ov017" "$SP/staging/ov017"
python scaffold.py 017 $A "$F" # callees and data resolved, a stub to fill in
python wlist.py 017 $A # the target, decoded from the ROM
python wgate.py 017 $A "$F" # MATCH, or RESIDUE
python wdiff.py 017 $A "$F" # only the differing instructions
python colorsweep.py 017 $A "$F" --apply # mechanical rewrites, stops on MATCH
cp "$F" "$SP/staging/ov017/$A.cpp"
bash finish_wave.sh 017 # integrate, ninja check, commit, push
wgate.py and wdiff.py change into the decomp directory, so source paths must be absolute.
finish_wave.sh reverts uncommitted edits to tracked files under the decomp's include/, config/
and src/ before it starts; commit your own changes first. docs/WORKFLOW.md
explains every step.
Layout
| path | contents |
|---|---|
| wgate.py wdiff.py wlist.py scaffold.py residue.py | the per-function gate, diff, listing and starting file |
| colorsweep.py presweep.py vtry.py symfix.py fixundef.py autorepair.py | mechanical rewrites and repairs |
| claim.py poolsize.py nearmiss.py resumable.py sdkident.py dqtool.py | choosing work |