Mickey's Speedway USA

This repo contains a decompilation of Mickey's Speedway USA for the N64. You need your own legally dumped copy of the ROM; nothing ROM-derived is committed here.

The US ROM (SHA1 507341c0a40ca3e9a7cee969b396ee53facfb548) is the matching target and rebuilds byte-identically today. PAL and JPN splat configs exist from the original stub but have not been modernized or verified.

Progress

functions       58 / 1467     3.95%   matched to C, byte-identical
.text bytes  14384 / 481380   2.99%   of the static resident segment
named          358 / 1467    24.40%   functions carrying an adopted name
symbols        382                    adopted in symbol_addrs.us.txt

Area	Functions	Matched to C	Named, still asm	Unnamed	Identified
libultra corridor	306	52	217	37	███▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░ 87.9%
game code, TU identified	74	6	46	22	██▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░ 70.3%
game code, not yet split	1087	0	37	1050	▓░░░░░░░░░░░░░░░░░░░ 3.4%
total	1467	58	300	1109	█▓▓▓▓░░░░░░░░░░░░░░░ 24.4%

█ matched to C · ▓ named but still assembly · ░ neither. Naming runs ahead of matching: a function is decompiled against an already-identified translation unit.

Matched so far: 46 C translation units that build byte-identically. 44 under src/libultra/; 2 under src/main/, including matrix.c (matrix/vector maths) and runlink.c (the runtime overlay linker core).

Generated by gmake scoreboard from the built ELF, the splat config, the asm/ tree and symbol_addrs.us.txt; gmake check-scoreboard fails if it has drifted. docs/modules.md records what each run of code was identified as and on what evidence; docs/references.md records the reference builds it was measured against.

Setup

Dependencies (macOS)

brew install make python3

Use gmake, Homebrew's GNU make: macOS's built-in make is too old.

splat (the disassembler/splitter) comes from requirements.txt via pip; no submodule is needed for the build itself.

tools/setup_toolchain.sh copies the MIPS binutils + IDO 5.3 toolchain from a local Diddy Kong Racing decomp checkout (DKR_PATH, default ~/Desktop/dev/Diddy-Kong-Racing). Without one: brew install mips64-elf-binutils, and take IDO 5.3 from the macOS build on decompals/ido-static-recomp's Releases page. The script documents both routes.

Baserom

Place your own legally dumped ROM at baseroms/mickey.us.z64. Expected SHA1s for all three regions are in mickey.*.sha1 and tools/verify_baseroms.sh.

Build

gmake setup   # venv, deps, toolchain, baserom SHA1 check, splat, git hooks
gmake -j8     # builds build/mickey.us.z64
gmake verify  # byte-compares it against the baserom SHA1

Checks

Command	Checks
gmake verify	the ROM rebuilds byte-identically
gmake cleanroom	no ROM-derived content (also run by the git hooks and CI)
gmake check-docs	derived numbers in the docs match the tree
gmake check-scoreboard	the Progress block matches the tree
gmake audit-decoders	the clean-room detectors aren't inventing words
gmake check-fixtures	the detectors still catch real ROM in every encoding
gmake check-reference-builds	the out-of-tree reference builds are the ones the names were mined from
gmake progress	matched functions/bytes/symbols

docs/CONTRIBUTING.md has the full table, including which are enforced and which need a build. check-scoreboard needs a linked ELF, which needs a baserom, so CI runs scoreboard.yml's --check-partial instead: the non-ELF-derived figures and the block's own arithmetic.

Decompiling

tools/asm-processor is required to build; it is what makes #pragma GLOBAL_ASM(...) work with IDO. tools/asm-differ (diff.sh) and tools/m2c (mips_to_c.sh, generate_ctx.sh) are the matching workflow and are not needed for gmake verify. tools/ido-static-recomp is left uninitialised; tools/setup_toolchain.sh installs a prebuilt IDO 5.3.

git submodule update --init tools/asm-processor tools/asm-differ tools/m2c

gmake setup runs that for you.

To add a translation unit: add it to mickey.*.yaml as a c subsegment, re-split (gmake does it automatically), and fill in src/. Every function starts as #pragma GLOBAL_ASM("asm/nonmatchings/<dir>/<func>.s"), which already builds byte-identically, and is replaced by C one function at a time.

./diff.sh <symbol>          # target vs. current disassembly; matched == no diffs
./diff.sh -mw <symbol>      # rebuild first, then re-diff on every file save
./generate_ctx.sh           # optional: ctx.c, so m2c knows project types
./mips_to_c.sh <symbol>     # m2c first draft into m2cfiles/<symbol>.c
gmake verify                # byte-identical or it does not count

C compiles with -O2 -mips1 -32 by default. Anything else is a per-file override in the Makefile's "Per-file compiler flags" block, justified in the source file's header comment. Measured per-file flags are in docs/modules.md §6.1.

Roadmap

Phase	Scope	State
0	Split the US ROM with splat; rebuild it byte-identically from disassembly	done
1	First matched C, libultra corridor, symbol/struct ontology	in progress
2	Clean-room gates; mine the published Rare decomps for matching objects	in progress
3	Overlay system: table format and ROM layout (settled), 107 overlay segments	in progress
4	Assets: 1172/1173 decompress/recompress with matching output	not started

Clean room

• No ROMs or extracted assets are committed.
• Names and adapted function bodies may come from the five named published retail-derived decomps, with a PROVENANCE note at the point of use. Leaked material is forbidden outright.
• docs/CLEANROOM.md is the policy, including what the automated gates do and do not catch.
• docs/CONTRIBUTING.md covers the commit/push gates that enforce it; gmake setup activates them.

Contributing

Read docs/CONTRIBUTING.md first, then docs/CLEANROOM.md. docs/modules.md is the module map and the evidence-tier convention every name follows; docs/references.md records the reference builds.

Credits

• Ryan-Myers, the original repository this project builds on, and the Jet Force Gemini decomp that most of the tier-A names here come from.
• The Diddy Kong Racing, Perfect Dark, Banjo-Kazooie and Conker's Bad Fur Day decomps.
• splat, asm-differ, asm-processor, m2c and ido-static-recomp.

License

CC0 1.0 Universal, covering this repository's own work only, not Rare's original code or any asset in the ROM.