# ioncodes/gg architecture

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

- Interactive diagram: https://gitdiagram.com/ioncodes/gg
- Repository: https://github.com/ioncodes/gg

## Overview

##### Major Components
- Emulator Core:
- The “core/src/vdp” subdirectory provides dedicated modules (mod.rs, pattern.rs, sprite.rs) that handle video display rendering – a key area for emulating the Game Gear hardware.
- Z80 Emulation:
- The “z80” directory includes modules for the Z80 CPU (like disassembler, instruction definitions, and core z80 logic) which is essential since the emulator uses a Z80 CPU core with AI-generated opcode parser.
- Main Application:
- The “gg” directory appears to be the entry point for the emulator. The “gg/src/main.rs” and “gg/src/emulator.rs” tie together the core emulation logic with user interaction, command-line argument handling, and execution flow.
- Debug and Testing Tools:
- Features for debugging, such as the debugger built with egui/eframe, are integrated into the emulator (as outlined in the README). This includes memory viewers, disassembly, trace and debug logging.
- Unit tests provided in core/src/tests.rs and the separate ZEXDOC/ZEXALL test integrations in the README should be acknowledged as part of validating system behavior.
- External Resources:
- The “external” folder contains BIOS listings, ROM samples/demonstrations, test scripts (e.g., test.lua), and additional asset files. These are important for testing and verifying emulator compatibility.

##### Relationships and Interactions
- The main application module in “gg” loads the emulator core and passes configuration parameters (e.g., paths to BIOS and ROM files) to initialize and run emulation.
- Within the core, the CPU emulation (core/src/cpu.rs integrated with the z80 modules) fetches instructions, interacts with memory (core/src/memory.rs), and uses the bus (core/src/bus.rs) to manage system-wide data flow.
- The VDP subsystem (core/src/vdp) handles rendering tasks, working in tandem with the CPU to provide accurate video output.
- The Lua scripting interface (core/src/lua_engine.rs) and debugger tools are connected to the running emulation, allowing for hooks and runtime adjustments (e.g., stepping, breakpoints).
- Testing and debugging components (selected via command-line arguments – see README options) interact with both the core and UI elements like egui, reflecting a development-time mode of operation.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The project clearly separates domain logic (emulation in “core” and “z80”), user interface and entry (in “gg”), and external dependencies (in “external”).
- Modular Design: Key functionalities (sound through PSG, video via VDP, CPU and memory handling, input via joystick) are divided into their own modules, making the system easier to reason about.
- Testability: With designated test modules and integration with standardized test ROMs, the design supports both unit testing and functional testing.

##### Capturing Essential Architectural Elements
- How the command-line interface (via Cargo commands) launches the system.
- How the CPU, with its instruction set from the Z80 modules, directs memory usage and bus operations.
- How the VDP module contributes to video output, closely tied with the CPU’s timing.
- How the debugger features (both CLI and GUI) interlink with the emulator’s runtime state.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Main Application Layer
    mainApp["Main Application (gg)"]

    %% Emulator Core Modules
    subgraph "Emulator Core"
        emulatorCore["Emulator Core (core)"]
        cpu["CPU Emulation (core/src/cpu.rs)"]
        memory["Memory (core/src/memory.rs)"]
        bus["Bus (core/src/bus.rs)"]
        io["I/O (core/src/io.rs)"]
        joystick["Joystick (core/src/joystick.rs)"]
        mapper["Mapper (core/src/mapper.rs)"]
        lua["Lua Engine (core/src/lua_engine.rs)"]
        vdp["VDP Subsystem (core/src/vdp)"]
    end

    %% Z80 Emulation Modules
    subgraph "Z80 Emulation"
        z80Core["Z80 Core (z80/src/z80.rs)"]
        disassembler["Disassembler (z80/src/disassembler.rs)"]
        instruction["Instruction Set (z80/src/instruction.rs)"]
    end

    %% Debug and Testing Tools
    subgraph "Debug & Testing Tools"
        debug["Debugger & Testing Tools (core/src/tests.rs)"]
    end

    %% External Resources
    subgraph "External Resources"
        external["External Resources (external)"]
    end

    %% Connections and Data Flow
    mainApp -->|"initializes"| emulatorCore
    emulatorCore -->|"invokes"| cpu
    cpu -->|"accesses"| memory
    cpu -->|"communicates"| bus
    emulatorCore -->|"handles"| io
    emulatorCore -->|"processes"| joystick
    emulatorCore -->|"maps"| mapper
    emulatorCore -->|"integrates"| lua
    cpu -->|"synchronizes with"| vdp
    cpu -->|"opcode decoding"| z80Core
    z80Core -->|"utilizes"| disassembler
    z80Core -->|"implements"| instruction
    debug -->|"monitors"| cpu
    debug -->|"inspects"| memory
    debug -->|"observes"| vdp
    external -->|"provides ROM/BIOS"| emulatorCore

    %% Click Events
    click mainApp "https://github.com/ioncodes/gg/tree/master/gg/"
    click emulatorCore "https://github.com/ioncodes/gg/tree/master/core/"
    click cpu "https://github.com/ioncodes/gg/blob/master/core/src/cpu.rs"
    click vdp "https://github.com/ioncodes/gg/tree/master/core/src/vdp/"
    click z80Core "https://github.com/ioncodes/gg/tree/master/z80/"
    click debug "https://github.com/ioncodes/gg/blob/master/core/src/tests.rs"
    click external "https://github.com/ioncodes/gg/tree/master/external/"

    %% Styling
    classDef mainStyle fill:#f9e,stroke:#333,stroke-width:2px;
    classDef coreStyle fill:#bbf,stroke:#333,stroke-width:2px;
    classDef z80Style fill:#bfb,stroke:#333,stroke-width:2px;
    classDef debugStyle fill:#ffb,stroke:#333,stroke-width:2px;
    classDef externalStyle fill:#fbb,stroke:#333,stroke-width:2px;

    class mainApp mainStyle;
    class emulatorCore,cpu,memory,bus,io,joystick,mapper,lua,vdp coreStyle;
    class z80Core,disassembler,instruction z80Style;
    class debug debugStyle;
    class external externalStyle;
```
