How n64decomp/perfect_dark works
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.