# harshilpabbisetti-sudo/dungeon-crawler architecture

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

- Interactive diagram: https://gitdiagram.com/harshilpabbisetti-sudo/dungeon-crawler
- Repository: https://github.com/harshilpabbisetti-sudo/dungeon-crawler

## Overview

1. **Overall shape**
   This is a single-process, offline **Python 3.10+ / Pygame** top-down game. The architecture is centered around one main game loop that owns input, simulation, AI, rendering, and screen transitions. There is no server/client split or external backend.

2. **Entry point and loop control**
   `code/main.py` is the orchestrator. It likely initializes Pygame, loads settings/assets, creates the initial world state, and then drives frame-by-frame updates for gameplay and for non-gameplay screens such as win/lose/end states in `code/end.py`.

3. **Core world state**
   `code/level.py` and `code/map_manager.py` appear to manage the active dungeon, including map layout, room/corridor state, tile rendering, collision boundaries, and progression between generated levels or game states. This is the main boundary between the generated world and everything that moves inside it.

4. **Procedural dungeon generation**
   `code/dungeon_gen.py` is the content-generation subsystem. It builds a dungeon layout at runtime, likely creating rooms, corridors, spawn points, exit placement, hiding spots, and obstacle placement. The generated structure feeds directly into the level/map manager, which then turns it into colliders and renderable tiles.

5. **Entity model**
   `code/entity.py` is the shared base abstraction for in-world actors or objects. `code/player.py`, `code/monster.py`, and `code/hiding_obj.py` sit on top of that foundation and represent the main interactive entity types: the player, enemies, and environment objects that can be used for hiding.

6. **Player-driven simulation**
   `code/player.py` owns movement, sprinting, hiding/interacting, and sound emission. Player state is not just visual; it influences enemy behavior through a sound radius and likely through hide-state flags, making the player subsystem a major input into the AI layer.

7. **Enemy AI and perception**
   `code/monster.py` is the enemy brain. It implements a state machine with the behaviors described in the README: roam, inspect, and chase. The important architectural boundary is that monster decisions are driven by two perception channels: visual detection via raycasted vision and auditory detection via the player’s noise events.

8. **Pathfinding and navigation**
   `code/astar.py` provides route planning for enemy movement, especially when investigating noise or pursuing the player through dungeon geometry. This separates “where to go” from “how to animate,” and likely consumes the grid or room graph produced by dungeon generation / map management.

9. **Data-driven enemy configuration**
   `code/monsters.json` is a content/config boundary for enemy types. It supplies per-monster stats or traits for the six enemy variants listed in the README, allowing `monster.py` to stay generic while behavior and balance are tuned through data.

10. **UI, timing, and end-state flow**
   `code/timer.py` and `code/stopwatch.py` handle run timing, while `code/end.py` handles success/failure presentation and restart flow. `code/debug.py` likely exposes developer diagnostics, and `code/support.py` plus `code/settings.py` provide shared utilities and constants used throughout the runtime.

11. **Assets and presentation**
   The `audio/`, `graphics/`, and `font/` directories are the presentation layer. They contain static assets for sprites, tiles, monster frames, background music, and sound effects. The game logic loads these assets at runtime; there is no evidence of asset streaming or external service dependency.

12. **Key data flow to diagram**
   The main flow is: **input → player update → sound/position/hidden state → monster perception + pathfinding → world/state update → render**. In parallel, **procedural generation → map/level setup → entity placement and collision surfaces** happens at startup or on level creation. That separation is the most important architectural boundary in the repo.

Main entry points: [`code/main.py`](https://github.com/harshilpabbisetti-sudo/dungeon-crawler/blob/main/code/main.py) (Main loop), [`code/monster.py`](https://github.com/harshilpabbisetti-sudo/dungeon-crawler/blob/main/code/monster.py) (Monster AI), [`code/level.py`](https://github.com/harshilpabbisetti-sudo/dungeon-crawler/blob/main/code/level.py) (Level state), [`code/player.py`](https://github.com/harshilpabbisetti-sudo/dungeon-crawler/blob/main/code/player.py) (Player)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g1["Game loop"]
  node_n1["Main loop<br/>orchestrator<br/>[main.py]"]
  node_n2["End screen<br/>state screen<br/>[end.py]"]
end

subgraph group_g2["World"]
  node_n3["Dungeon gen<br/>procedural gen<br/>[dungeon_gen.py]"]
  node_n4["Level state<br/>world state<br/>[level.py]"]
  node_n5["Map manager<br/>map assembly<br/>[map_manager.py]"]
end

subgraph group_g3["Actors"]
  node_n6(("Entity base<br/>actor base<br/>[entity.py]"))
  node_n7["Player<br/>input actor<br/>[player.py]"]
  node_n8["Monster AI<br/>enemy brain<br/>[monster.py]"]
  node_n9["Hiding obj<br/>world object<br/>[hiding_obj.py]"]
end

subgraph group_g4["Support"]
  node_n10{{"Pathfinding<br/>navigation<br/>[astar.py]"}}
  node_n11["Monster data<br/>config data<br/>[monsters.json]"]
  node_n12["Timer<br/>run timing<br/>[timer.py]"]
  node_n13["Stopwatch<br/>time helper<br/>[stopwatch.py]"]
  node_n14["Settings<br/>constants<br/>[settings.py]"]
  node_n15["Support utils<br/>shared utils<br/>[support.py]"]
  node_n16["Debug<br/>dev tools<br/>[debug.py]"]
end

subgraph group_g5["Presentation"]
  node_n17[("Audio<br/>assets")]
  node_n18[("Graphics<br/>assets")]
  node_n19[("Fonts<br/>assets")]
end

node_n1 -->|"runs"| node_n4
node_n1 -->|"updates"| node_n7
node_n1 -->|"updates"| node_n8
node_n1 -->|"switches to"| node_n2
node_n1 -->|"tracks time"| node_n12
node_n3 -->|"feeds layout"| node_n5
node_n4 -->|"creates"| node_n3
node_n4 -->|"owns map"| node_n5
node_n5 -->|"places"| node_n9
node_n6 -->|"base for"| node_n7
node_n6 -->|"base for"| node_n8
node_n6 -->|"base for"| node_n9
node_n7 -->|"emits noise"| node_n8
node_n7 -->|"interacts with"| node_n9
node_n8 -->|"paths via"| node_n10
node_n8 -->|"reads traits"| node_n11
node_n8 -->|"navigates"| node_n4
node_n12 -->|"uses"| node_n13
node_n1 -->|"reads"| node_n14
node_n1 -->|"uses"| node_n15
node_n1 -.->|"optional debug"| node_n16
node_n1 -->|"loads"| node_n17
node_n1 -->|"loads"| node_n18
node_n1 -->|"loads"| node_n19

click node_n1 "https://github.com/harshilpabbisetti-sudo/dungeon-crawler/blob/main/code/main.py"
click node_n2 "https://github.com/harshilpabbisetti-sudo/dungeon-crawler/blob/main/code/end.py"
click node_n3 "https://github.com/harshilpabbisetti-sudo/dungeon-crawler/blob/main/code/dungeon_gen.py"
click node_n4 "https://github.com/harshilpabbisetti-sudo/dungeon-crawler/blob/main/code/level.py"
click node_n5 "https://github.com/harshilpabbisetti-sudo/dungeon-crawler/blob/main/code/map_manager.py"
click node_n6 "https://github.com/harshilpabbisetti-sudo/dungeon-crawler/blob/main/code/entity.py"
click node_n7 "https://github.com/harshilpabbisetti-sudo/dungeon-crawler/blob/main/code/player.py"
click node_n8 "https://github.com/harshilpabbisetti-sudo/dungeon-crawler/blob/main/code/monster.py"
click node_n9 "https://github.com/harshilpabbisetti-sudo/dungeon-crawler/blob/main/code/hiding_obj.py"
click node_n10 "https://github.com/harshilpabbisetti-sudo/dungeon-crawler/blob/main/code/astar.py"
click node_n11 "https://github.com/harshilpabbisetti-sudo/dungeon-crawler/blob/main/code/monsters.json"
click node_n12 "https://github.com/harshilpabbisetti-sudo/dungeon-crawler/blob/main/code/timer.py"
click node_n13 "https://github.com/harshilpabbisetti-sudo/dungeon-crawler/blob/main/code/stopwatch.py"
click node_n14 "https://github.com/harshilpabbisetti-sudo/dungeon-crawler/blob/main/code/settings.py"
click node_n15 "https://github.com/harshilpabbisetti-sudo/dungeon-crawler/blob/main/code/support.py"
click node_n16 "https://github.com/harshilpabbisetti-sudo/dungeon-crawler/blob/main/code/debug.py"
click node_n17 "https://github.com/harshilpabbisetti-sudo/dungeon-crawler/tree/main/audio"
click node_n18 "https://github.com/harshilpabbisetti-sudo/dungeon-crawler/tree/main/graphics"
click node_n19 "https://github.com/harshilpabbisetti-sudo/dungeon-crawler/tree/main/font"

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_n1,node_n2 toneBlue
class node_n3,node_n4,node_n5 toneAmber
class node_n6,node_n7,node_n8,node_n9 toneMint
class node_n10,node_n11,node_n12,node_n13,node_n14,node_n15,node_n16 toneRose
class node_n17,node_n18,node_n19 toneIndigo
```

## Components

### Game loop

Top-level runtime orchestration and end-state flow.

- [Main loop](https://github.com/harshilpabbisetti-sudo/dungeon-crawler/blob/main/code/main.py): orchestrator · Initializes and runs the frame loop for gameplay and screen transitions. · `code/main.py`
- [End screen](https://github.com/harshilpabbisetti-sudo/dungeon-crawler/blob/main/code/end.py): state screen · Handles win/lose presentation and restart/exit flow. · `code/end.py`

### World

Dungeon generation, level state, and map assembly.

- [Dungeon gen](https://github.com/harshilpabbisetti-sudo/dungeon-crawler/blob/main/code/dungeon_gen.py): procedural gen · Builds dungeon layouts, spawn points, and obstacle placement at runtime. · `code/dungeon_gen.py`
- [Level state](https://github.com/harshilpabbisetti-sudo/dungeon-crawler/blob/main/code/level.py): world state · Owns the active level and progression between generated stages. · `code/level.py`
- [Map manager](https://github.com/harshilpabbisetti-sudo/dungeon-crawler/blob/main/code/map_manager.py): map assembly · Turns generated layout into tiles, collision boundaries, and renderable map state. · `code/map_manager.py`

### Actors

Shared entity model plus player, enemies, and hiding objects.

- [Entity base](https://github.com/harshilpabbisetti-sudo/dungeon-crawler/blob/main/code/entity.py): actor base · Shared abstraction for in-world actors and interactive objects. · `code/entity.py`
- [Player](https://github.com/harshilpabbisetti-sudo/dungeon-crawler/blob/main/code/player.py): input actor · Handles movement, sprinting, hiding, interaction, and noise emission. · `code/player.py`
- [Monster AI](https://github.com/harshilpabbisetti-sudo/dungeon-crawler/blob/main/code/monster.py): enemy brain · Implements roaming, inspecting, chasing, and perception-driven behavior. · `code/monster.py`
- [Hiding obj](https://github.com/harshilpabbisetti-sudo/dungeon-crawler/blob/main/code/hiding_obj.py): world object · Environment object the player can use for concealment. · `code/hiding_obj.py`

### Support

Navigation, timing, configuration, and shared utilities.

- [Pathfinding](https://github.com/harshilpabbisetti-sudo/dungeon-crawler/blob/main/code/astar.py): navigation · Computes routes through dungeon geometry for pursuit and investigation. · `code/astar.py`
- [Monster data](https://github.com/harshilpabbisetti-sudo/dungeon-crawler/blob/main/code/monsters.json): config data · Defines enemy variants and tuning parameters for the AI layer. · `code/monsters.json`
- [Timer](https://github.com/harshilpabbisetti-sudo/dungeon-crawler/blob/main/code/timer.py): run timing · Tracks elapsed time and run timing state. · `code/timer.py`
- [Stopwatch](https://github.com/harshilpabbisetti-sudo/dungeon-crawler/blob/main/code/stopwatch.py): time helper · Low-level stopwatch utility used by the timing system. · `code/stopwatch.py`
- [Settings](https://github.com/harshilpabbisetti-sudo/dungeon-crawler/blob/main/code/settings.py): constants · Shared runtime constants and tuning values. · `code/settings.py`
- [Support utils](https://github.com/harshilpabbisetti-sudo/dungeon-crawler/blob/main/code/support.py): shared utils · Common helper functions used across the codebase. · `code/support.py`
- [Debug](https://github.com/harshilpabbisetti-sudo/dungeon-crawler/blob/main/code/debug.py): dev tools · Developer diagnostics and inspection helpers. · `code/debug.py`

### Presentation

Static art, audio, and font assets loaded by the game.

- [Audio](https://github.com/harshilpabbisetti-sudo/dungeon-crawler/tree/main/audio): assets · Background music and sound effects used by the game. · `audio`
- [Graphics](https://github.com/harshilpabbisetti-sudo/dungeon-crawler/tree/main/graphics): assets · Sprite, tile, monster, and environment art assets. · `graphics`
- [Fonts](https://github.com/harshilpabbisetti-sudo/dungeon-crawler/tree/main/font): assets · Font assets used for UI and screen text. · `font`

## Connections

- Main loop → Level state: runs · Main loop advances the active level each frame.
- Main loop → Player: updates · Main loop feeds input and simulation into the player.
- Main loop → Monster AI: updates · Main loop steps enemy AI and movement.
- Main loop → End screen: switches to · Main loop transitions into end-state screens.
- Main loop → Timer: tracks time · Main loop reads run timing state.
- Dungeon gen → Map manager: feeds layout · Generated dungeon structure is consumed by map assembly.
- Level state → Dungeon gen: creates · Level state triggers dungeon generation for new stages.
- Level state → Map manager: owns map · Level state holds the active map representation.
- Map manager → Hiding obj: places · Map assembly integrates hiding objects into the world.
- Entity base → Player: base for · Player is built on the shared entity abstraction.
- Entity base → Monster AI: base for · Monster AI is built on the shared entity abstraction.
- Entity base → Hiding obj: base for · Hiding objects use the shared entity abstraction.
- Player → Monster AI: emits noise · Player sound state influences enemy perception and chase.
- Player → Hiding obj: interacts with · Player can hide in or interact with concealment objects.
- Monster AI → Pathfinding: paths via · Enemy pursuit and investigation uses route planning.
- Monster AI → Monster data: reads traits · Monster behavior and stats are driven by config data.
- Monster AI → Level state: navigates · Enemy movement is constrained by the active level geometry.
- Timer → Stopwatch: uses · Timer is backed by stopwatch logic.
- Main loop → Settings: reads · Core runtime settings are loaded during startup.
- Main loop → Support utils: uses · Main loop relies on shared helper utilities.
- Main loop → Debug: optional debug · Developer diagnostics can be enabled alongside the loop.
- Main loop → Audio: loads · Audio assets are loaded for music and sound effects.
- Main loop → Graphics: loads · Graphics assets are loaded for the world and actors.
- Main loop → Fonts: loads · Font assets are loaded for UI text.
