How n64decomp/mk64 works
Project Type and Purpose
• This is a large-scale open-source decompilation project for the Nintendo 64 game “Mario Kart 64.”
• It reconstructs the original game code (in C and assembly), assets (textures, models, courses), and build tools to reproduce the original ROM bit-for-bit.
• The repository combines:
• Hand-written assembly and decompiled C code (src/, asm/)
• Asset definitions (assets/, models/, courses/, yamls/)
• Custom tooling (tools/, Python scripts)
• A cross-platform build pipeline (Makefiles, Dockerfile, CI workflows)
• Documentation generation (Doxygen, docs/)
Key Architectural Components
A. Source Code
• asm/: Hand-written assembly routines, OS boot, and exception stubs
• src/: Decompiled C code split into subsystems (actors, audio, racing engine, OS glue, etc.)
• /: Header files exposing interfaces to PR/ultra64 libs and game code
B. Data & Assets
• assets/, data/: Texture JSON, sound data, instrument sets
• courses/: Course geometry, display lists, staff-ghost models
• models/: 3D model definitions (common and track-specific)
• yamls/: Metadata driving automated conversion scripts
C. Tooling & Scripts
• tools/: Asset extractors, patchers, assembler differ, blender exporters, IDO re-compilers
• Python scripts (addr_to_sym.py, extract_assets.py, diff_settings.py)
• make targets and helper scripts (m2c_helper.sh, python_convert.py)
D. Build System & CI
• Top-level Makefile / Makefile.split orchestrating build, asset extraction, documentation
• safe_gcc.mk and IDO toolchain wrappers under tools/ido-recomp for original compiler emulation
• Dockerfile for consistent environment
• GitHub Actions workflows for Linux/macOS/Windows compile and format checks
E. Documentation
• Doxyfile + docs/ and docs/html generated by Doxygen
• Markdown tutorials under docs/ for contributors
Relationships & Data Flow
1. Input: Original N64 ROM → asset extraction scripts (extract_assets.py, first-diff.py) generate JSON, binary tables
2. Metadata (yamls/) + JSON asset definitions → conversion scripts → C/assembly include files under assets/include/ and data/
3. C/assembly sources (src/, asm/, generated includes) + headers (include/) → compiled by either safe_gcc or IDO toolchain
4. Linker (mk64.ld) stitches object files with libultra, PR libs → final ROM binaries (mk64.us.z64, mk64.eu.v10.z64, etc.)
5. Continuous Integration: runs make assets, make all, make doc in isolated Docker or OS VMs to validate cross-platform reproducibility
6. Documentation: source code annotated via Doxygen → docs/html site
Architectural Patterns and Principles
• Modular decomposition: subsystems are in distinct directories (actors, audio, racing, OS glue).
• Code-generation pipeline: metadata-driven asset → code conversion ensures consistency and bit-matching.
• Multi-toolchain support: ability to compile with original IDO or modern GCC (safe_gcc) fosters shiftability.
• Versioned assembly vs C: “asm/” holds handcrafted routines, “src/” hold decompiled code.
• Asset Pipeline (metadata, extractors, converters)
• Codebase (C modules, assembly modules, headers)
• Build & Toolchain (Makefile, safe_gcc, IDO wrappers)
• External Dependencies (original ROM, libultra/PR libraries)
• Output (final ROM binaries)
• Continuous Integration (Docker, GitHub Actions)
• Documentation Generator (Doxygen)
• Original ROM → Asset Extractors → JSON/YAML → Code-generation scripts → Generated includes
• C/ASM sources + includes → Compiler → Object files → Linker → ROM
• Makefile orchestrates all steps → triggers both asset pipeline and compilation
• CI pipeline → invokes Dockerfile + Make targets → validates build on multiple OSes
• Source annotations → Doxygen → docs/html
c. Important Patterns:
• Metadata-driven code generation cluster
• Dual toolchain paths (safe_gcc vs IDO)
• Separation of static assets (textures, models, courses) vs runtime code
• Documentation pipeline off to the side
d. Technologies and Frameworks:
• Python (extract_assets.py, diff scripts)
• Make (Makefile, safe_gcc.mk)
• Docker (Dockerfile)
• GitHub Actions (YAML workflows)
• Doxygen (Doxyfile, docs/)
• IDO Toolchain (tools/ido-recomp)