The project ships a set of Python scripts that support the decompilation workflow — from snapshotting the build to comparing assembly output to generating context files. This page documents each tool, its key flags, and when to reach for it.Documentation 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.
diff.py
diff.py is the primary tool you use during matching. It compares the original game’s MIPS assembly (left column) against the assembly produced by your C code (right column) and highlights differences.
Key flags
| Flag | Effect |
|---|---|
-m | Watch mode — recompiles and refreshes the diff every time you save the .c file |
-w | Automatically infers the source file to watch from the function name |
-o | Colourises output for easier reading |
-3 | Three-column diff: original (left), current (middle), previous saved (right) |
-b | Three-column diff: original (left), current (middle), version from when diff.py started (right) |
-h | Print full help and all available flags |
Example commands
Compare a function once and exit:m2ctx.py
m2ctx.py generates a context file (ctx.c) by preprocessing the C source file you’re working on. This context file contains all struct definitions, typedefs, and function prototypes that mips_to_c needs to produce accurate C output.
gcc -E with the project’s include paths and preprocessor flags, then writes the result to ctx.c in the repository root. Pass ctx.c to mips_to_c with --context ctx.c when running locally, or paste its contents into the lower box of the web version.
Run
m2ctx.py from the repository root. The path you pass should be relative to the repository root as well.make_expected.sh
make_expected.sh snapshots the current build as the reference that diff.py compares against. Run it once after you have a successful build:
ver/*/expected/ directories and then copies each version’s build/ directory into the corresponding expected/ directory:
ver/us/build/→ver/us/expected/ver/us/ver/jp/build/→ver/jp/expected/ver/jp/ver/ique/build/→ver/ique/expected/ver/ique/ver/pal/build/→ver/pal/expected/ver/pal/
make_expected.sh any time you pull upstream changes that affect the build, so the reference stays current.
coverage.py
coverage.py tracks which functions have been matched. After you’ve matched a function and verified it compiles, run:
.s assembly files from ver/us/asm/nonmatchings/ (and equivalent paths for other versions) that correspond to functions now implemented in C. Removing these files keeps the nonmatchings/ directories clean and makes it easy to see how much work remains.
Other tools
Thetools/ directory contains several additional scripts you may encounter:
| Script | Purpose |
|---|---|
rename.py | Renames a function across the codebase — updates the .c file, assembly references, and symbol address files consistently |
sym_info.py | Looks up information about a symbol (address, size, source file) from the build’s map file |
update_symbol_addrs.py | Updates symbol_addrs.txt after symbols are renamed or relocated |
-h to see their full usage.
VS Code integration
The project includes VS Code task definitions for the two most common operations:- Run Build Task (
Ctrl+Shift+B) — runsninjaand shows compiler errors and warnings in the Problems tab. - Run Test Task — runs
diff.pyfor the current function and shows compiler feedback inline.