Once your environment is set up, building the game takes three steps: placing a verified base ROM, runningDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/pmret/papermario/llms.txt
Use this file to discover all available pages before exploring further.
./configure to extract assets and set up the build system, and running ninja to compile. A successful build ends with papermario.z64: OK, confirming the output matches the original ROM byte-for-byte.
You need at least one original Paper Mario ROM to build the project. The project supports four regional versions — you can build whichever versions you have ROMs for.
Supported versions and SHA1 hashes
Place your ROM(s) at the paths shown below. The file must match the expected SHA1 hash exactly; a ROM that has been modified or obtained from an unofficial source will cause the build to fail.| Region | ROM path | SHA1 hash |
|---|---|---|
| US | ver/us/baserom.z64 | 3837f44cda784b466c9a2d99df70d77c322b97a0 |
| JP | ver/jp/baserom.z64 | b9cca3ff260b9ff427d981626b82f96de73586d3 |
| PAL | ver/pal/baserom.z64 | 2111d39265a317414d359e35a7d971c4dfa5f9e1 |
| iQue | ver/ique/baserom.z64 | 5c724685085eba796537573dd6f84aaddedc8582 |
If you are using WSL 2, you can browse to the Linux filesystem from Windows Explorer at
\\wsl$\Ubuntu\home\<your username>\papermario to copy ROM files into the correct location.Build steps
Place the base ROM
Copy at least one verified ROM into the repository at its corresponding path. For example, for the US version:Repeat for any additional regional versions you want to build.
Configure the build
Run the configure script to detect which versions you have, extract assets from the ROM, and generate the Ninja build files:You must re-run
./configure whenever you rename or delete source files, create new source files, or migrate data from a .data.s file into C. If ninja breaks after a git pull, re-running ./configure usually fixes it.Compile the game
Run Ninja to compile all source files and link the ROM:If the build succeeds and the output matches the base ROM, you will see:If you see
FAIL instead, the compiled output does not match the original. This typically means a function is not yet matched and is still represented as raw assembly.What papermario.z64: OK means
After linking, the build system runs a SHA1 checksum comparison between the freshly compiled ROM and the base ROM you placed in the repository. OK means the two files are identical — every byte matches. This is the core goal of the decompilation project: not just equivalent behavior, but an exact binary match.
The compiled ROM is written to ver/<version>/build/papermario.z64.
Before contributing
If you use Visual Studio Code, you can use Run Build Task (Ctrl+Shift+B) to run ninja. Compiler errors and warnings appear in the Problems tab.