zeldaret/mm: Building the US N64 Majora's Mask Decompilation

What zeldaret/mm Reconstructs and Who Can Use It

zeldaret/mm addresses source reconstruction for The Legend of Zelda: Majora's Mask version 1.0 for the Nintendo 64. The project says its purpose is to recreate a source code base from scratch using information found in the game together with static or dynamic analysis. Its intended users are people who want to inspect the game's implementation, work on decompilation, investigate matching behavior, or attempt modifications at the source level.

This is not a reimplementation with a new runtime and it is not a PC port. The README explicitly says the project is not intended to produce one. Its current support is limited to the US N64 release. Although the project aims eventually to support every retail version of the original game, that does not mean other retail versions, or the remake described in the README as a different game, are currently supported.

The project presents itself as work in progress. It says some changes are already possible, but warns that the codebase could change drastically and that parts of the ROM may not yet be shiftable. That warning matters for modders because a source-level change does not necessarily translate into an easy ROM modification at this stage. Decompilation status can differ by function and section, so the repository is better suited to contributors who understand matching work than to someone expecting a stable modding SDK.

From Base ROM to Matching Output in the mm Build

The repository does not contain the assets or assembly code needed for a complete independent build. Instead, the documented pipeline starts with a user-supplied US ROM. The Makefile exposes settings such as VERSION, COMPARE, NON_MATCHING, ORIG_COMPILER, COMPILER, WERROR, RUN_CC_CHECK, and OBJDUMP_BUILD. The documented default target is VERSION=n64-us, while COMPARE defaults to 1 so the build checks the resulting checksum.

The documented build has five broad stages. It creates a Python virtual environment, installs tools from pip, and compiles build utilities. It then decompresses the supplied ROM, extracts individual files, and expands archives. Assets are extracted according to XML files under assets/xml. Code-containing files are disassembled, including data, rodata, and bss. Finally, the project compiles code and assets and generates both an uncompressed and compressed ROM.

This workflow explains why a prior copy of the game is required. The repository supplies decompiled source, specifications, scripts, and build logic, but the initial build still needs original content to recover assets and establish the matching baseline. For decompilation work, the README also identifies an assembler differ: expected files are copied during initialization so code can be compared during function matching. Matching is therefore part of the normal development loop, not merely a checksum performed after packaging.

Linux Setup and the First mm ROM Build

The clearest installation route in the README is Debian or Ubuntu, either natively or through WSL or a virtual machine. On Windows 10, the README directs users through the Windows Subsystem for Linux guide and recommends Debian or Ubuntu 20.04. Separate preparation documents cover macOS and Docker.

Install the documented Linux packages first. These include the GNU toolchain, Python environment tools, and image and XML development libraries:

sudo apt update
sudo apt install git build-essential binutils-mips-linux-gnu curl python3 python3-pip python3-venv libpng-dev libxml2-dev

The README asks contributors to create their own fork and clone it. Replace the placeholder with your GitHub username exactly as shown:

git clone https://github.com/<YOUR_USERNAME>/mm.git
cd mm

Next, place a US copy of the game in baseroms/n64-us/. Rename the file according to its original extension, using baserom.z64, baserom.n64, or baserom.v64. No original game file is included in this repository.

Run the initialization target for the first build, replacing N with the processor core count:

make init -j N

On success, the README expects matching output at build/n64-us/mm-n64-us.z64 and build/n64-us/mm-n64-us-compressed.z64. The terminal should report each as OK. Subsequent builds can use make -j N instead of repeating initialization. For easier diagnosis, the README notes that parallel output can become scrambled, so developers may prefer a single job when investigating a failure.

Matching Constraints and ROM Modification Boundaries

A failed checksum is a meaningful signal in this project, but the README does not treat it as a black-box installation problem. If a build reports FAILED and md5sum says that one computed checksum did not match, the documented causes are an incorrect base ROM or code that does not match. That makes checksum comparison part of judging whether the reconstructed source is correct.

The supported reference outputs are explicitly identified. The uncompressed mm-n64-us.z64 target has md5 f46493eaa0628827dbd6ad3ecd8d65d6, while mm-n64-us-compressed.z64 has md5 2a0a8acb61538235bc1094d297fb6556. These values describe the project's expected artifacts. They do not remove the need for a legally obtained source ROM because the repository still requires the user's own copy for extraction.

There is also a difference between successful compilation and practical modding. The README warns that parts of the ROM may not be shiftable yet. Modifying those parts can therefore be difficult even when the source file can be edited. NON_MATCHING can be set to 1 in the Makefile, but the default comparison behavior centers on reproducing the target rather than accepting arbitrary differences. Users seeking immediate, convenient modification of arbitrary game data may find this project unsuitable until the relevant sections are matchable and movable.

Docker Support and the Custom Build Toolchain

The repository includes a Dockerfile based on ubuntu:24.04 and links to separate Docker preparation documentation. Its container installs native build dependencies, the MIPS GCC toolchain, Python tools, Git, wget, unzip, vbindiff, Vim, clang-format-14, clang-tidy-14, libpng-dev, and practicerom-dev. It also adds a PracticeRom package repository before installing dependencies.

That container is not a prebuilt game image. Its WORKDIR is /mm, and its entry point opens Bash for further work. Based on the repository layout, the source tree includes src for code, include for headers, assets for extracted game assets, spec for build descriptions, tools for build and disassembly utilities, and linker_scripts for output layout. The Dockerfile provides an environment, while the Makefile and Python tools perform initialization, extraction, disassembly, compilation, and comparison.

The requirements file constrains important tools rather than pinning every dependency to one exact release. It includes colorama, crunch64, ipl3checksum, pyyaml, rabbitizer, spimdisasm, pyelftools, watchdog, argcomplete, Levenshtein, cxxfilt, pycparser, toml, and mapfile-parser. Some entries have major-version bounds, such as crunch64>=0.3.1,<1.0.0. The first `make init` phase downloads the necessary pip tools and compiles build utilities, so a normal Linux setup needs network access during initialization.

The Dockerfile also exposes an environment difference that matters when diagnosing failures. It installs gcc-mips-linux-gnu and practicerom-dev in addition to the native compiler and support packages listed in the README. That is useful context, but the Makefile still controls how the ROM is compiled, including whether IDO, an original compiler route, or GCC is selected.

Maintenance Signals, Licence Status, and Project Scope

The repository is not archived, and its last push was on 2026-10-11. There are no GitHub releases, so users cannot treat tagged releases as a defined upgrade channel from the available project record. The README calls the repository a work in progress and warns that its codebase could change drastically. That is the more important upgrade warning for contributors: moving to a later commit may alter project structure without providing a release-note migration path.

No licence identifier appears in the repository information, and the README does not state licensing terms. It would therefore be unsound to infer permission to redistribute the source, compiled ROMs, extracted assets, or original game data. The project requires users to supply their own copy of the US ROM and does not include the assets or assembly code necessary for compilation. Licence review is especially relevant when planning to publish a modified ROM or distribute extracted material, although this article does not provide legal advice.

A realistic alternative is an ordinary source port. A port would target a modern runtime and new platform while changing the implementation around the game. zeldaret/mm takes the opposite approach for its stated scope: reconstruct and compile the original N64 release so its output can match the reference ROM. For developers who need byte-level comparison or N64-oriented source analysis, that distinction is the deciding factor.

Editorial conclusion

Adopt zeldaret/mm if your work requires source-level inspection or matching modifications to the supported US N64 release. Do not choose it as a PC conversion project or expect stable modding interfaces immediately. Verify base ROM compatibility, toolchain availability, build output, and any function-specific matching requirements before committing substantial work.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. zeldaret/mm on GitHub