# caffeinetrip/echo-of-fallens architecture

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

- Interactive diagram: https://gitdiagram.com/caffeinetrip/echo-of-fallens
- Repository: https://github.com/caffeinetrip/echo-of-fallens

## Overview

##### Main Components
- Game Entry & Core Loop: Start with main.py and core scripts that initialize and manage the game.
- Game Logic & Managers: Components such as room_manager.py, battle_manager.py, dialogue_manager.py, scenes.py, spells, player, enemy, etc., which handle gameplay and interactive mechanics.
- Custom Game Engine (“pygpen”): This extensive package includes:
- Assets Handling (assets, spritesheets, asset utilities)
- Data Structures for entities and collision (entity_quads, quads, stationary_quads)
- Entities and Entity Database for game objects
- ModernGL Integration (mgl) for low-level rendering and shader management
- Rendering Pipeline (renderer in rendering folder)
- Sound Management (sound submodule)
- Utility Modules (game_math, gfx, io, etc.)
- Visual Effects (vfx for particles, water, grass, etc.)
- UI Components (textbox, boxer)
- Data Assets: The “data” directory holds all external assets – dialogues, fonts, images (cards, entities, spritesheets), key configurations, music, saves, and sounds.
- Shaders: The “shaders” directory (including shader.frag) provides custom GLSL shader scripts.
- Additional Scripts: Others like scripts/animation.py and room.py provide additional game mechanics and support for in-game animations and room management.

##### Relationships and Data Flow
- The Game Entry (main.py) initializes the game loop and orchestrates the interaction among various modules.
- Managers (battle, dialogue, room, etc.) communicate with the engine (“pygpen”) modules to display visuals, handle user input, and produce sound.
- The engine’s rendering and sound submodules take assets from the data folder (ensuring assets are contextually separated) and use shaders (ModernGL pipeline) for visual output.
- The UI and game event modules interact to present game state and capture player input.
- Data flows from external asset directories (data/) through asset management components to rendering, audio, and game logic. Additionally, the game’s procedural generation element (infinite generation) should be shown as a loop or iterative process feeding into room management and scene rendering.

##### Important Architectural Patterns
- Modular Design: Each function (game logic, asset handling, rendering, sound, etc.) is separated into its own module or package. This separation makes it easier to isolate and troubleshoot areas such as input management, rendering, and data handling.
- Layered Architecture: The low-level engine (pygpen) serves as a foundation, abstracting complexity for higher-level game logic components.
- Data-Driven Design: External data asset management is a crucial part of the architecture (note the extensive “data” directory), meaning the game dynamically loads assets (maps, sprites, sounds) which are then fed into the engine modules.
- Use of External APIs: Integration with ModernGL for graphics and Pygame for game loop / event handling.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Nodes - Data & Shaders
    ED["External Data Assets"]:::data
    GLSL["Custom GLSL Shaders"]:::data

    %% Game Core: Main Loop & Managers
    subgraph "Game Core"
        ML["Main Loop (main.py)"]:::game
        RM["Room Manager"]:::game
        BM["Battle Manager"]:::game
        DM["Dialogue Manager"]:::game
        SC["Scenes & High-Level Logic"]:::game
        SP["Spells Module"]:::game
        PL["Player Logic"]:::game
        EL["Enemy Logic"]:::game
        AN["Animation Script"]:::game
        HK["Hooks Script"]:::game
    end

    %% Custom Game Engine (pygpen) Subcomponents
    subgraph "Custom Game Engine (pygpen)"
        AH["Assets Handling"]:::engine
        DS["Data Structures"]:::engine
        EDDB["Entities & Database"]:::engine
        MGL["ModernGL Integration"]:::engine
        RP["Rendering Pipeline"]:::engine
        SM["Sound Management"]:::engine
        UM["Utility Modules"]:::engine
        VFX["Visual Effects (VFX)"]:::engine
        UI["UI Components"]:::engine
        MM["Miscellaneous Modules"]:::engine
        TH["Tilemap Handling"]:::engine
    end

    %% Interactions & Data Flow
    ML -->|initiates| RM
    ML -->|initiates| BM
    ML -->|initiates| DM
    ML -->|initiates| SC
    ML -->|initiates| SP
    ML -->|initiates| PL
    ML -->|initiates| EL
    ML -->|initiates| AN
    ML -->|initiates| HK

    RM -->|manages| TH
    BM -->|handles| EDDB
    DM -->|controls| UI
    SC -->|interacts with| MGL
    SP -->|uses| EDDB
    PL -->|updates| EDDB
    EL -->|updates| EDDB

    %% Internal Engine Relationships
    MGL -->|feeds| RP
    RP -->|applies| GLSL
    ED -->|provides assets to| AH

    %% Styling for vertical flow
    %% Additional engine modules not directly linked can be considered part of the overall engine

    %% Click Events for Game Core
    click ML "https://github.com/caffeinetrip/echo-of-fallens/blob/main/main.py"
    click RM "https://github.com/caffeinetrip/echo-of-fallens/blob/main/scripts/room_manager.py"
    click BM "https://github.com/caffeinetrip/echo-of-fallens/blob/main/scripts/battle_manager.py"
    click DM "https://github.com/caffeinetrip/echo-of-fallens/blob/main/scripts/dialogue_manager.py"
    click SC "https://github.com/caffeinetrip/echo-of-fallens/blob/main/scripts/scenes.py"
    click SP "https://github.com/caffeinetrip/echo-of-fallens/tree/main/scripts/spells"
    click PL "https://github.com/caffeinetrip/echo-of-fallens/blob/main/scripts/player.py"
    click EL "https://github.com/caffeinetrip/echo-of-fallens/blob/main/scripts/enemy.py"
    click AN "https://github.com/caffeinetrip/echo-of-fallens/blob/main/scripts/animation.py"
    click HK "https://github.com/caffeinetrip/echo-of-fallens/blob/main/scripts/hooks.py"

    %% Click Events for Custom Engine (pygpen) Modules
    click AH "https://github.com/caffeinetrip/echo-of-fallens/tree/main/scripts/pygpen/assets"
    click DS "https://github.com/caffeinetrip/echo-of-fallens/tree/main/scripts/pygpen/data_structures"
    click EDDB "https://github.com/caffeinetrip/echo-of-fallens/tree/main/scripts/pygpen/entities"
    click MGL "https://github.com/caffeinetrip/echo-of-fallens/tree/main/scripts/pygpen/mgl"
    click RP "https://github.com/caffeinetrip/echo-of-fallens/tree/main/scripts/pygpen/rendering"
    click SM "https://github.com/caffeinetrip/echo-of-fallens/tree/main/scripts/pygpen/sound"
    click UM "https://github.com/caffeinetrip/echo-of-fallens/tree/main/scripts/pygpen/utils"
    click VFX "https://github.com/caffeinetrip/echo-of-fallens/tree/main/scripts/pygpen/vfx"
    click UI "https://github.com/caffeinetrip/echo-of-fallens/tree/main/scripts/pygpen/ui"
    click MM "https://github.com/caffeinetrip/echo-of-fallens/tree/main/scripts/pygpen/misc"
    click TH "https://github.com/caffeinetrip/echo-of-fallens/tree/main/scripts/pygpen/tiles"

    %% Click Events for External Data & Shaders
    click ED "https://github.com/caffeinetrip/echo-of-fallens/tree/main/data"
    click GLSL "https://github.com/caffeinetrip/echo-of-fallens/blob/main/shaders/shader.frag"

    %% Styles
    classDef game fill:#FFC107,stroke:#333,stroke-width:2px;
    classDef engine fill:#8BC34A,stroke:#333,stroke-width:2px;
    classDef data fill:#03A9F4,stroke:#333,stroke-width:2px;
```
