# kirjavascript/tetrisgym architecture

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

- Interactive diagram: https://gitdiagram.com/kirjavascript/tetrisgym
- Repository: https://github.com/kirjavascript/tetrisgym

## Overview

Main Components to Include:

##### Core Game Engine
- Game state management system (/src/gamemodestate/)
- Play state controller (/src/playstate/)

##### Input/Output System
- NMI (Non-Maskable Interrupt) handlers (/src/nmi/)
- Controller and keyboard polling subsystems

##### Game Modes and Trainers
- Connections to different training features (T-Spins, Pace, etc.)
- Game type menu system (/src/gamemode/gametypemenu/)

##### Graphics System
- Sprite handling (/src/sprites/)
- Nametable management (/src/nametables/)
- Palette systems (/src/palettes.asm)

##### Memory and State Management
- RAM management component (/src/ram.asm)
- High score system (/src/highscores/)
- Save state functionality

##### Audio System
- Audio processing component (/src/audio.asm)

Design Guidelines:

- [Boot/Reset] → [Core Game Engine] → [Game Modes]
- ↑   ↑   ↑
- [Input System] → [State Management] ← [Graphics System]
- ↓   ↓   ↓
- [Audio System] → [Memory Management] ← [High Scores]

##### Connection types
- Double lines: Data flow

##### Component details to highlight
- Memory mapper support (NROM, MMC1, MMC3, MMC5, CNROM)
- PAL/NTSC mode switching
- Save state system
- High score persistence

- [Game Type Menu]
- ↓
- [Mode Selection] → [Specific Trainer]
- ↓               ↓
- [Level Config] → [Game Instance]

- The assembly-based architecture
- The NES hardware interaction layers
- The extensive modification systems
- The training mode framework
- The build and testing infrastructure

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Core Game Engine
    subgraph CoreEngine
        Main["Main Game Logic"]:::core
        GameState["Game State Manager"]:::core
        PlayState["Play State Controller"]:::core
        Boot["Boot Process"]:::core
    end

    %% Input/Output System
    subgraph IO
        IOHandler["I/O Handler"]:::io
        NMIProc["NMI Processing"]:::io
        ControllerPoll["Controller Polling"]:::io
        KeyboardPoll["Keyboard Polling"]:::io
    end

    %% Game Modes
    subgraph GameModes
        Modes["Game Modes"]:::gamemode
        TypeMenu["Game Type Menu"]:::gamemode
        LevelMenu["Level Menu"]:::gamemode
        SpeedTest["Speed Test"]:::gamemode
    end

    %% Graphics System
    subgraph Graphics
        Sprites["Sprite Management"]:::graphics
        Nametables["Nametable Management"]:::graphics
        Palettes["Palette System"]:::graphics
        CharMap["Character Mapping"]:::graphics
    end

    %% Memory Management
    subgraph Memory
        RAM["RAM Management"]:::memory
        HighScores["High Score System"]:::memory
        Constants["Constants"]:::memory
        Data["Data Storage"]:::memory
    end

    %% Audio System
    subgraph Audio
        AudioProc["Audio Processing"]:::audio
    end

    %% Utility System
    subgraph Utils
        CoreUtils["Core Utilities"]:::util
        MathFunc["Math Functions"]:::util
        MapperUtils["Mapper Utilities"]:::util
        StringHandler["String Handling"]:::util
    end

    %% Connections
    Boot --> Main
    Main --> GameState
    GameState --> PlayState
    IOHandler --> Main
    NMIProc -.-> Main
    ControllerPoll --> IOHandler
    KeyboardPoll --> IOHandler
    Main --> Modes
    Modes --> TypeMenu
    TypeMenu --> LevelMenu
    LevelMenu --> SpeedTest
    Main --> Sprites
    Main --> Nametables
    Main --> Palettes
    CharMap --> Graphics
    RAM --> Main
    HighScores --> Main
    AudioProc --> Main
    CoreUtils --> Main
    MathFunc --> Main
    MapperUtils --> Main
    StringHandler --> Main

    %% Click Events
    click Main "https://github.com/kirjavascript/TetrisGYM/blob/master/src/main.asm"
    click GameState "https://github.com/kirjavascript/TetrisGYM/tree/master/src/gamemodestate/"
    click PlayState "https://github.com/kirjavascript/TetrisGYM/tree/master/src/playstate/"
    click Boot "https://github.com/kirjavascript/TetrisGYM/blob/master/src/boot.asm"
    click IOHandler "https://github.com/kirjavascript/TetrisGYM/blob/master/src/io.asm"
    click NMIProc "https://github.com/kirjavascript/TetrisGYM/tree/master/src/nmi/"
    click ControllerPoll "https://github.com/kirjavascript/TetrisGYM/blob/master/src/nmi/pollcontroller.asm"
    click KeyboardPoll "https://github.com/kirjavascript/TetrisGYM/blob/master/src/nmi/pollkeyboard.asm"
    click Modes "https://github.com/kirjavascript/TetrisGYM/tree/master/src/modes/"
    click TypeMenu "https://github.com/kirjavascript/TetrisGYM/tree/master/src/gamemode/gametypemenu/"
    click LevelMenu "https://github.com/kirjavascript/TetrisGYM/blob/master/src/gamemode/levelmenu.asm"
    click SpeedTest "https://github.com/kirjavascript/TetrisGYM/blob/master/src/gamemode/speedtest.asm"
    click Sprites "https://github.com/kirjavascript/TetrisGYM/tree/master/src/sprites/"
    click Nametables "https://github.com/kirjavascript/TetrisGYM/tree/master/src/nametables/"
    click Palettes "https://github.com/kirjavascript/TetrisGYM/blob/master/src/palettes.asm"
    click CharMap "https://github.com/kirjavascript/TetrisGYM/blob/master/src/charmap.asm"
    click RAM "https://github.com/kirjavascript/TetrisGYM/blob/master/src/ram.asm"
    click HighScores "https://github.com/kirjavascript/TetrisGYM/tree/master/src/highscores/"
    click Constants "https://github.com/kirjavascript/TetrisGYM/blob/master/src/constants.asm"
    click Data "https://github.com/kirjavascript/TetrisGYM/tree/master/src/data/"
    click AudioProc "https://github.com/kirjavascript/TetrisGYM/blob/master/src/audio.asm"
    click CoreUtils "https://github.com/kirjavascript/TetrisGYM/blob/master/src/util/core.asm"
    click MathFunc "https://github.com/kirjavascript/TetrisGYM/blob/master/src/util/math.asm"
    click MapperUtils "https://github.com/kirjavascript/TetrisGYM/blob/master/src/util/mapper.asm"
    click StringHandler "https://github.com/kirjavascript/TetrisGYM/blob/master/src/util/strings.asm"

    %% Styles
    classDef core fill:#a8d5ff,stroke:#333
    classDef io fill:#90EE90,stroke:#333
    classDef gamemode fill:#ffb6c1,stroke:#333
    classDef graphics fill:#fff59d,stroke:#333
    classDef memory fill:#dda0dd,stroke:#333
    classDef audio fill:#ffa07a,stroke:#333
    classDef util fill:#f0f0f0,stroke:#333

    %% Legend
    subgraph Legend
        L1["Core Components"]:::core
        L2["I/O System"]:::io
        L3["Game Modes"]:::gamemode
        L4["Graphics"]:::graphics
        L5["Memory"]:::memory
        L6["Audio"]:::audio
        L7["Utilities"]:::util
    end
```
