How davidsm64/diddy-kong-racing works
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