# viett123/stungeon architecture

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

- Interactive diagram: https://gitdiagram.com/viett123/stungeon
- Repository: https://github.com/viett123/stungeon

## Overview

Stungeon is a pygame educational dungeon-crawler: the player creates or resumes a hero, explores floors, answers German questions to resolve combat, and progresses through rewards and choices toward the final floor. The graph separates run flow, dungeon exploration, question-driven combat, progression/economy, and presentation. Edges are limited to relationships visible in excerpts, SOURCE INDEX references, or the README; several unsampled subsystems are shown without speculative internal wiring.

Main entry points: [`core/flow.py`](https://github.com/viett123/stungeon/blob/main/core/flow.py) (Run Flow), [`dungeon/dungeon_scene.py`](https://github.com/viett123/stungeon/blob/main/dungeon/dungeon_scene.py) (Dungeon Scene), [`combat/combat_scene.py`](https://github.com/viett123/stungeon/blob/main/combat/combat_scene.py) (Fight Screen), [`ui/shop_screen.py`](https://github.com/viett123/stungeon/blob/main/ui/shop_screen.py) (Shop Screen)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_flow["Game Flow"]
  node_game["Game Runtime<br/>[game.py]"]
  node_scene_manager["Scene Manager<br/>[scene.py]"]
  node_flow_coordinator["Run Flow<br/>[flow.py]"]
end

subgraph group_dungeon["Dungeon Exploration"]
  node_dungeon_scene["Dungeon Scene<br/>[dungeon_scene.py]"]
  node_floor_gen["Floor Generation<br/>[floor.py]"]
  node_dungeon_render["Dungeon Rendering<br/>[renderer.py]"]
  node_actor_sprites["Actors and Sprites<br/>[actor.py]"]
end

subgraph group_combat["Combat and Learning"]
  node_combat_scene["Fight Screen<br/>[combat_scene.py]"]
  node_battle_rules["Battle Rules<br/>[battle.py]"]
  node_question_engine["German Questions<br/>[engine.py]"]
end

subgraph group_progress["Run Progression"]
  node_player["Player<br/>[player.py]"]
  node_run_state["Run State<br/>[run.py]"]
  node_save_store[("Save System<br/>[save.py]")]
  node_items_inventory["Items and Inventory<br/>[inventory.py]"]
  node_loot["Loot Rewards<br/>[loot.py]"]
  node_shop["Between-Floor Shop<br/>[shop.py]"]
  node_choices["Risk-Reward Choice<br/>[choices.py]"]
end

subgraph group_presentation["Screens and Rendering"]
  node_new_game["Hero Setup<br/>[new_game.py]"]
  node_class_select["Class Selection<br/>[class_select.py]"]
  node_hud["HUD<br/>[hud.py]"]
  node_inventory_screen["Inventory Screen"]
  node_shop_screen["Shop Screen<br/>[shop_screen.py]"]
  node_screen_routes["Other Screens<br/>[screens.py]"]
end

node_player_actor(("Player"))

node_player_actor -->|"starts run"| node_new_game
node_new_game -->|"submits choices"| node_flow_coordinator
node_flow_coordinator -->|"routes scenes"| node_scene_manager
node_game -->|"drives scenes"| node_scene_manager
node_flow_coordinator -->|"creates run"| node_run_state
node_flow_coordinator -->|"loads and saves"| node_save_store
node_flow_coordinator -->|"enters floor"| node_dungeon_scene
node_flow_coordinator -->|"opens shop"| node_shop_screen
node_flow_coordinator -->|"shows end screen"| node_screen_routes
node_class_select -->|"submits class"| node_flow_coordinator
node_run_state -->|"holds player"| node_player
node_dungeon_scene -->|"generates floor"| node_floor_gen
node_dungeon_scene -->|"renders floor"| node_dungeon_render
node_dungeon_scene -->|"uses actors"| node_actor_sprites
node_dungeon_scene -->|"starts fight"| node_combat_scene
node_dungeon_scene -->|"adds loot"| node_items_inventory
node_dungeon_scene -->|"awards loot"| node_loot
node_combat_scene -->|"resolves moves"| node_battle_rules
node_combat_scene -->|"asks questions"| node_question_engine
node_battle_rules -->|"uses combat stats"| node_player
node_combat_scene -->|"uses consumables"| node_items_inventory
node_inventory_screen -->|"reads inventory"| node_items_inventory
node_shop_screen -->|"uses shop system"| node_shop
node_hud -.->|"shows status"| node_player
node_player_actor -->|"explores floors"| node_dungeon_scene
node_player_actor -->|"chooses moves"| node_combat_scene
node_player_actor -->|"opens bag"| node_inventory_screen
node_player_actor -->|"shops between floors"| node_shop_screen

click node_player "https://github.com/viett123/stungeon/blob/main/systems/player.py"
click node_game "https://github.com/viett123/stungeon/blob/main/core/game.py"
click node_scene_manager "https://github.com/viett123/stungeon/blob/main/core/scene.py"
click node_flow_coordinator "https://github.com/viett123/stungeon/blob/main/core/flow.py"
click node_run_state "https://github.com/viett123/stungeon/blob/main/core/run.py"
click node_save_store "https://github.com/viett123/stungeon/blob/main/systems/save.py"
click node_new_game "https://github.com/viett123/stungeon/blob/main/ui/new_game.py"
click node_class_select "https://github.com/viett123/stungeon/blob/main/ui/class_select.py"
click node_dungeon_scene "https://github.com/viett123/stungeon/blob/main/dungeon/dungeon_scene.py"
click node_floor_gen "https://github.com/viett123/stungeon/blob/main/dungeon/floor.py"
click node_dungeon_render "https://github.com/viett123/stungeon/blob/main/dungeon/renderer.py"
click node_actor_sprites "https://github.com/viett123/stungeon/blob/main/dungeon/actor.py"
click node_combat_scene "https://github.com/viett123/stungeon/blob/main/combat/combat_scene.py"
click node_battle_rules "https://github.com/viett123/stungeon/blob/main/combat/battle.py"
click node_question_engine "https://github.com/viett123/stungeon/blob/main/questions/engine.py"
click node_items_inventory "https://github.com/viett123/stungeon/blob/main/systems/inventory.py"
click node_loot "https://github.com/viett123/stungeon/blob/main/systems/loot.py"
click node_shop "https://github.com/viett123/stungeon/blob/main/systems/shop.py"
click node_choices "https://github.com/viett123/stungeon/blob/main/systems/choices.py"
click node_hud "https://github.com/viett123/stungeon/blob/main/ui/hud.py"
click node_inventory_screen "https://github.com/viett123/stungeon/blob/main/ui/inventory_screen.py"
click node_shop_screen "https://github.com/viett123/stungeon/blob/main/ui/shop_screen.py"
click node_screen_routes "https://github.com/viett123/stungeon/blob/main/ui/screens.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_game,node_scene_manager,node_flow_coordinator toneBlue
class node_dungeon_scene,node_floor_gen,node_dungeon_render,node_actor_sprites toneAmber
class node_combat_scene,node_battle_rules,node_question_engine toneMint
class node_player,node_run_state,node_save_store,node_items_inventory,node_loot,node_shop,node_choices toneRose
class node_new_game,node_class_select,node_hud,node_inventory_screen,node_shop_screen,node_screen_routes,node_player_actor toneIndigo
```

## Components

### Game Flow

- [Game Runtime](https://github.com/viett123/stungeon/blob/main/core/game.py): `core/game.py`
- [Scene Manager](https://github.com/viett123/stungeon/blob/main/core/scene.py): `core/scene.py`
- [Run Flow](https://github.com/viett123/stungeon/blob/main/core/flow.py): `core/flow.py`

### Dungeon Exploration

- [Dungeon Scene](https://github.com/viett123/stungeon/blob/main/dungeon/dungeon_scene.py): `dungeon/dungeon_scene.py`
- [Floor Generation](https://github.com/viett123/stungeon/blob/main/dungeon/floor.py): `dungeon/floor.py`
- [Dungeon Rendering](https://github.com/viett123/stungeon/blob/main/dungeon/renderer.py): `dungeon/renderer.py`
- [Actors and Sprites](https://github.com/viett123/stungeon/blob/main/dungeon/actor.py): `dungeon/actor.py`

### Combat and Learning

- [Fight Screen](https://github.com/viett123/stungeon/blob/main/combat/combat_scene.py): `combat/combat_scene.py`
- [Battle Rules](https://github.com/viett123/stungeon/blob/main/combat/battle.py): `combat/battle.py`
- [German Questions](https://github.com/viett123/stungeon/blob/main/questions/engine.py): `questions/engine.py`

### Run Progression

- [Player](https://github.com/viett123/stungeon/blob/main/systems/player.py): `systems/player.py`
- [Run State](https://github.com/viett123/stungeon/blob/main/core/run.py): `core/run.py`
- [Save System](https://github.com/viett123/stungeon/blob/main/systems/save.py): `systems/save.py`
- [Items and Inventory](https://github.com/viett123/stungeon/blob/main/systems/inventory.py): `systems/inventory.py`
- [Loot Rewards](https://github.com/viett123/stungeon/blob/main/systems/loot.py): `systems/loot.py`
- [Between-Floor Shop](https://github.com/viett123/stungeon/blob/main/systems/shop.py): `systems/shop.py`
- [Risk-Reward Choice](https://github.com/viett123/stungeon/blob/main/systems/choices.py): `systems/choices.py`

### Screens and Rendering

- [Hero Setup](https://github.com/viett123/stungeon/blob/main/ui/new_game.py): `ui/new_game.py`
- [Class Selection](https://github.com/viett123/stungeon/blob/main/ui/class_select.py): `ui/class_select.py`
- [HUD](https://github.com/viett123/stungeon/blob/main/ui/hud.py): `ui/hud.py`
- [Inventory Screen](https://github.com/viett123/stungeon/blob/main/ui/inventory_screen.py): `ui/inventory_screen.py`
- [Shop Screen](https://github.com/viett123/stungeon/blob/main/ui/shop_screen.py): `ui/shop_screen.py`
- [Other Screens](https://github.com/viett123/stungeon/blob/main/ui/screens.py): `ui/screens.py`

### Other components

- **Player**

## Connections

- Player → Hero Setup: starts run (evidence: `README.md`)
- Hero Setup → Run Flow: submits choices (evidence: `ui/new_game.py`)
- Run Flow → Scene Manager: routes scenes (evidence: `core/flow.py`)
- Game Runtime → Scene Manager: drives scenes
- Run Flow → Run State: creates run (evidence: `core/flow.py`)
- Run Flow → Save System: loads and saves (evidence: `core/flow.py`)
- Run Flow → Dungeon Scene: enters floor (evidence: `core/flow.py`)
- Run Flow → Shop Screen: opens shop (evidence: `core/flow.py`)
- Run Flow → Other Screens: shows end screen (evidence: `core/flow.py`)
- Class Selection → Run Flow: submits class (evidence: `ui/class_select.py`)
- Run State → Player: holds player (evidence: `core/run.py`)
- Dungeon Scene → Floor Generation: generates floor (evidence: `dungeon/dungeon_scene.py`)
- Dungeon Scene → Dungeon Rendering: renders floor (evidence: `dungeon/dungeon_scene.py`)
- Dungeon Scene → Actors and Sprites: uses actors (evidence: `dungeon/dungeon_scene.py`)
- Dungeon Scene → Fight Screen: starts fight (evidence: `dungeon/dungeon_scene.py`)
- Dungeon Scene → Items and Inventory: adds loot (evidence: `dungeon/dungeon_scene.py`)
- Dungeon Scene → Loot Rewards: awards loot (evidence: `dungeon/dungeon_scene.py`)
- Fight Screen → Battle Rules: resolves moves (evidence: `combat/combat_scene.py`)
- Fight Screen → German Questions: asks questions (evidence: `combat/combat_scene.py`)
- Battle Rules → Player: uses combat stats (evidence: `combat/battle.py`)
- Fight Screen → Items and Inventory: uses consumables (evidence: `combat/combat_scene.py`)
- Inventory Screen → Items and Inventory: reads inventory (evidence: `ui/inventory_screen.py`)
- Shop Screen → Between-Floor Shop: uses shop system (evidence: `core/flow.py`)
- HUD → Player: shows status
- Player → Dungeon Scene: explores floors (evidence: `README.md`)
- Player → Fight Screen: chooses moves (evidence: `README.md`)
- Player → Inventory Screen: opens bag (evidence: `README.md`)
- Player → Shop Screen: shops between floors (evidence: `README.md`)
