# fgsfdsfgs/perfect_dark architecture

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

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

## Overview

##### Overall Architecture & Project Type
- It as a game port (a cross-platform game engine) that reuses a decompilation of the original game.
- Its purpose is to run “Perfect Dark” on modern hardware, handling ROM input, asset loading for different regions (NTSC, PAL, JPN), and providing improvements (mouselook, dual analog, 60 FPS and even 240 FPS modes, etc.).
- It is structured around a traditional game engine with a core loop and specialized systems: rendering, audio, input, game logic, and asset management.

- Build & Configuration Layer:
- CMake scripts (CMakeLists.txt and the cmake/ directory).
- Build tools and scripts (tools/*, build pipelines for each platform).
- Platform Abstraction Layer:
- “port” directory: contains graphics API adapters (OpenGL, SDL2, glad) and platform-specific glue code.
- “include” and “lib” directories: contain both original and platform-abstraction modules (such as the libultra adaptations and audio/DMA routines).
- Game Core / Engine Layer:
- “src/game”: Contains all game logic including the main game loop, physics, AI, update routines (files like mainmenu.c, game_loop files, player.c, collision routines, etc.).
- “src/lib”: Contains utility libraries and common functions such as matrix math, audio mixer (via minimp3), RNG, and memory management.
- Rendering and Graphics System:
- Graphics related code appears in “src/game”, “port/fast3d”, and “src/lib/ultra” (which includes fast3d implementations and interfacing with low-level graphics via SDL2/OpenGL).
- Audio System:
- Modules in “src/lib/naudio” and “src/lib/mp3” indicate the use of a custom audio mixer and MP3 decoding.
- There is also integration in “src/lib/ultra/audio” to manage the original audio engine expectations.
- Input & Controls:
- Input processing code is distributed in source files (e.g., src/game/pad.c) along with configuration for different controller types (keyboard, Xbox, N64 pad).
- Asset Loading & Management:
- The “src/assets” directory structure is extensive with subdirectories for multiple versions (ntsc, jpn, pal, beta etc.). These hold animations, textures, language files, and level data.
- Tools in “tools/assetmgr” help to preprocess and package assets.
- ROM Handling and Emulator-like Features:
- The ROM loading and identification logic is part of the initialization routines in the engine.
- External Libraries and Dependencies:
- SDL2 (in both “port/fast3d” and build instructions in README) for windowing, input, and audio.
- OpenGL (via glad, whichever is used on each platform).
- ZLib for compression tasks (as seen by checksums and gzip utilities in “tools/mkrom”).
- The build and patch tools from the “tools” directory that support ROM manipulation and asset processing.

##### Relationships and Interactions
- The Build Layer generates executables for different platforms using CMake, which then integrate the entire Engine.
- The Platform Abstraction Layer communicates with the OS via SDL2 and low-level graphics/audio libraries.
- The Game Core repeatedly calls into systems for rendering, audio, input handling, and game logic updates in each cycle of the game loop.
- The Asset Manager loads and parses platform-specific asset files (located in src/assets) and passes them to the game core.
- Input events from controllers/keyboard/mouse lead into the input processing system that updates player state.
- Use connectors to indicate that the engine subsystems (graphics, audio, input, game logic) interoperate closely inside the core game loop.

##### Architectural Patterns and Design Principles
- Cross-Platform Abstraction: Separation between hardware-specific code (in “port” and “cmake” directories) and game core logic (in “src/game” and “src/lib”).
- Modularization: Clearly delineated modules (graphics, audio, etc.) that maintain boundaries by interfacing through defined APIs (as seen in “include” directories).
- Build-Time Configuration: Use of CMake and multiple build profiles (driven by ROMID and platform-specific flags) to produce different binaries for NTSC, PAL, and JPN.

##### Elements
▪ Data flow from user ROM file and configuration (via “data” folder) into the game initialization routines.
▪ Interactions from the game engine to rendering and audio subsystems.

- Then graphically connect these modules by showing how the engine core (game loop) calls the interfaces provided by the abstraction layer which in turn communicates with the OS via SDL2 and OpenGL for graphics and audio.
- External dependencies (ROMs, configuration files, external libraries) clearly.

This detailed, modular approach encapsulates the architecture of the Perfect Dark port project and will provide a clear visual reference for developers to understand and extend the system.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & Configuration Layer
    subgraph "Build & Configuration Layer"
        A["CMake Build System"] 
        A2["CMake Scripts"]
        B["Build Tools & Scripts"]
    end

    %% Platform Abstraction Layer
    subgraph "Platform Abstraction Layer"
        C["Platform Abstraction"]
    end

    %% Game Core / Engine Layer
    subgraph "Game Core / Engine Layer"
        D["Game Core & Engine"]
    end

    %% Subsystems
    subgraph "Subsystems"
        E["Rendering & Graphics"]
        F1["Audio Mixer"]
        F2["MP3 Decoder"]
        F3["Legacy Audio Interface"]
        G1["Gamepad Input"]
        G2["Platform Input"]
        G3["Input Driver"]
        H["Asset Manager"]
        I["Asset Tools"]
        J["ROM Handling & Emulation"]
    end

    %% External Resources
    subgraph "External Resources"
        K["ROM File"]
        L["User Input"]
        M["Configuration File"]
        N["SDL2"]
        O["OpenGL"]
        P["ZLib"]
    end

    %% Relationships between Build & Configuration and Game Core
    A -->|"build"| D
    A2 -->|"scripts"| D
    B -->|"tools"| D

    %% Game Core interactions
    D -->|"calls"| E
    D -->|"calls"| F1
    D -->|"calls"| F2
    D -->|"calls"| F3
    D -->|"calls"| G1
    D -->|"calls"| H
    D -->|"initRom"| J
    D -->|"uses"| C
    D -->|"configures"| M

    %% Platform Abstraction provides APIs
    C -->|"APIs"| E
    C -->|"APIs"| G2
    C -->|"APIs"| G3
    N -->|"interfaces"| C

    %% Subsystem internal interactions
    I -->|"preprocess"| H

    %% External inputs
    K -->|"loads"| J
    L -->|"sends"| G1
    O -->|"graphics"| E
    P -->|"compression"| J

    %% Class Definitions with Colours
    classDef build fill:#f9e79f,stroke:#f39c12,stroke-width:2px;
    classDef platform fill:#aed6f1,stroke:#3498db,stroke-width:2px;
    classDef game fill:#a3e4d7,stroke:#1abc9c,stroke-width:2px;
    classDef subsystem fill:#f5b7b1,stroke:#e74c3c,stroke-width:2px;
    classDef external fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;

    %% Assign classes to nodes
    class A,A2,B build;
    class C platform;
    class D game;
    class E,F1,F2,F3,G1,G2,G3,H,I,J subsystem;
    class K,L,M,N,O,P external;

    %% Click Events for components
    click A "https://github.com/fgsfdsfgs/perfect_dark/blob/port/CMakeLists.txt"
    click A2 "https://github.com/fgsfdsfgs/perfect_dark/tree/port/cmake/"
    click B "https://github.com/fgsfdsfgs/perfect_dark/tree/port/tools/"
    click C "https://github.com/fgsfdsfgs/perfect_dark/tree/port/port/"
    click D "https://github.com/fgsfdsfgs/perfect_dark/tree/port/src/game/"
    click E "https://github.com/fgsfdsfgs/perfect_dark/tree/port/port/fast3d/"
    click F1 "https://github.com/fgsfdsfgs/perfect_dark/tree/port/src/lib/naudio/"
    click F2 "https://github.com/fgsfdsfgs/perfect_dark/tree/port/src/lib/mp3/"
    click F3 "https://github.com/fgsfdsfgs/perfect_dark/tree/port/src/lib/ultra/audio/"
    click G1 "https://github.com/fgsfdsfgs/perfect_dark/blob/port/src/game/pad.c"
    click G2 "https://github.com/fgsfdsfgs/perfect_dark/blob/port/port/include/input.h"
    click G3 "https://github.com/fgsfdsfgs/perfect_dark/blob/port/port/src/input.c"
    click H "https://github.com/fgsfdsfgs/perfect_dark/tree/port/src/assets/"
    click I "https://github.com/fgsfdsfgs/perfect_dark/tree/port/tools/assetmgr/"
    click J "https://github.com/fgsfdsfgs/perfect_dark/tree/port/tools/mkrom/"
```
