zeldaret/oot: The Community Decompilation of Ocarina of Time

What the Decompilation Project Produces and Why It Matters

zeldaret/oot reconstructs the C source code for The Legend of Zelda: Ocarina of Time from the original N64 and GameCube ROMs. The methodology combines static analysis of the compiled binary with dynamic analysis during gameplay, allowing contributors to reverse-engineer function signatures, data structures, and control flow back into readable C.

The end goal is a source base that compiles byte-for-byte to the original ROM checksums. The README tracks a comparison mode (COMPARE=1 in the Makefile) that checks the output MD5 hash against known ROM hashes after each build. This verification step is what distinguishes a decompilation from a reimplementation: the output must be identical to the original, not merely functionally equivalent.

The project explicitly states it is not producing a PC port. Port projects such as Ship of Harkinian (which the related searches reference) are separate efforts that use the decompiled output as a base, but that work happens outside this repository. This repository's purpose is the decompilation itself.

Progress is tracked publicly at zelda.deco.mp/games/oot, where a badge in the README reflects the current decompilation percentage.

Supported ROM Versions: 15 Builds from NTSC 1.0 to GameCube

The repository supports building 15 distinct ROM versions across N64 and GameCube releases. These include ntsc-1.0 (build timestamp 98-10-21), ntsc-1.1, pal-1.0, ntsc-1.2, pal-1.1, gc-jp, gc-jp-mq, gc-us, gc-us-mq, gc-eu-dbg-2, gc-eu-mq-dbg, gc-eu-dbg, gc-eu, gc-eu-mq, gc-jp-ce (GameCube Collector's Edition), and ique-cn (iQue Player Simplified Chinese). Each version is identified by a specific MD5 hash listed in the README.

The default build target is gc-eu-mq-dbg, the GameCube Europe/PAL Master Quest Debug ROM (build timestamp 03-02-21 00:16:31). This version is default because the debug build contains more symbol information that aids decompilation. Contributors can select a different version by passing VERSION= to the make command.

The Makefile exposes the VERSION setting alongside COMPARE, NON_MATCHING, ORIG_COMPILER, and COMPILER options. Setting NON_MATCHING=1 defines a preprocessor flag that allows the code to compile without requiring exact register-level matching, which is useful when writing ROM modifications that do not need to match the original binary.

Setting Up the Build: Linux, WSL, and Docker

The README recommends Linux or WSL on Windows, and notes that most contributors use WSL, Linux, and macOS. For Linux or WSL, the first step is installing build dependencies:

sudo apt-get update
sudo apt-get install git build-essential curl python3 python3-pip python3-venv libxml2-dev

Python 3.10 or later is required. Alongside system packages, a MIPS binutils installation is needed. The project supports several toolchains: mips64-ultra-elf or mips64 from the practicerom toolchain, mips64-elf from the libdragon n64 homebrew library, or mips-linux-gnu and mips64-linux-gnu from distribution package managers (for example, binutils-mips-linux-gnu on Debian or Ubuntu). The Makefile exposes MIPS_BINUTILS_PREFIX to set a custom toolchain prefix if none of the standard ones are available.

For Windows users who prefer not to set up WSL, the repository provides a Docker-based build path. The docker-compose.yml mounts the repository directory at /oot and runs the build inside a container:

services:
  oot:
    build:
      context: .
      dockerfile: Dockerfile
    volumes:
      - ./:/oot
    tty: true
    stdin_open: true

The Dockerfile is based on ubuntu:24.04 and installs binutils-mips-linux-gnu, Python 3, python3-pip, python3-venv, git, curl, clang-tidy, and clang-format. The WSL note in the README specifically warns to clone into the Linux filesystem using Linux's git rather than from the Windows filesystem, to avoid symlink and line-ending issues.

Python Dependencies and the Tooling Ecosystem

The build toolchain depends on several Python packages listed in requirements.txt. These cover decompression (crunch64 >= 0.5.1), ROM checksum tools (ipl3checksum >= 1.2.0), configuration (pyyaml >= 6.0.1), graphics decoding (pygfxd >= 1.0.3), assembly diffing (asm-differ, which uses argcomplete, colorama, cxxfilt, python-Levenshtein, watchdog), permuter tools (pycparser, toml), ELF analysis (pyelftools==0.30), and disassembly (rabbitizer >= 1.0.0, spimdisasm >= 1.28.1).

The repository includes diff.py and first_diff.py scripts for comparing assembly output between decompiled C and the original binary, which are the primary tools contributors use when working on an unmatched function. The sym_info.py script provides symbol lookup utilities.

The tools/ directory and scripts at the repository root support the decompilation workflow. The Doxyfile at the root suggests Doxygen is used for internal documentation generation, likely for the decompiled source headers in include/.

Limitations: Work in Progress, Not All Code Shiftable

The README includes a warning that the codebase can drastically change at any time. Some parts of the ROM are not yet shiftable, meaning that code in those sections cannot be freely relocated in the binary without breaking the expected layout. Modding projects that rely on specific addresses or code offsets in the decompiled source should account for this instability.

The repository does not include any game assets (textures, audio, scene data). A prior, legally owned copy of the game is required to extract those assets before building. The README lists the MD5 hashes of valid ROM inputs for each supported version; a ROM that does not match the expected hash will cause the build to fail.

There are no GitHub releases in this repository. The main branch represents the current decompilation state, which changes as contributors match more functions. Anyone building from a specific commit for modding purposes needs to track the exact commit hash rather than relying on a stable release tag.

The zeldaret/oot Decompilation vs. Ship of Harkinian

Ship of Harkinian is a separate project that takes the decompiled Ocarina of Time source as a base and ports it to run natively on PC operating systems (Windows, macOS, Linux). It is a PC port; zeldaret/oot is not. The two projects are related but distinct in purpose.

zeldaret/oot produces a ROM that is byte-for-byte identical to the original cartridge data. Ship of Harkinian takes that decompiled source and adapts it to run without the N64 hardware abstraction layer, replacing the original rendering and audio code with modern APIs. Someone who wants to play Ocarina of Time on a PC with widescreen and quality-of-life improvements uses Ship of Harkinian. Someone who wants to study the original game's C code, understand the original engine, or write ROM patches that compile from source uses zeldaret/oot.

The decompilation is a prerequisite for port projects, but the zeldaret/oot repository itself is scoped to the decompilation task only.

Editorial conclusion

zeldaret/oot suits developers who want to study the original Ocarina of Time game logic, understand how the N64 engine worked at the source level, or create ROM modifications with access to the decompiled C codebase. It requires a legally owned copy of the game to build, a MIPS binutils toolchain, and Python 3.10 or later. The codebase can change dramatically at any time, so modding projects that depend on specific symbol offsets or code structure should treat any given commit as unstable until the decompilation reaches completion.

Frequently asked questions

Official sources

1. Issues
2. README
3. zeldaret/oot on GitHub