# jmltundercode/dexel_survival_dungeon architecture

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

- Interactive diagram: https://gitdiagram.com/jmltundercode/dexel_survival_dungeon
- Repository: https://github.com/jmltundercode/dexel_survival_dungeon

## Overview

##### Project type and purpose
- This is a 2D roguelike survival‐dungeon game written in Python, using Pygame for graphics/audio and NumPy for math/AI.
- The player navigates procedurally generated dungeons, fights AI enemies, and the core is a real‐time game loop.

##### File structure
- Top level:
- game (script or packaged executable)
- src (source code)
- requirements.txt, README, CI workflows, web (static site)
- src/ has these subfolders:
- assets – tiled maps, sprites, tilesets
- characters – player, enemy, attack waves, animations
- data – configuration tables (e.g. enemy stats)
- kinematics – steering behaviors (seek, wander, arrive)
- – dungeon generation & map logic
- utils – config loader, resource path resolver
- main.py – entry point & game loop

##### README
- Confirms Python 3.8+, Pygame 2.5.0, NumPy, PyInstaller
- Describes major features: procedural dungeons, AI behaviors, player controls
- Shows expected project tree for src/game vs. our actual src subfolders

##### Main components and how to represent them
a. Components
1. **Entry & Bootstrap** (main.py, configs)
2. **Asset Manager** (utils.resource_path, loads sprites, maps, tilesets)
3. **Game Loop** (initialize, update, render, event handling)
4. **Input Controller** (keyboard & mouse → player commands)
5. **Game State / World Model** (map layout, entities’ positions & stats)
6. **Dungeon Generator** (src.map.map, procedural layout & tile placements)
7. **Entity System**
– Player (src.characters.player)
– Enemies (src.characters.enemy + src.data.enemies)
8. **AI & Physics**
– Steering & kinematics (seek, arrive, wandering)
– Collision detection & resolution
9. **Combat System** (attack_wave, weapons & bullets management)
11. **External Libraries** (Pygame, NumPy)
12. **Packaging / Deployment** (game script, PyInstaller)

b. Relationships & data flow
- **Startup**: main.py → load configs → initialize Asset Manager → generate dungeon → spawn entities
- **Game Loop Iteration**:
1. Input Controller reads events → updates Player intent
2. AI & Kinematics compute new velocities/paths for enemies
3. Physics & collision resolve movements
4. Combat System resolves attacks → health/states updated
5. Renderer queries Game State → draws map, entities, UI

c. Architectural patterns & principles
- **Component decomposition**: each subsystem (input, AI, rendering) lives in its own package
- **Single Responsibility**: map generation separate from rendering; kinematics separate from character logic
- **MVC‐style** (rough):
- Model = Game State & Entities
- View = Renderer
- Controller = Input & Game Loop
- **Resource centralization**: Asset Manager handles all I/O for sprites, maps, sounds

d. Key technologies & libraries
- Python 3.8+
- Pygame (graphics, audio, event loop)
- NumPy (vector math for kinematics/AI)
- Tiled .tmx/.tsx format for maps
- PyInstaller for bundling

##### Elements
- Blue for core loop & controllers
- Green for game state/model
- Orange for AI/physics
- Purple for rendering/assets
- Gray for external libraries

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Entry & Bootstrap
    subgraph "Bootstrap Layer"
        direction TB
        Entry["main.py"]:::core
        ConfigLoader["configs.py"]:::core
        Entry -->|loads configs| ConfigLoader
    end

    %% Asset Manager
    subgraph "Asset Management" 
        direction TB
        AssetManager["resource_path.py"]:::render
        StaticAssets["assets/"]:::render
        AssetManager -->|resolves paths| StaticAssets
    end

    %% Dungeon Generator
    subgraph "World Generation"
        direction TB
        DungeonGen["map.py"]:::model
    end

    %% Game State / World Model
    subgraph "Game State / Model"
        direction TB
        WorldModel["map.py"]:::model
        PlayerEntity["player.py"]:::model
        EnemyEntity["enemy.py"]:::model
        EnemyData["enemies.py"]:::model
        WorldModel -->|uses| PlayerEntity
        WorldModel -->|uses| EnemyEntity
        EnemyEntity -->|stats from| EnemyData
    end

    %% AI & Physics System
    subgraph "AI System" 
        direction TB
        KinematicCore["kinematic.py"]:::ai
        Arrive["kinematic_arrive.py"]:::ai
        Seek["kinematic_seek.py"]:::ai
        Wandering["kinematic_wandering.py"]:::ai
        KinematicCore --> Arrive
        KinematicCore --> Seek
        KinematicCore --> Wandering
    end

    %% Combat System
    subgraph "Combat System"
        direction TB
        Combat["attack_wave.py"]:::model
        Animation["animation.py"]:::render
    end

    %% Game Loop & Controller
    subgraph "Core Game Loop"
        direction TB
        Loop["Game Loop"]:::core
        InputCtrl["Input Controller"]:::core
        Renderer["Renderer"]:::render
        Loop -->|handles events| InputCtrl
        Loop -->|updates AI| KinematicCore
        Loop -->|generates world| DungeonGen
        Loop -->|updates state| WorldModel
        Loop -->|resolves combat| Combat
        Loop -->|calls render| Renderer
    end

    %% External Libraries
    subgraph "External Libraries"
        direction TB
        Pygame["Pygame"]:::external
        NumPy["NumPy"]:::external
        Pygame -.-> InputCtrl
        Pygame -.-> Renderer
        NumPy -.-> KinematicCore
    end

    %% Packaging
    Package["game"]:::core

    %% Connections
    Entry -->|starts| Loop
    Entry -->|initializes| AssetManager
    AssetManager -->|provides assets to| Renderer
    DungeonGen -->|builds tiles to| WorldModel
    WorldModel -->|provides state to| Renderer
    InputCtrl -->|commands| PlayerEntity
    PlayerEntity -->|moves| WorldModel
    EnemyEntity -->|moves| WorldModel
    Combat -->|spawns bullets| WorldModel
    Animation -->|draws frames| Renderer

    Entry --> Package

    %% Click Events
    click Entry "https://github.com/jmltundercode/dexel_survival_dungeon/blob/main/src/main.py"
    click ConfigLoader "https://github.com/jmltundercode/dexel_survival_dungeon/blob/main/src/utils/configs.py"
    click AssetManager "https://github.com/jmltundercode/dexel_survival_dungeon/blob/main/src/utils/resource_path.py"
    click StaticAssets "https://github.com/jmltundercode/dexel_survival_dungeon/tree/main/src/assets/"
    click DungeonGen "https://github.com/jmltundercode/dexel_survival_dungeon/blob/main/src/map/map.py"
    click WorldModel "https://github.com/jmltundercode/dexel_survival_dungeon/blob/main/src/map/map.py"
    click PlayerEntity "https://github.com/jmltundercode/dexel_survival_dungeon/blob/main/src/characters/player.py"
    click EnemyEntity "https://github.com/jmltundercode/dexel_survival_dungeon/blob/main/src/characters/enemy.py"
    click EnemyData "https://github.com/jmltundercode/dexel_survival_dungeon/blob/main/src/data/enemies.py"
    click Combat "https://github.com/jmltundercode/dexel_survival_dungeon/blob/main/src/characters/attack_wave.py"
    click Animation "https://github.com/jmltundercode/dexel_survival_dungeon/blob/main/src/characters/animation.py"
    click KinematicCore "https://github.com/jmltundercode/dexel_survival_dungeon/blob/main/src/kinematics/kinematic.py"
    click Arrive "https://github.com/jmltundercode/dexel_survival_dungeon/blob/main/src/kinematics/kinematic_arrive.py"
    click Seek "https://github.com/jmltundercode/dexel_survival_dungeon/blob/main/src/kinematics/kinematic_seek.py"
    click Wandering "https://github.com/jmltundercode/dexel_survival_dungeon/blob/main/src/kinematics/kinematic_wandering.py"
    click Package "https://github.com/jmltundercode/dexel_survival_dungeon/tree/main/game"

    %% Styles
    classDef core fill:#BFDBFE,stroke:#1E3A8A,color:#1E3A8A;
    classDef model fill:#DCFCE7,stroke:#166534,color:#166534;
    classDef ai fill:#FED7AA,stroke:#C2410C,color:#C2410C;
    classDef render fill:#E9D5FF,stroke:#6B21A8,color:#6B21A8;
    classDef external fill:#E5E7EB,stroke:#6B7280,color:#6B7280;
```
