# botrandomness/code-dmg architecture

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

- Interactive diagram: https://gitdiagram.com/botrandomness/code-dmg
- Repository: https://github.com/botrandomness/code-dmg

## Overview

##### Project Type and Purpose
- CODE‑DMG is an open‑source Gameboy emulator written in C#. It provides a “Core” emulation engine (CLI) and a minimal GUI wrapper via Raylib‑cs for rendering and input. Its primary goal is to emulate the DMG‑CPU, PPU, MMU, MBC chips, timers, and joypad of the original Gameboy hardware in a cycle‑driven loop.

##### File Structure Analysis
- Top‑level files:
- CODE‑DMG.csproj – C# project file
- fall_back.gb – fallback ROM for testing
- git‑res/ – assets (logo, boot GIF, screenshots)
- src/ – core emulator components:
- Program.cs – entry point, parses CLI flags, initializes DMG
- DMG.cs – orchestrator wiring CPU, PPU, MMU, Timer, Joypad, and main emulation loop
- CPU.cs – executes instructions, drives cycle counts
- PPU.cs – Picture Processing Unit, scanline renderer
- MMU.cs – Memory Management Unit, unified 16‑bit address space and MMIO
- MBC.cs – Memory Bank Controller logic (bank switching for ROM/RAM)
- Timer.cs – hardware timer, interrupt generation
- Joypad.cs – input handling, updates MMIO bits
- Helper.cs – static constants, palettes, global enums
- Test.cs – JSON‑based CPU instruction test harness
- test/ – test resource descriptions

##### Key Insights from README
- Architecture is object‑oriented: one class per hardware component
- Emulation loop in DMG.Run() is “CPU‑driven”: fetch/execute instruction → returns cycle count → step PPU & Timer → after 70224 T‑cycles, end frame → render via Raylib at 60 FPS
- Dependencies: Raylib‑cs for graphics & input, .NET 6.0 runtime

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI / CLI Layer"
        Program["Program.cs\n(Raylib Window & Event Loop)"]:::frontend
    end

    %% Core Orchestrator
    subgraph "Core Orchestrator"
        DMG["DMG.cs\n(Run Loop)"]:::core
    end

    %% Hardware Components
    subgraph "Hardware Components"
        CPU["CPU.cs\nExecuteInstruction()"]:::hw
        MMU["MMU.cs\nRead/Write Memory & MMIO"]:::hw
        MBC["MBC.cs\nBank Switching"]:::hw
        PPU["PPU.cs\nScanline Rendering"]:::hw
        Timer["Timer.cs\nStep(cycles) & Interrupts"]:::hw
        Joypad["Joypad.cs\nHandle Input & MMIO Update"]:::hw
    end

    %% Utilities
    subgraph "Utilities"
        Helper["Helper.cs\nConstants & Enums"]:::util
    end

    %% Storage / I/O
    subgraph "Storage"
        ROM[(fall_back.gb)]:::storage
        ProjectFile[(CODE‑DMG.csproj)]:::storage
    end

    %% Test Harness
    subgraph "Test Harness"
        Test["Test.cs\nJSON CPU Tests"]:::test
        TestRes[(test/README.txt)]:::test
    end

    %% Connections
    Program -->|"initializes"| DMG
    DMG -->|"fetch/execute"| CPU
    DMG -->|"step"| PPU
    DMG -->|"step"| Timer
    DMG -->|"poll input"| Joypad
    CPU -->|"read/write"| MMU
    MMU -->|"ROM/RAM access"| MBC
    Joypad -->|"update MMIO bits"| MMU
    CPU -->|"return cycles"| PPU
    CPU -->|"return cycles"| Timer
    PPU -->|"framebuffer"| Program
    Timer -->|"set interrupt flags"| MMU
    MMU -->|"deliver interrupts"| CPU
    ROM -->|"load data"| MMU
    ProjectFile --> Program
    Test --> CPU
    Test --> MMU
    TestRes --> Test
    CPU -.-> Helper
    MMU -.-> Helper
    PPU -.-> Helper
    Timer -.-> Helper
    Joypad -.-> Helper

    %% Click Events
    click Program "https://github.com/botrandomness/code-dmg/blob/master/src/Program.cs"
    click DMG "https://github.com/botrandomness/code-dmg/blob/master/src/DMG.cs"
    click CPU "https://github.com/botrandomness/code-dmg/blob/master/src/CPU.cs"
    click MMU "https://github.com/botrandomness/code-dmg/blob/master/src/MMU.cs"
    click MBC "https://github.com/botrandomness/code-dmg/blob/master/src/MBC.cs"
    click PPU "https://github.com/botrandomness/code-dmg/blob/master/src/PPU.cs"
    click Timer "https://github.com/botrandomness/code-dmg/blob/master/src/Timer.cs"
    click Joypad "https://github.com/botrandomness/code-dmg/blob/master/src/Joypad.cs"
    click Helper "https://github.com/botrandomness/code-dmg/blob/master/src/Helper.cs"
    click ROM "https://github.com/botrandomness/code-dmg/blob/master/fall_back.gb"
    click ProjectFile "https://github.com/botrandomness/code-dmg/blob/master/CODE‑DMG.csproj"
    click Test "https://github.com/botrandomness/code-dmg/blob/master/src/Test.cs"
    click TestRes "https://github.com/botrandomness/code-dmg/blob/master/test/README.txt"

    %% Styles
    classDef frontend fill:#D6EFFF,stroke:#0366D6,stroke-width:2px,stroke-dasharray: 5 5,shape:round;
    classDef core fill:#E6FFDA,stroke:#228B22,stroke-width:2px;
    classDef hw fill:#FFF5BA,stroke:#DAA520,stroke-width:2px;
    classDef util fill:#F0F0F0,stroke:#888888,stroke-width:2px;
    classDef storage fill:#FFEBDD,stroke:#D2691E,stroke-width:2px,shape:cylinder;
    classDef test fill:#FDE2E1,stroke:#B22222,stroke-width:2px;
    class Program,DMG,CPU,MMU,MBC,PPU,Timer,Joypad,Helper,ROM,ProjectFile,Test,TestRes frontend,core,hw,util,storage,test
```
