How harshilpabbisetti-sudo/dungeon-crawler works
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: main.py Main loop · monster.py Monster AI · level.py Level state · player.py Player
Components 19
Game loop
Top-level runtime orchestration and end-state flow.
- Main loop · Initializes and runs the frame loop for gameplay and screen transitions.
code/main.py - End screen · Handles win/lose presentation and restart/exit flow.
code/end.py
World
Dungeon generation, level state, and map assembly.
- Dungeon gen · Builds dungeon layouts, spawn points, and obstacle placement at runtime.
code/dungeon_gen.py - Level state · Owns the active level and progression between generated stages.
code/level.py - Map manager · 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 · Shared abstraction for in-world actors and interactive objects.
code/entity.py - Player · Handles movement, sprinting, hiding, interaction, and noise emission.
code/player.py - Monster AI · Implements roaming, inspecting, chasing, and perception-driven behavior.
code/monster.py - Hiding obj · Environment object the player can use for concealment.
code/hiding_obj.py
Support
Navigation, timing, configuration, and shared utilities.
- Pathfinding · Computes routes through dungeon geometry for pursuit and investigation.
code/astar.py - Monster data · Defines enemy variants and tuning parameters for the AI layer.
code/monsters.json - Timer · Tracks elapsed time and run timing state.
code/timer.py - Stopwatch · Low-level stopwatch utility used by the timing system.
code/stopwatch.py - Settings · Shared runtime constants and tuning values.
code/settings.py - Support utils · Common helper functions used across the codebase.
code/support.py - Debug · Developer diagnostics and inspection helpers.
code/debug.py
Connections 24
- 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.