# videogamepreservation/dukenukem3d architecture

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

- Interactive diagram: https://gitdiagram.com/videogamepreservation/dukenukem3d
- Repository: https://github.com/videogamepreservation/dukenukem3d

## Overview

##### Main Components
- Game Engine & Core Logic:
- Represented by source code in directories like SRC and source. Files such as ENGINE.C/ENGINE.OBJ, GAME.C, and other support files (e.g., BUILD.H, PRAGMAS.H) illustrate the core game loop, physics, and overall game logic.
- Also, files in extras and kenbuild_data hint at legacy or experimental features that relate to the main engine.
- Build Engine:
- The Duke 3D game is built upon Ken Silverman’s Build Engine. Although some of the build engine code is integrated into the source (via .OBJ and .H files) and partially provided in its own separate archive (e.g., BUILD.TXT, BUILDINF.TXT), it is a distinct module. Make sure to show the interaction between the game logic and the Build Engine that handles rendering, geometry, and level design.
- Audio Library:
- The entire audiolib directory is dedicated to the sound system. It contains subdirectories for source code (SOURCING the audio routines), precompiled objects, libraries (LIB & OBJ), and even utility batch files. This module is responsible for sound effects, music, and even networking considerations related to audio.
- Utility Tools & Extras:
- The UTIL folder includes source code for map conversion, asset extraction, and configuration setup. The extras folder and kenbuild_data include older versions or experimental code that might serve educational or optional purposes.
- Test Data & External Assets:
- The testdata directory stores configuration and demo files used to test the game.
- The release also includes documentation (READMEs, GNU.TXT) and build scripts (MAKEFILEs). These elements, while not “runtime” components, are important for the build and deployment pipelines.

##### Relationships and Interactions
- Utility modules (from UTIL and extras) are often used during development or for level and asset processing. Therefore, these can be depicted as standalone tools or helper services that feed processed data (e.g., maps and art assets) into the Game Engine.
- The configuration and compiling infrastructure (the Makefiles and build scripts) should be noted as supporting processes that bind together the various modules into the final executable (DUKE3D.EXE).

##### Architectural Patterns/Design Principles
- Build and Deployment Pipeline: Show that the Makefiles compile the different modules and link them together. You might also note that the project uses external components (such as DOS/4GW and Watcom assemblies) which need to be bound during the distribution process.

##### Relevant Technologies, Frameworks, and Libraries
- Watcom C/C++ Compiler: The README details how the project is built using Watcom (or Open Watcom). This is an important part of the build chain.
- DOS/4GW Extender: Since Duke3D is a DOS game, the extender is critical. Even though its source isn’t included, it plays a part in running the final executable on modern systems.
- Assembly Files: Notice files like A.ASM, K.ASM, and various .ASM files in the Build Engine and audio modules. These indicate performance-critical routines that interact closely with hardware.

- Clearly labeled modules for:
- Game Core/Engine (from SRC and source folders)
- Build Engine (representation of rendering, level handling)
- Audio Library (complete audiolib breakdown)
- Utility/Extra Tools (UTIL, extras folders)
- External Dependencies (DOS/4GW, Make/Build Tools)
- Data and control flow from the Game Engine → Build Engine (rendering calls)
- Event-driven calls from the Game Engine → Audio Library (sound events)
- Data asset pipelines from Utility Tools → Game Engine
- Build-time processes aggregating distributed components into DUKE3D.EXE
- Runtime execution modules (e.g., rectangles for game core, ovals for audio/graphics engines)
- Development/build modules (e.g., hexagons or clouds for utilities and external tools)
- Labels for:
- Source code directories that are tied to specific behaviors (e.g., game input from keyboards, network handling, etc.)

## Diagram (Mermaid)

```mermaid
graph TD

    %% Modules as Subgraphs

    subgraph "Game Engine & Core"
        GEContainer["Game Engine & Core"]:::engine
        GE1["ENGINE.C"]:::engineFile
        GE2["GAME.C"]:::engineFile
        GE3["PRAGMAS.H"]:::engineFile
        GE4["KDMENG.C"]:::engineFile
        GE5["CACHE1D.C"]:::engineFile
        GE6["ENGINE.OBJ"]:::engineFile
        GE7["GAME.C (source)"]:::engineFile
        GE8["GAMEDEF.C"]:::engineFile
        GE9["GLOBAL.C"]:::engineFile
        GE10["PLAYER.C"]:::engineFile
    end

    subgraph "Build Engine"
        BEContainer["Build Engine"]:::build
        BE1["BUILD.C"]:::buildFile
        BE2["BUILD.H"]:::buildFile
        BE3["BUILD.TXT"]:::buildFile
        BE4["BUILD2.TXT"]:::buildFile
        BE5["BUILDINF.TXT"]:::buildFile
        BE6["BUILD.H (source)"]:::buildFile
    end

    subgraph "Audio Library"
        ALContainer["Audio Library"]:::audio
        AL1["audiolib (directory)"]:::audioFile
    end

    subgraph "Utility Tools & Extras"
        UTContainer["Utility Tools & Extras"]:::utility
        UT1["UTIL Tools"]:::utilityFile
        UT2["Extras"]:::utilityFile
        UT3["KenBuild Data"]:::utilityFile
    end

    subgraph "Test Data & External Assets"
        TDContainer["Test Data & External Assets"]:::test
        TD1["TestData"]:::testFile
    end

    subgraph "Build & Deployment Infrastructure"
        BIContainer["Build & Deployment Infrastructure"]:::buildInfra
        BI1["MAKEFILE (SRC)"]:::buildInfraFile
        BI2["MAKEFILE (source)"]:::buildInfraFile
        BI3["AUDIO.MAK"]:::buildInfraFile
        BI4["AUDIO2.MAK"]:::buildInfraFile
        BI5["WMAKE.BAT"]:::buildInfraFile
        BI6["Documentation"]:::buildInfraFile
    end

    %% External Dependencies and Final Artifact
    WC["Watcom C/C++ Compiler"]:::external
    D4GW["DOS/4GW Extender"]:::external
    EXE["DUKE3D.EXE"]:::executable

    %% Inter-Module Relationships
    GEContainer -->|"render_calls"| BEContainer
    GEContainer -->|"sound_API_calls"| ALContainer
    UTContainer -->|"asset_pipeline"| GEContainer

    %% All modules contribute to the build process
    GEContainer -->|"build"| BIContainer
    BEContainer -->|"build"| BIContainer
    ALContainer -->|"build"| BIContainer
    UTContainer -->|"build"| BIContainer
    TDContainer -->|"build"| BIContainer

    BIContainer -->|"linked"| EXE
    BIContainer -->|"compiled_by"| WC
    BIContainer -->|"bound_to"| D4GW

    %% Click Events for Game Engine & Core Files
    click GE1 "https://github.com/videogamepreservation/dukenukem3d/blob/master/SRC/ENGINE.C"
    click GE2 "https://github.com/videogamepreservation/dukenukem3d/blob/master/SRC/GAME.C"
    click GE3 "https://github.com/videogamepreservation/dukenukem3d/blob/master/SRC/PRAGMAS.H"
    click GE4 "https://github.com/videogamepreservation/dukenukem3d/blob/master/SRC/KDMENG.C"
    click GE5 "https://github.com/videogamepreservation/dukenukem3d/blob/master/SRC/CACHE1D.C"
    click GE6 "https://github.com/videogamepreservation/dukenukem3d/blob/master/source/ENGINE.OBJ"
    click GE7 "https://github.com/videogamepreservation/dukenukem3d/blob/master/source/GAME.C"
    click GE8 "https://github.com/videogamepreservation/dukenukem3d/blob/master/source/GAMEDEF.C"
    click GE9 "https://github.com/videogamepreservation/dukenukem3d/blob/master/source/GLOBAL.C"
    click GE10 "https://github.com/videogamepreservation/dukenukem3d/blob/master/source/PLAYER.C"

    %% Click Events for Build Engine Files
    click BE1 "https://github.com/videogamepreservation/dukenukem3d/blob/master/SRC/BUILD.C"
    click BE2 "https://github.com/videogamepreservation/dukenukem3d/blob/master/SRC/BUILD.H"
    click BE3 "https://github.com/videogamepreservation/dukenukem3d/blob/master/SRC/BUILD.TXT"
    click BE4 "https://github.com/videogamepreservation/dukenukem3d/blob/master/SRC/BUILD2.TXT"
    click BE5 "https://github.com/videogamepreservation/dukenukem3d/blob/master/SRC/BUILDINF.TXT"
    click BE6 "https://github.com/videogamepreservation/dukenukem3d/blob/master/source/BUILD.H"

    %% Click Event for Audio Library Directory
    click AL1 "https://github.com/videogamepreservation/dukenukem3d/tree/master/audiolib/"

    %% Click Events for Utility Tools & Extras
    click UT1 "https://github.com/videogamepreservation/dukenukem3d/tree/master/UTIL/"
    click UT2 "https://github.com/videogamepreservation/dukenukem3d/tree/master/extras/"
    click UT3 "https://github.com/videogamepreservation/dukenukem3d/tree/master/kenbuild_data/"

    %% Click Event for Test Data Directory
    click TD1 "https://github.com/videogamepreservation/dukenukem3d/tree/master/testdata/"

    %% Click Events for Build & Deployment Infrastructure Files
    click BI1 "https://github.com/videogamepreservation/dukenukem3d/tree/master/SRC/MAKEFILE"
    click BI2 "https://github.com/videogamepreservation/dukenukem3d/tree/master/source/MAKEFILE"
    click BI3 "https://github.com/videogamepreservation/dukenukem3d/blob/master/audiolib/AUDIO.MAK"
    click BI4 "https://github.com/videogamepreservation/dukenukem3d/blob/master/audiolib/AUDIO2.MAK"
    click BI5 "https://github.com/videogamepreservation/dukenukem3d/blob/master/audiolib/WMAKE.BAT"
    click BI6 "https://github.com/videogamepreservation/dukenukem3d/blob/master/README.TXT"

    %% Styles
    classDef engine fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef engineFile fill:#D6EAF8,stroke:#1B4F72,stroke-width:1px;
    classDef build fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef buildFile fill:#E9F7EF,stroke:#229954,stroke-width:1px;
    classDef audio fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef audioFile fill:#FCE4D6,stroke:#D35400,stroke-width:1px;
    classDef utility fill:#F5CBA7,stroke:#B9770E,stroke-width:2px;
    classDef utilityFile fill:#FDEBD0,stroke:#B9770E,stroke-width:1px;
    classDef test fill:#D7BDE2,stroke:#8E44AD,stroke-width:2px;
    classDef testFile fill:#E8DAEF,stroke:#8E44AD,stroke-width:1px;
    classDef buildInfra fill:#ABEBC6,stroke:#1E8449,stroke-width:2px;
    classDef buildInfraFile fill:#E9F7EF,stroke:#1E8449,stroke-width:1px;
    classDef executable fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef external fill:#D6EAF8,stroke:#2980B9,stroke-dasharray: 5,5,stroke-width:2px;
```
