# laurentprudhon/zxspectrumsimulator architecture

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

- Interactive diagram: https://gitdiagram.com/laurentprudhon/zxspectrumsimulator
- Repository: https://github.com/laurentprudhon/zxspectrumsimulator

## Overview

##### Project Type and Purpose
- This is a desktop emulator suite (“monorepo”) for accurately simulating the Z80 CPU and ZX Spectrum computer at the electronic (wire-and-clock) level.
- Components include a code-generation tool (Instruction table generator), the core Z80 simulation library, the ZX Spectrum-specific emulator layers (ROM, ULA, tape, BASIC, peripherals), a WPF‐based UI, an assembly code editor, and a large test harness.

##### File-Structure Analysis
- Top-level solution “ZxSpectrumSimulator.sln” contains multiple projects:
- Z80Simulator.GenerateTables: pre-build tool that ingests CSV instruction data & documentation to emit opcode tables.
- Z80Simulator: core simulation engine (Assembly, CPU, Instructions, System—Bus, Memory, IOPins).
- Z80Simulator.Test: rich NUnit/xUnit test suite covering ALU, CPU controls, machine cycles, microinstructions, system integration, ZEXALL.
- ZXSpectrum: ZX Spectrum emulator layers (ROM loader, ULA, BASIC interpreter, tape file formats, devices).
- ZXSpectrum.Test: tests for tape files, ULA video, basic programs, performance.
- ZXSpectrumUI: WPF front-end, platform adapters (keyboard, joystick, screen, speaker), NAudio for sound, game-loader assets.
- ZXCodeEditor: standalone WPF editor for incremental assembly, syntax highlighting, linking to the emulator back-end.

##### README Insights
- Emphasis on “electronic level”: clock, bus, pins.
- Goal: full reconstruction to deeply understand hardware and ROM.
- Loads real tape captures, plays original games.

a. Main Components (layered top-down):
1. Instruction Table Generator (Z80Simulator.GenerateTables) – design-time component.
2. Core Z80 Engine (Z80Simulator):
– CPU Model (Registers, ALU, Decoder, Microinstructions)
– System Model (Bus, Memory, IOPins, Clock)
– Assembly/Disassembly modules.
3. ZX Spectrum Emulator (ZXSpectrum):
– ROM Loader
– ULA (video timing, screen buffer)
– TapeFile Reader/Recorder
– BASIC Interpreter
– Peripheral abstractions (Joystick, Keyboard, Speaker)
4. UI Layer:
– WPF App (ZXSpectrumUI): MainWindow, Game Loader, Controls
– Platform Adapters: map emulator pins/signals into UI widgets
– ZXCodeEditor: Asm code editing, incremental assembler UI.
5. Test Harness:
– Z80Simulator.Test & ZXSpectrum.Test: drive inputs, capture logs, validate against reference data.
b. Interactions:
- UI calls into ZXSpectrum API to load ROM/tape, start/stop clock.
- ZXSpectrum wraps Z80Simulator: at each tick, drives CPU→System→Memory→Devices.
- ULA emits video frames back to ScreenAdapter; SpeakerAdapter plays audio via NAudio.
- ZXCodeEditor optionally outputs assembly into Z80Simulator.GenerateTables / Z80Simulator.Assembler.
- Test projects instantiate either Z80Simulator or ZXSpectrum.System to run scenarios, compare CSV logs.
c. Architectural Patterns
- Layered architecture: tool → core engine → specialization → presentation.
- Modular design: each instruction group in separate partial classes (e.g., Z80CPU_Instructions_*.cs).
- Dependency injection (System interfaces) for memory/devices.
- The test harness uses a simulation‐only “TestSystem” with mock devices.
d. Key Technologies
- C#/.NET, partial classes for instruction sets, CSV-based table generation.
- WPF for UI + AvalonEdit for code editing + NAudio for audio output.
- xUnit/NUnit for tests, CSV log comparison.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Design-time Tools
    subgraph "Design-Time Tools"
        direction TB
        ITG["Instruction Table Generator"]:::design
        CSV["CSV Instruction Data"]:::data
        TableOutput["Opcode Tables"]:::data
    end

    CSV -->|"ingest CSV"| ITG
    ITG -->|"emit tables"| TableOutput

    click ITG "https://github.com/laurentprudhon/zxspectrumsimulator/tree/master/Z80Simulator.GenerateTables/"
    click CSV "https://github.com/laurentprudhon/zxspectrumsimulator/tree/master/Z80Simulator.GenerateTables/"
    click TableOutput "https://github.com/laurentprudhon/zxspectrumsimulator/tree/master/Z80Simulator.GenerateTables/"

    %% Core Simulation
    subgraph "Core Z80 Engine"
        direction TB
        Assembly["Assembly Module"]:::core
        CPU["CPU Model"]:::core
        InstrSets["Instruction Sets"]:::core
        Cycles["Machine Cycles"]:::core
        SystemModel["System Model"]:::core
        Assembly -->|"uses tables"| TableOutput
        CPU -->|"executes instructions"| InstrSets
        CPU -->|"performs cycles"| Cycles
        CPU -->|"interacts via bus"| SystemModel
    end

    click Assembly "https://github.com/laurentprudhon/zxspectrumsimulator/blob/master/Z80Simulator/Assembly/Assembler.cs"
    click CPU "https://github.com/laurentprudhon/zxspectrumsimulator/blob/master/Z80Simulator/CPU/Z80CPU.cs"
    click InstrSets "https://github.com/laurentprudhon/zxspectrumsimulator/blob/master/Z80Simulator/CPU/Z80CPU_Instructions_*.cs"
    click Cycles "https://github.com/laurentprudhon/zxspectrumsimulator/blob/master/Z80Simulator/CPU/Z80CPU_MachineCycles.cs"
    click SystemModel "https://github.com/laurentprudhon/zxspectrumsimulator/blob/master/Z80Simulator/System/Bus.cs"

    classDef design fill:#ADD8E6,stroke:#000;
    classDef core fill:#90EE90,stroke:#000;

    %% ZX Spectrum Emulator
    subgraph "ZX Spectrum Emulator"
        direction TB
        ZXSpectrumCore["ZXSpectrumComputer"]:::zx
        ROMLoader["ROM Loader"]:::zx
        BASIC["BASIC Interpreter"]:::zx
        TapeIO["TapeFile I/O"]:::zx
        ULA["ULA (Video)"]:::zx
        Peripherals["Peripherals"]:::zx

        ZXSpectrumCore --> ROMLoader
        ZXSpectrumCore --> BASIC
        ZXSpectrumCore --> TapeIO
        ZXSpectrumCore --> ULA
        ZXSpectrumCore --> Peripherals
    end

    click ZXSpectrumCore "https://github.com/laurentprudhon/zxspectrumsimulator/blob/master/ZXSpectrum/ZXSpectrumComputer.cs"
    click ROMLoader "https://github.com/laurentprudhon/zxspectrumsimulator/blob/master/ZXSpectrum/ROM/ROM.cs"
    click BASIC "https://github.com/laurentprudhon/zxspectrumsimulator/blob/master/ZXSpectrum/Basic/BasicProgram.cs"
    click TapeIO "https://github.com/laurentprudhon/zxspectrumsimulator/blob/master/ZXSpectrum/TapeFiles/TapFileReader.cs"
    click ULA "https://github.com/laurentprudhon/zxspectrumsimulator/blob/master/ZXSpectrum/ULA.cs"
    click Peripherals "https://github.com/laurentprudhon/zxspectrumsimulator/blob/master/ZXSpectrum/Keyboard.cs"

    classDef zx fill:#FFA500,stroke:#000;

    %% UI Layer
    subgraph "UI Layer"
        direction TB
        WPFApp["WPF App"]:::ui
        PlatformAdapters["Platform Adapters"]:::ui
        NAudio["NAudio Integration"]:::ui
        UserControls["User Controls"]:::ui

        WPFApp -->|"loads ROM/tape, controls clock"| ZXSpectrumCore
        ZXSpectrumCore -->|"video frames"| UserControls
        ZXSpectrumCore -->|"audio data"| NAudio
        PlatformAdapters -->|"maps pins to UI"| WPFApp
    end

    click WPFApp "https://github.com/laurentprudhon/zxspectrumsimulator/blob/master/ZXSpectrumUI/MainWindow.xaml"
    click PlatformAdapters "https://github.com/laurentprudhon/zxspectrumsimulator/blob/master/ZXSpectrumUI/PlatformAdapters/KeyboardAdapter.cs"
    click NAudio "https://github.com/laurentprudhon/zxspectrumsimulator/tree/master/ZXSpectrumUI/NAudio-1.6/"
    click UserControls "https://github.com/laurentprudhon/zxspectrumsimulator/blob/master/ZXSpectrumUI/UserControls/Bus.xaml"

    classDef ui fill:#DDA0DD,stroke:#000;

    %% Code Editor
    subgraph "Assembly Code Editor"
        direction TB
        AsmEditor["Asm Code Editor"]:::editor
        AvalonEdit["AvalonEdit Integration"]:::editor
        IncrAsm["Incremental Assembler"]:::editor

        AsmEditor -->|"uses assembler API"| IncrAsm
        AvalonEdit --> AsmEditor
        IncrAsm -->|"emits code tables"| TableOutput
    end

    click AsmEditor "https://github.com/laurentprudhon/zxspectrumsimulator/blob/master/ZXCodeEditor/AsmCodeEditor.xaml"
    click AvalonEdit "https://github.com/laurentprudhon/zxspectrumsimulator/tree/master/ZXCodeEditor/AvalonEdit/"
    click IncrAsm "https://github.com/laurentprudhon/zxspectrumsimulator/tree/master/ZXCodeEditor/IncrementalAssembler/"

    classDef editor fill:#DDA0DD,stroke:#000;

    %% Test Harness
    subgraph "Test Harness"
        direction TB
        Z80Test["Z80Simulator.Test"]:::test
        ZXTest["ZXSpectrum.Test"]:::test

        Z80Test -->|"instantiates core"| CPU
        ZXTest -->|"instantiates emulator"| ZXSpectrumCore
    end

    click Z80Test "https://github.com/laurentprudhon/zxspectrumsimulator/tree/master/Z80Simulator.Test/"
    click ZXTest "https://github.com/laurentprudhon/zxspectrumsimulator/tree/master/ZXSpectrum.Test/"

    classDef test fill:#D3D3D3,stroke:#000;

    %% Data Stores and I/O
    CSV --> ITG
    TableOutput --> Assembly
    subgraph "I/O Devices"
        direction TB
        TapeFiles["Tape Files"]:::io
        ROMFiles["ROM Files"]:::io
        Screen["Screen"]:::io
        Speaker["Speaker"]:::io

        TapeFiles --> TapeIO
        ROMFiles --> ROMLoader
        Screen --> UserControls
        Speaker --> NAudio
    end

    classDef data fill:#E0FFFF,stroke:#000;
    classDef io fill:#F5F5DC,stroke:#000;
```
