# n64decomp/perfect_dark architecture

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

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

## Overview

##### Project Type and Purpose
- It is a matching decompilation project – an effort to reconstruct the original Perfect Dark codebase so that when compiled with the same tools and settings, the output ROM is byte-for-byte identical to the original.
- The project combines low‐level MIPS/assembly code, C source files, and a large body of supporting assets (graphics, audio, language files, etc.) that are extracted from an original ROM. It uses a Makefile-based build process.

##### High-Level Components
- Build System and Tools:
– The Makefile at the project root orchestrates the overall build process.
– Tools directory: Contains various auxiliary tools (like assetmgr, mkrom, mktextures, and other scripts) that process assets, manage asset extraction, and aid in creating the final ROM image.
– Submodules and configuration tools such as armips, MIPS gcc, and binutils form part of the external toolchain.
- Asset Extraction and Management:
– Base ROM file (for example, “pd.ntsc-final.z64”) is placed in the root.
– Asset extraction (make extract) pulls assets and language files into src/assets. Note that assets are organized by ROM version (jpn-final, ntsc-1.0, ntsc-beta, etc.).
- Source Code Layers:
– “src/”: Contains all the core source code organized into logical subdirectories:
- Game: Contains the game logic and engine code (handling graphics, gameplay, audio, physics, etc.).
- lib: Contains libraries that use both assembly and C, including utility functions, math, graphics libraries (e.g. ultra64 headers and files), audio (naudio), and others.
- rsp and romheader directories: Handle platform-specific initialization and boot code.
- setups and modeldata directories: Provide initialization for different game modules or multiplayer settings.
- Other directories like “preamble”, “setups”, “stubs” also show layers of initialization, fallback implementations and test code.
- Directories:
– “include/”: Contains header files that are split into system headers (for both the proprietary PR and system-level functions) as well as project-specific include files for game, lib, and assets.
- Build Outputs:
– The linking process (driven by files in “ld” directory and configuration files in “make”) results in the final ROM (“build/ntsc-final/pd.z64”).
– There is also an “extracted” directory that holds segments from the original ROM for comparison.

##### Relationships and Data Flow
- The Makefile orchestrates compiling source code (from the “src” folder, using headers in “include” and libraries in “lib”), linking (through linker script definitions in “ld”), and subsequently producing the final ROM image.
- The “tools” are auxiliary and sit outside of the main source but are invoked during asset preparation, ROM packaging, and testing (make test for matching).
- External dependencies (MIPS gcc, binutils, armips) are shown as an external toolchain that the build process depends upon.

##### Architectural Patterns and Design Principles
- Separation of concerns: There is a clear split between source code (game logic, engines, initialization, etc.), asset processing, and build tools.
- Modular organization: Each system (game, lib, audio, graphics, input, etc.) is isolated in its own set of directories to facilitate verification and matching.
- Build Reproducibility: The use of a matching decompilation process means that low-level code and the asset extraction phases are designed to ensure exact byte-for-byte ROM matches.

##### Detailed Step-by-Step for the Principal Software Engineer
1. Start by drawing a high-level flowchart that shows:
- External Inputs (Original ROM, External Build Tools)
- Pre-processing/Asset Extraction (make extract process)
- Compilation Process:
– Source code and headers in src and include directories.
– Library code in lib, and low-level system code such as rsp, romheader.
– Utilization of linker scripts from the ld directory.
- Final Linking and Output (Final ROM in the build/ directory).
– For example, blue for the build system and tools, green for core game logic, orange for libraries, and grey for assets.
5. Edges with dependencies – indicate “calls”, “builds”, “extracts”, “links” as appropriate.
6. Every major directory group (as seen in the file tree) is represented.
7. That this architecture is designed for a strict matching decompilation, so precision in the build and asset pipelines is critical.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Inputs
    subgraph "External Inputs"
        A["Original ROM (pd.ntsc-final.z64)"]:::asset
        B["External Toolchain (MIPS GCC, binutils, armips)"]:::external
    end

    %% Asset Management
    subgraph "Asset Management"
        C["Asset Extraction Process (make extract)"]:::tools
        D["Assets (src/assets)"]:::asset
        E["Asset Manager Tools"]:::tools
    end

    %% Build System
    subgraph "Build System"
        F["Build Orchestrator (Makefile)"]:::tools
        G["Auxiliary Build Tools (tools)"]:::tools
        H["Linker Scripts (ld)"]:::tools
    end

    %% Source Code Compilation
    subgraph "Source Code Compilation"
        I["Game Engine Core (src/game)"]:::game
        J["Library Code (src/lib)"]:::lib
        K["RSP Initialization (src/rsp)"]:::lib
        L["ROM Header (src/romheader)"]:::lib
        M["Pre-Init (src/preamble)"]:::lib
        N["Setup Modules (src/setups)"]:::lib
        O["Header Files (include)"]:::header
    end

    %% Final Output
    subgraph "Final Output"
        P["Final ROM Output (build/ntsc-final/pd.z64)"]:::tools
    end

    %% Connections between External Inputs and Build System
    A -->|"provides"| C
    B -->|"supports"| F
    G -->|"assists"| F

    %% Asset extraction flow
    C -->|"extracts"| D
    C -->|"invokes"| E
    D -->|"integrated into"| F

    %% Build orchestrator triggers compilation of source components
    F -->|"compiles"| I
    F -->|"compiles"| J
    F -->|"compiles"| K
    F -->|"compiles"| L
    F -->|"compiles"| M
    F -->|"compiles"| N
    F -->|"includes"| O

    %% Compilation outputs are linked
    I -->|"links"| H
    J -->|"links"| H
    K -->|"links"| H
    L -->|"links"| H
    M -->|"links"| H
    N -->|"links"| H
    O -->|"links"| H

    %% Linking produces final ROM output
    H -->|"builds"| P

    %% Styles
    classDef external fill:#EEE8AA,stroke:#000,stroke-width:2px;
    classDef tools fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef game fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef lib fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef asset fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef header fill:#F0E68C,stroke:#000,stroke-width:2px;

    %% Click Events
    click F "https://github.com/n64decomp/perfect_dark/tree/master/Makefile"
    click H "https://github.com/n64decomp/perfect_dark/tree/master/ld/"
    click G "https://github.com/n64decomp/perfect_dark/tree/master/tools/"
    click E "https://github.com/n64decomp/perfect_dark/tree/master/tools/assetmgr"
    click D "https://github.com/n64decomp/perfect_dark/tree/master/src/assets"
    click I "https://github.com/n64decomp/perfect_dark/tree/master/src/game"
    click J "https://github.com/n64decomp/perfect_dark/tree/master/src/lib"
    click K "https://github.com/n64decomp/perfect_dark/tree/master/src/rsp"
    click L "https://github.com/n64decomp/perfect_dark/tree/master/src/romheader"
    click N "https://github.com/n64decomp/perfect_dark/tree/master/src/setups"
    click O "https://github.com/n64decomp/perfect_dark/tree/master/include/"
    click M "https://github.com/n64decomp/perfect_dark/tree/master/src/preamble"
```
