# davidsm64/diddy-kong-racing architecture

> Architecture diagram of the GitHub repository davidsm64/diddy-kong-racing, 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/davidsm64/diddy-kong-racing
- Repository: https://github.com/davidsm64/diddy-kong-racing

## Overview

##### Project Type & Purpose
- This is an open-source decompilation and rebuild pipeline for the N64 game “Diddy Kong Racing.”
- It supports extracting assets from an original ROM, rebuilding the game in C from decompiled code, tracking decompilation progress, and applying mods.

##### File-Structure Analysis
- Top-level:
- baseroms/ – holds original game ROM(s)
- src/ – decompiled C game code + hand-written ASM helpers
- /, libultra/ – headers and N64 system library sources
- tools/ – asset extraction & building tools (C++ builders, Python scripts, shell wrappers)
- mods/ – community mod assets & metadata
- extract-ver/ – version-specific JSON configs for extraction
- ver/ – verification data (YAML, SHA1, symbol tables)
- scripts (extract.sh, diff.sh, makefile targets) orchestrate the pipeline
- .github/workflows – CI for build verification and score updates

- Architectural Patterns:
- A monolithic repo with a domain-driven layout (assets vs. code vs. tools).
- A data-pipeline style asset extraction & build stage.
- A standard build pipeline using Makefiles and cross-compiler toolchains.
- CI pipelines to auto-verify matching builds and update decomp progress.

##### README Insights
- Describes a two-stage developer workflow:
A. extract assets from a binary ROM,
B. compile C/ASM code + linked libultra to produce a matching ROM build.
- Mentions submodules (libultra, tools), python venv setup, multiple ROM version support, and modding.

a. Main Components
1. Input (Original ROM in baseroms/)
2. Asset Extraction Layer
– extract-ver configs + extract.sh wrapper
– Python scripts & splat tool
– dkr_assets_tool_src (C++ extractor & builder)
3. Mods Overlay (mods/ folder with JSON metadata)
4. Asset Output (assets/ folder structure)
5. Build System
– Makefile / gcc-mips / IDO compiler
– src/ (C & ASM code) + include/ + libultra/
6. Verification & Diff Tools
– diff.sh, diff_settings.py, ver/ folder
7. CI/CD
– GitHub Actions workflows for build verification and score updates
8. Final Output (rebuilt ROM)

b. Relationships & Data Flow
- ROM → (extract.sh + splat + Python) → raw asset files
- raw asset files + mods → (dkr_assets_tool builder) → packaged assets
- packaged assets + src code → (Makefile, cross-compiler) → game binary
- game binary ↔ diff.sh/verification → ensure byte-exact match
- commits/triggers → GitHub Actions → automated build & scoring

c. Architectural Patterns & Principles
- Separation of concerns: asset pipeline vs. code compilation vs. mod overlay
- Pipeline stages chained via scripts & Make targets
- Reusable tools: C++ builders, Python helpers, shell wrappers
- Automated verification to enforce N64 matching

d. Key Technologies & Frameworks
- gcc-mips-linux-gnu, IDO compiler for assembly compatibility
- Make, GNU shell scripts for orchestration
- Python3 + libpcre2 for fast extraction
- C++17 (tools) with Third-party libs: Boost-like utilities (argparse.hpp), tiny_gltf, stb_image, ThreadPool
- GitHub Actions for CI

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Inputs
    baseroms["Original ROMs"]:::data
    ExtractConfigs["Extraction Configs (extract-ver/*.config.json)"]:::data
    ModsOverlay["Mods Overlay"]:::data

    %% Extraction Layer
    ExtractorWrapper["Extractor Wrapper (extract.sh)"]:::processing
    PythonHelpers["Python Extraction Helpers"]:::processing
    CxxExtractor["Asset Extractor (C++)"]:::processing
    RawAssets["Raw Asset Files"]:::data

    %% Asset Building
    BuilderCxx["Asset Builder (C++)"]:::processing
    PackagedAssets["Packaged Asset Outputs"]:::data

    %% Build Orchestration
    BuildOrch["Build System Orchestration"]:::processing

    %% Game Code Compilation
    subgraph "Game Code"
        srcCode["src/ (C source)"]:::code
        libultra["libultra/src/ & include/PR/"]:::code
        headers["include/ (common headers)"]:::code
    end
    GameCompile["Game Code Compilation\n(gcc-mips, IDO, libultra link)"]:::processing
    FinalROM["Rebuilt ROM"]:::data

    %% Verification
    Verifier["Verifier (diff.sh/CI)"]:::processing
    VerificationData["Verification Data (ver/)"]:::data

    %% CI/CD
    CICD["CI/CD Workflows"]:::ci

    %% Data Flow
    baseroms --> ExtractorWrapper
    ExtractConfigs --> ExtractorWrapper
    ExtractorWrapper --> PythonHelpers
    PythonHelpers --> CxxExtractor
    CxxExtractor --> RawAssets

    RawAssets --> BuilderCxx
    ModsOverlay --> BuilderCxx
    BuilderCxx --> PackagedAssets

    PackagedAssets --> BuildOrch
    BuildOrch --> GameCompile

    srcCode --> GameCompile
    libultra --> GameCompile
    headers --> GameCompile

    GameCompile --> FinalROM

    FinalROM --> Verifier
    VerificationData --> Verifier

    Verifier --> CICD
    GameCompile --> CICD

    %% Click Events
    click baseroms "https://github.com/davidsm64/diddy-kong-racing/tree/master/baseroms/"
    click ExtractConfigs "https://github.com/davidsm64/diddy-kong-racing/blob/master/extract-ver/*.config.json"
    click ExtractorWrapper "https://github.com/davidsm64/diddy-kong-racing/blob/master/extract.sh"
    click PythonHelpers "https://github.com/davidsm64/diddy-kong-racing/tree/master/tools/python/"
    click CxxExtractor "https://github.com/davidsm64/diddy-kong-racing/tree/master/tools/dkr_assets_tool_src/extract/"
    click ModsOverlay "https://github.com/davidsm64/diddy-kong-racing/tree/master/mods/"
    click BuilderCxx "https://github.com/davidsm64/diddy-kong-racing/tree/master/tools/dkr_assets_tool_src/builder/"
    click BuildOrch "https://github.com/davidsm64/diddy-kong-racing/tree/master/Makefile"
    click srcCode "https://github.com/davidsm64/diddy-kong-racing/tree/master/src/"
    click libultra "https://github.com/davidsm64/diddy-kong-racing/tree/master/libultra/src/"
    click headers "https://github.com/davidsm64/diddy-kong-racing/tree/master/include/"
    click Verifier "https://github.com/davidsm64/diddy-kong-racing/blob/master/diff.sh"
    click VerificationData "https://github.com/davidsm64/diddy-kong-racing/tree/master/ver/"
    click CICD "https://github.com/davidsm64/diddy-kong-racing/tree/master/.github/workflows/"

    %% Styles
    classDef data fill:#E0F7FA,stroke:#00796B,color:#004D40
    classDef processing fill:#E8F5E9,stroke:#2E7D32,color:#1B5E20
    classDef code fill:#FFF3E0,stroke:#EF6C00,color:#E65100
    classDef ci fill:#F3E5F5,stroke:#6A1B9A,color:#4A148C
```
