# n64decomp/mk64 architecture

> Architecture diagram of the GitHub repository n64decomp/mk64, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/n64decomp/mk64
- Repository: https://github.com/n64decomp/mk64

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Asset Pipeline
    subgraph "Asset Pipeline"
        direction TB
        YAML["YAML Metadata"]:::data
        ASSETS["assets/"]:::data
        MODELS["models/"]:::data
        ExtractScript["extract_assets.py"]:::tool
        ConvertScript["python_convert.py"]:::tool
        BlenderTools["tools/blender/"]:::tool
        NewExtract["tools/new_extract_assets.py"]:::tool
    end

    %% Codebase
    subgraph "Codebase"
        direction TB
        subgraph "Hand-written Assembly" 
            direction TB
            ASM["asm/"]:::source
            ASM_OS["asm/os/"]:::source
        end
        subgraph "Decompiled C Code"
            direction TB
            SRC["src/"]:::source
            Actors["src/actors/"]:::source
            Audio["src/audio/"]:::source
            Racing["src/racing/"]:::source
            OSsrc["src/os/"]:::source
            DataSrc["src/data/"]:::source
            Ending["src/ending/"]:::source
        end
        subgraph "Headers / Interfaces"
            direction TB
            Include["include/"]:::source
            PRInclude["include/PR/"]:::source
        end
    end

    %% Build System & Toolchain
    subgraph "Build & Toolchain" 
        direction TB
        Makefile["Makefile"]:::infra
        MakeSplit["Makefile.split"]:::infra
        SafeGCC["safe_gcc.mk"]:::infra
        UtilMK["util.mk"]:::infra
        LinkerLD["mk64.ld"]:::infra
        Dockerfile["Dockerfile"]:::infra
        IDORecomp["tools/ido-recomp/"]:::infra
    end

    %% Custom Tooling & Scripts
    subgraph "Custom Tooling & Scripts"
        direction TB
        ASMProc["tools/asm-processor/"]:::tool
        Bin2C["tools/bin2c.py"]:::tool
        Permuter["tools/decomp-permuter/"]:::tool
        DL_Packer["tools/displaylist_packer.c"]:::tool
        LibMIO0["tools/libmio0.c / libtkmk00.c"]:::tool
        LinkOnlyGen["tools/linkonly_generator.py"]:::tool
        MkGCCGen["tools/mkgccgen.py"]:::tool
        Checksum["tools/n64cksum.c"]:::tool
        Graphics["tools/n64graphics.c"]:::tool
        SetABI["tools/set_o32abi_bit.py"]:::tool
        WinBuild["tools/windows_build.py"]:::tool
        AddrSym["addr_to_sym.py"]:::tool
        DiffSettings["diff_settings.py"]:::tool
        FirstDiff["first-diff.py"]:::tool
        M2CHelper["m2c_helper.sh"]:::tool
        RenameSym["rename_sym.sh"]:::tool
    end

    %% Continuous Integration
    subgraph "Continuous Integration"
        direction TB
        CFmt[".github/workflows/clang-format.yml"]:::infra
        LinuxCI[".github/workflows/linux-compile.yml"]:::infra
        MacCI[".github/workflows/macos-compile.yml"]:::infra
        WinCI[".github/workflows/windows-compile.yml"]:::infra
        DoctestCI[".github/workflows/doxygen-and-linux-test.yml"]:::infra
        PrCI[".github/workflows/clang-pr.yml"]:::infra
        DockerCI["Dockerfile"]:::infra
    end

    %% Documentation Generator
    subgraph "Documentation"
        direction TB
        Doxy["Doxyfile"]:::docs
        DocsDir["docs/"]:::docs
        CSS["doxygen-awesome-css/"]:::docs
        SymGen["tools/doxygen_symbol_gen.py"]:::docs
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        LibUltra["libultra / PR libs"]:::ext
        LinkerLD2["mk64.ld"]:::infra
    end

    %% Output
    subgraph "Output"
        direction TB
        ROM_US["mk64.us.z64"]:::infra
        SHA1_US["mk64.us.sha1"]:::infra
        SHA1_EU10["mk64.eu.v10.sha1"]:::infra
        SHA1_EU11["mk64.eu.v11.sha1"]:::infra
    end

    %% Data Flow
    ExternalROM["Original N64 ROM"]:::ext
    ExternalROM -->|extract→| ExtractScript
    ExtractScript -->|generate→| YAML
    YAML -->|feeds→| ConvertScript
    ConvertScript -->|produce includes→| Include

    subgraph "Asset to Code"
        direction TB
        ASSETS -->|JSON→| ConvertScript
        MODELS -->|meta→| BlenderTools
        BlenderTools -->|export→| MODELS
    end

    %% Compilation Flow
    Include -->|include→| ASM
    Include -->|include→| SRC
    ASM -->|compile→| SafeGCC
    SRC -->|compile→| SafeGCC
    SafeGCC -->|object files→| LinkerLD
    IDORecomp -->|object files→| LinkerLD
    LinkerLD -->|link→| ROM_US

    %% Build Orchestration
    Makefile -->|orchestrates→| ExtractScript
    Makefile -->|orchestrates→| SafeGCC
    Makefile -->|orchestrates→| LinkerLD
    Makefile -->|orchestrates→| Doxy

    %% CI Pipeline
    CFmt -->|checks→| Makefile
    LinuxCI -->|runs→| DockerCI
    MacCI -->|runs→| DockerCI
    WinCI -->|runs→| DockerCI
    DoctestCI -->|generates→| DocsDir
    PrCI -->|validates→| Makefile

    %% Documentation Flow
    ASM -->|annotate→| Doxy
    SRC -->|annotate→| Doxy
    Doxy -->|generate→| DocsDir

    %% Click Events
    click YAML "https://github.com/n64decomp/mk64/tree/master/yamls/"
    click ASSETS "https://github.com/n64decomp/mk64/tree/master/assets/"
    click MODELS "https://github.com/n64decomp/mk64/tree/master/models/"
    click ExtractScript "https://github.com/n64decomp/mk64/blob/master/extract_assets.py"
    click ConvertScript "https://github.com/n64decomp/mk64/blob/master/python_convert.py"
    click BlenderTools "https://github.com/n64decomp/mk64/tree/master/tools/blender/"
    click NewExtract "https://github.com/n64decomp/mk64/blob/master/tools/new_extract_assets.py"
    click ASM "https://github.com/n64decomp/mk64/tree/master/asm/"
    click ASM_OS "https://github.com/n64decomp/mk64/tree/master/asm/os/"
    click SRC "https://github.com/n64decomp/mk64/tree/master/src/"
    click Actors "https://github.com/n64decomp/mk64/tree/master/src/actors/"
    click Audio "https://github.com/n64decomp/mk64/tree/master/src/audio/"
    click Racing "https://github.com/n64decomp/mk64/tree/master/src/racing/"
    click OSsrc "https://github.com/n64decomp/mk64/tree/master/src/os/"
    click DataSrc "https://github.com/n64decomp/mk64/tree/master/src/data/"
    click Ending "https://github.com/n64decomp/mk64/tree/master/src/ending/"
    click Include "https://github.com/n64decomp/mk64/tree/master/include/"
    click PRInclude "https://github.com/n64decomp/mk64/tree/master/include/PR/"
    click Makefile "https://github.com/n64decomp/mk64/tree/master/Makefile"
    click MakeSplit "https://github.com/n64decomp/mk64/blob/master/Makefile.split"
    click SafeGCC "https://github.com/n64decomp/mk64/blob/master/safe_gcc.mk"
    click UtilMK "https://github.com/n64decomp/mk64/blob/master/util.mk"
    click LinkerLD "https://github.com/n64decomp/mk64/blob/master/mk64.ld"
    click Dockerfile "https://github.com/n64decomp/mk64/tree/master/Dockerfile"
    click IDORecomp "https://github.com/n64decomp/mk64/tree/master/tools/ido-recomp/"
    click ASMProc "https://github.com/n64decomp/mk64/tree/master/tools/asm-processor/"
    click Bin2C "https://github.com/n64decomp/mk64/blob/master/tools/bin2c.py"
    click Permuter "https://github.com/n64decomp/mk64/tree/master/tools/decomp-permuter/"
    click DL_Packer "https://github.com/n64decomp/mk64/blob/master/tools/displaylist_packer.c"
    click LibMIO0 "https://github.com/n64decomp/mk64/blob/master/tools/libmio0.c / libtkmk00.c"
    click LinkOnlyGen "https://github.com/n64decomp/mk64/blob/master/tools/linkonly_generator.py"
    click MkGCCGen "https://github.com/n64decomp/mk64/blob/master/tools/mkgccgen.py"
    click Checksum "https://github.com/n64decomp/mk64/blob/master/tools/n64cksum.c"
    click Graphics "https://github.com/n64decomp/mk64/blob/master/tools/n64graphics.c"
    click SetABI "https://github.com/n64decomp/mk64/blob/master/tools/set_o32abi_bit.py"
    click WinBuild "https://github.com/n64decomp/mk64/blob/master/tools/windows_build.py"
    click AddrSym "https://github.com/n64decomp/mk64/blob/master/addr_to_sym.py"
    click DiffSettings "https://github.com/n64decomp/mk64/blob/master/diff_settings.py"
    click FirstDiff "https://github.com/n64decomp/mk64/blob/master/first-diff.py"
    click M2CHelper "https://github.com/n64decomp/mk64/blob/master/m2c_helper.sh"
    click RenameSym "https://github.com/n64decomp/mk64/blob/master/rename_sym.sh"
    click CFmt "https://github.com/n64decomp/mk64/blob/master/.github/workflows/clang-format.yml"
    click LinuxCI "https://github.com/n64decomp/mk64/blob/master/.github/workflows/linux-compile.yml"
    click MacCI "https://github.com/n64decomp/mk64/blob/master/.github/workflows/macos-compile.yml"
    click WinCI "https://github.com/n64decomp/mk64/blob/master/.github/workflows/windows-compile.yml"
    click DoctestCI "https://github.com/n64decomp/mk64/blob/master/.github/workflows/doxygen-and-linux-test.yml"
    click PrCI "https://github.com/n64decomp/mk64/blob/master/.github/workflows/clang-pr.yml"
    click DockerCI "https://github.com/n64decomp/mk64/tree/master/Dockerfile"
    click Doxy "https://github.com/n64decomp/mk64/tree/master/Doxyfile"
    click DocsDir "https://github.com/n64decomp/mk64/tree/master/docs/"
    click CSS "https://github.com/n64decomp/mk64/tree/master/doxygen-awesome-css/"
    click SymGen "https://github.com/n64decomp/mk64/blob/master/tools/doxygen_symbol_gen.py"

    %% Styles
    classDef source fill:#cce5ff,stroke:#004085,color:#004085
    classDef data fill:#d4edda,stroke:#155724,color:#155724
    classDef tool fill:#fff3cd,stroke:#856404,color:#856404
    classDef infra fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef docs fill:#f5c6cb,stroke:#721c24,color:#721c24
    classDef ext fill:#f8d7da,stroke:#721c24,color:#721c24
```
