God Hand Decomp: Matching the PS2 Retail ELF Byte for Byte

What This Decompilation Actually Demands

Most decompilation projects aim for source that behaves the same as the original. This one demands more. The README is explicit: the goal is C/C++ that, compiled with the original PS2 toolchain, reproduces the NTSC-U retail master SLUS-21503 byte-for-byte from a single source tree. That means the compiled output must match the original machine code down to register allocation and instruction order. The bar is not functional equivalence; it is binary identity. The project targets the NTSC-U version of God Hand, a 2006 Clover Studio and Capcom game for the PlayStation 2. It is for people who care about how the original compiler turned C into assembly, not for people who want to play the game on a PC. There is no port. The sole aim is decompilation, and the README says so directly.

The Mechanism: Splat, Carving, and the Ratchet

The project follows the matching decompilation model popularized by decomp.me. The process starts with splat, which disassembles the retail boot ELF into one monolithic assembly file, asm/cod/000000.s. Every instruction carries the retail bytes in a comment. Each function begins as raw assembly included from C via INCLUDE_ASM. The work is called carving: one function at a time, a contributor rewrites the assembly as real C, and the INCLUDE_ASM line is replaced once the compiled output matches the retail disassembly. The scoring tool is objdiff, which diffs each compiled unit against the frozen retail target. A function is matched only when its compiled .text is identical, including register allocation and instruction order. The ratchet is the full-ELF sha256 check: every commit must keep the entire ELF byte-identical to retail. This means the project stays green only while every carved function reproduces retail exactly. The README states that an empty carve already reproduces retail, so the binary integrity is maintained from the start. This design prevents regressions, but it also means the project cannot ship partial progress in a broken state. The progress metrics are matched_code_percent and matched_functions from objdiff, plus the binary pass/fail gate. The two are complementary: one shows how far in the decomp is, the other confirms the binary still reproduces.

Getting It Running: Commands and Environment

The setup assumes you have a legally dumped NTSC-U disc. The repo contains no game data. The first step is to place your own ISO at the repo root as 'God Hand (USA).iso' and run ./scripts/extract_iso.sh to extract and verify the boot ELF. Next, ./scripts/setup_toolchain.sh provisions the original toolchain: ee-gcc 2.96, the SN linker, dvp-as, plus splat, m2c, objdiff, asm-differ, and decomp-permuter. It also sets up a Python venv and git hooks. One host dependency is required: mipsel-linux-gnu binutils, which the build calls as a cross assembler. Then you run .venv/bin/python compile.py --setup to generate the asm split and the objdiff scoring project. The final step is building, which produces build/SLUS_215.03.elf. If its sha256 equals the retail boot ELF, your environment is correct. The README also describes a Nix dev environment: nix develop provisions a sealed toolchain, including the compiler, wibo, objdiff, cross-binutils, Python, and Node. On Linux x86_64, the i386 compiler blobs run natively; on ARM they run under qemu-i386. On macOS, the compiler is an i386-Linux binary, so you run the Linux flow inside a linux/amd64 container using Docker. The Nix flow is additive: the shellHook symlinks pinned blobs into the gitignored paths, so the setup script skips blob fetches and only handles the venv, Python tools, assembler patches, and git hooks.

The Hard Constraint: Original Toolchain Only

A matching decompilation is only as good as the toolchain it targets. This project pins ee-gcc 2.96, the SN linker, and dvp-as. Those are old, proprietary, and not freely redistributable. The README notes that the original PS2 SDK binaries are not redistributed; the setup script downloads them from public archives maintained by the PS2 decomp community. That introduces a dependency on external archives that could disappear or change. The compiler is an i386-Linux binary, which complicates macOS and ARM development. The Nix environment handles those cases, but only if you have Nix installed and are willing to run a container on macOS. The requirement for a legal disc dump is another barrier: you cannot even start without the original media. These constraints are inherent to matching decompilation, but they make the project less approachable than a non-matching decomp that just needs a modern compiler. If you want to contribute, you must be willing to work with a 2002-era compiler and its quirks. That is not a flaw in the project; it is the definition of the task.

Where It Falls Short: Speed, Scope, and Overlays

The matching approach is slow by design. Each function requires manual rewriting and iteration against objdiff. The README mentions that good first targets are small leaf functions, which suggests the process is tedious. The project is a work in progress, and the README does not state a percentage or a timeline. The scope is narrow: only the NTSC-U version is listed as matching, with no mention of PAL or Japanese releases. The README mentions matching .rel overlays as part of the goal, but the status table only lists the primary boot ELF. Overlays are not yet addressed, which means the decompilation is incomplete even for the NTSC-U version. The project also has no port, so the resulting source tree is not directly runnable on modern hardware. If you want to study the game's logic, you must be comfortable reading C that is written to match specific compiler output, which can be unnatural. The code is not written for readability; it is written for byte identity. That makes it a poor resource for learning game architecture unless you already understand the original assembly.

The Alternative: Non-Matching Decompilation

A real alternative is a non-matching decompilation, such as the approach used by many open-source reimplementations of old games. In a non-matching decomp, the goal is to produce C code that behaves the same as the original, but not necessarily with identical bytes. The compiler can be modern, the code can be clean, and the build can run on current platforms. Projects like OpenGOAL for Jak and Daxter, or the many PC ports of classic games, take this route. The difference is fundamental: a matching decomp is a forensic exercise, a non-matching decomp is a functional one. For God Hand specifically, a non-matching decomp could produce a playable port on PC or other platforms, which this project explicitly does not do. The trade-off is that a non-matching decomp cannot verify its fidelity as strictly; you rely on gameplay testing rather than byte comparison. For preservation, matching is stronger because it proves the source is a perfect representation of the original. For practical use, non-matching is more useful. This project chooses the former, and that choice defines its audience and its limitations.

Maintenance, Licensing, and the Bottom Line

The project is licensed under MIT, which is permissive for the decompiled source. However, the README stresses that no copyrighted Capcom or Sony assets are included, and the original SDK binaries are not redistributed. The setup script downloads them from community archives, which raises a practical maintenance concern: if those archives go offline, the project cannot build. The repo itself is not archived, but the last push is unknown, and there are no recent releases. That suggests the project may be in a low-activity state. The README mentions a decomp.dev page for live progress, which is a good sign for transparency, but the lack of releases means you must build from source. The git hooks and the ratchet ensure that any commit keeps the ELF byte-identical, which is a strong quality gate. For a contributor, the cost is learning the matching loop and the specific toolchain. For a user, there is nothing to use yet. The project's value is in its process and its potential to produce a verified source tree. If you are not interested in the process, there is no reason to adopt it. If you are, the first step is to verify your environment can reproduce the retail sha256, as the README instructs. That is the concrete entry point.

Editorial conclusion

Adopt this project if you are a contributor interested in PS2 reverse engineering, matching decompilation, or the specific challenge of ee-gcc 2.96 codegen. Do not adopt it if you expect a playable port, a quick win, or a codebase that runs on modern hardware. Before contributing, verify that your local environment can reproduce the retail sha256 from an empty carve, as the README describes, and confirm you have a legal NTSC-U disc dump. The project's value is in the process and the resulting source tree, not in any runtime artifact. It is a preservation and education effort, and its success will be measured by the byte-identical ELF, not by user-facing features.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. README
4. Releases