# yong-cheng-huang/zelda-rpg architecture

> Architecture diagram of the GitHub repository yong-cheng-huang/zelda-rpg, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yong-cheng-huang/zelda-rpg
- Repository: https://github.com/yong-cheng-huang/zelda-rpg

## Overview

##### Project type and purpose
- This is a standalone Pygame-based action-adventure RPG (“Zelda RPG”)
- Player explores maps, fights enemies, uses weapons and magic, collects items

##### File structure
- Top-level directories
– audio: all sound effects and music
– graphics: sprites, tilemaps, particles, fonts
– map: CSV files defining floor, grass, objects, entities, difficulty variants
– code: Python modules for game logic
- Key code modules
– main.py: initializes Pygame, loads assets, starts game loop
– settings.py: global constants (screen size, FPS, paths)
– support.py: helpers (image loading, CSV parsing)
– tile.py / level.py / map loader: constructs level geometry from CSV
– entity.py / enemy.py / player.py / weapon.py / magic.py / upgrade.py: game objects and behaviors
– particles.py: particle effects engine
– ui.py: on-screen HUD, menus
– debug.py: development tools

##### README insights
- Confirms use of Pygame, installation instructions, run command
- Overview of game features (enemies, effects, weapons)

a. Main components
1. Game Loop Controller
2. Input Handler
3. Asset Manager (graphics, audio, map data)
4. Loader / Level Manager
5. Entity System (Player, Enemies, NPCs)
6. Physics & Collision Manager
7. Rendering Engine (Sprite Batcher, Tilemap Renderer, Particle System)
8. Audio Engine (Music, SFX)
9. UI System (HUD, Menus)
10. Utility Modules (settings, support, debug)
b. Relationships & interactions
- Game Loop polls Input Handler each frame → updates Entity System & Physics → triggers Audio & Particle events → commands Rendering Engine → UI System overlays → loop continues
- Asset Manager loads graphics and sounds at startup or on demand, feeds resources to Rendering and Audio engines
- Loader reads CSV files → constructs tilemap and collision data for Level Manager → Entity System spawns entities based on map definitions
c. Architectural patterns
- Game-loop architecture (Input → Update → Render)
- Modular separation (one module per concern)
- Event-driven triggers for audio and particle effects
- Data-driven map construction (CSV files)
d. Technologies and frameworks
- Python 3.x
- Pygame for rendering, input, audio
- CSV parser (built-in or custom in support.py)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External dependency
    External["Pygame"]:::external

    %% Core Loop & Controllers
    GameLoop["Game Loop Controller"]:::core
    Input["Input Handler"]:::core

    %% Asset & Data
    subgraph "Asset Manager" 
        AssetGraphics["Graphics Assets"]:::asset
        AssetAudio["Audio Assets"]:::asset
        AssetMap["Map Data"]:::asset
    end

    %% Map & Level
    MapLoader["Map Loader / Level Manager"]:::subsystem
    Tilemap["Tilemap Construction & Collision"]:::subsystem

    %% Subsystems
    subgraph "Entity System"
        EntityBase["Base Entity"]:::subsystem
        EntityEnemy["Enemy Behaviors"]:::subsystem
        EntityPlayer["Player Behaviors"]:::subsystem
        Weapon["Weapons Subsystem"]:::subsystem
        Magic["Magic Subsystem"]:::subsystem
        Upgrade["Upgrades Subsystem"]:::subsystem
    end
    Particles["Particle System"]:::subsystem
    UI["UI System (HUD & Menus)"]:::subsystem
    AudioEngine["Audio Engine"]:::subsystem
    Physics["Physics & Collision Manager"]:::subsystem

    %% Utilities
    Support["CSV Parsing & Asset Helpers"]:::utility
    Settings["Settings & Constants"]:::utility
    Debug["Debug Tools"]:::utility

    %% Startup & Asset Loading
    External --> GameLoop
    GameLoop --> Settings
    GameLoop --> Support
    GameLoop --> AssetGraphics
    GameLoop --> AssetAudio
    GameLoop --> AssetMap

    AssetMap --> MapLoader
    MapLoader --> Tilemap
    Support --> MapLoader
    Tilemap --> Physics

    %% Main Loop Cycle
    GameLoop --> Input
    Input --> EntityBase
    EntityBase --> EntityEnemy
    EntityBase --> EntityPlayer
    EntityEnemy --> Weapon
    EntityPlayer --> Magic
    EntityPlayer --> Upgrade

    EntityBase --> Physics
    Physics --> EntityBase

    EntityBase --> Particles
    EntityBase --> AudioEngine

    %% Rendering & UI
    Tilemap --> Rendering["Rendering Engine"]:::subsystem
    Particles --> Rendering
    EntityBase --> Rendering
    Rendering --> UI
    UI --> GameLoop

    %% Event-driven Audio
    AudioEngine --> GameLoop

    %% Utility Tools
    GameLoop --> Debug

    %% Click Events
    click GameLoop "https://github.com/yong-cheng-huang/zelda-rpg/blob/main/code/main.py"
    click Input "https://github.com/yong-cheng-huang/zelda-rpg/blob/main/code/main.py"
    click AssetGraphics "https://github.com/yong-cheng-huang/zelda-rpg/tree/main/graphics/"
    click AssetAudio "https://github.com/yong-cheng-huang/zelda-rpg/tree/main/audio/"
    click AssetMap "https://github.com/yong-cheng-huang/zelda-rpg/tree/main/map/"
    click MapLoader "https://github.com/yong-cheng-huang/zelda-rpg/blob/main/code/level.py"
    click Tilemap "https://github.com/yong-cheng-huang/zelda-rpg/blob/main/code/tile.py"
    click Support "https://github.com/yong-cheng-huang/zelda-rpg/blob/main/code/support.py"
    click EntityBase "https://github.com/yong-cheng-huang/zelda-rpg/blob/main/code/entity.py"
    click EntityEnemy "https://github.com/yong-cheng-huang/zelda-rpg/blob/main/code/enemy.py"
    click EntityPlayer "https://github.com/yong-cheng-huang/zelda-rpg/blob/main/code/player.py"
    click Weapon "https://github.com/yong-cheng-huang/zelda-rpg/blob/main/code/weapon.py"
    click Magic "https://github.com/yong-cheng-huang/zelda-rpg/blob/main/code/magic.py"
    click Upgrade "https://github.com/yong-cheng-huang/zelda-rpg/blob/main/code/upgrade.py"
    click Particles "https://github.com/yong-cheng-huang/zelda-rpg/blob/main/code/particles.py"
    click UI "https://github.com/yong-cheng-huang/zelda-rpg/blob/main/code/ui.py"
    click AudioEngine "https://github.com/yong-cheng-huang/zelda-rpg/tree/main/audio/"
    click AudioEngine "https://github.com/yong-cheng-huang/zelda-rpg/blob/main/code/support.py"
    click Physics "https://github.com/yong-cheng-huang/zelda-rpg/blob/main/code/tile.py"
    click Settings "https://github.com/yong-cheng-huang/zelda-rpg/blob/main/code/settings.py"
    click Debug "https://github.com/yong-cheng-huang/zelda-rpg/blob/main/code/debug.py"

    %% Styles
    classDef core fill:#AEDFFF,stroke:#000,stroke-width:1px
    classDef asset fill:#C8FACC,stroke:#000,stroke-width:1px
    classDef subsystem fill:#FFD58B,stroke:#000,stroke-width:1px
    classDef utility fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef external fill:#FFC0CB,stroke:#000,stroke-width:1px
```
