# rasmuslc1/kobold_clash architecture

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

- Interactive diagram: https://gitdiagram.com/rasmuslc1/kobold_clash
- Repository: https://github.com/rasmuslc1/kobold_clash

## Overview

This is a Python/Pygame dungeon-crawler roguelike with systems for biome-based world generation, combat and enemy AI, loot and inventory progression, lighting, and persistence. The principal gameplay loop takes the player through generated rooms and encounters, with enemies navigating and attacking, and items supporting further progression. The README documents several performance and architecture features; source excerpts are partial, and some modules it names are absent from the supplied tree, so uncertain runtime wiring is omitted.

Main entry points: [`scripts/game/save_load_manager.py`](https://github.com/rasmuslc1/kobold_clash/blob/main/scripts/game/save_load_manager.py) (Save and Load), [`scripts/engine/tilemap/tilemap.py`](https://github.com/rasmuslc1/kobold_clash/blob/main/scripts/engine/tilemap/tilemap.py) (Tilemap and Queries), [`scripts/entities/items/item_handler.py`](https://github.com/rasmuslc1/kobold_clash/blob/main/scripts/entities/items/item_handler.py) (Items and Drops), [`scripts/entities/traps/trap_handler.py`](https://github.com/rasmuslc1/kobold_clash/blob/main/scripts/entities/traps/trap_handler.py) (Traps)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Game Runtime"]
  node_save["Save and Load"]
  node_main["Game Entry Loop<br/>[main.py]"]
end

subgraph group_world["World Systems"]
  node_awakening["Awakening Director<br/>[awakening.py]"]
  node_spawn["Biome Enemy Spawners<br/>[crypt_spawn.py]"]
  node_rooms["Room Initialization"]
  node_tilemap["Tilemap and Queries<br/>[tilemap.py]"]
  node_decorations["Decorations"]
  node_traps["Traps<br/>[trap_handler.py]"]
end

subgraph group_combat["Combat and AI"]
  node_player["Player<br/>[player.py]"]
  node_enemy["Enemies<br/>[enemy_handler.py]"]
  node_ai["Enemy Intent and AI<br/>[intent_manager.py]"]
  node_effects["Status Effects<br/>[effects_handler.py]"]
end

subgraph group_progression["Items and Progression"]
  node_items["Items and Drops<br/>[item_handler.py]"]
  node_inventory["Inventory"]
  node_runes["Runes<br/>[rune_handler.py]"]
end

subgraph group_engine["Engine Services"]
  node_path_queue["Pathfinding Queue"]
  node_a_star["A* Pathfinding<br/>[a_star.py]"]
  node_raycaster["Lighting and Fog<br/>[ray_caster.py]"]
  node_particles["Particles"]
end

node_user(("Player"))

node_user -->|"starts game"| node_main
node_main -->|"creates manager"| node_save
node_save -->|"captures and restores"| node_tilemap
node_save -->|"captures and restores"| node_player
node_save -->|"captures and restores"| node_items
node_save -->|"captures and restores"| node_enemy
node_save -->|"captures and restores"| node_traps
node_save -->|"captures and restores"| node_inventory
node_save -->|"captures and restores"| node_decorations
node_save -->|"captures and restores"| node_raycaster
node_enemy -->|"updates intent"| node_ai
node_ai -.->|"requests paths"| node_path_queue
node_path_queue -.->|"processes requests"| node_a_star
node_ai -->|"targets player"| node_player
node_awakening -.->|"dispatches spawns"| node_spawn
node_rooms -.->|"selects biome spawns"| node_spawn
node_rooms -.->|"initializes room"| node_tilemap
node_decorations -->|"updates tile entities"| node_tilemap
node_traps -->|"queries nearby tiles"| node_tilemap
node_items -->|"queries nearby items"| node_tilemap
node_items -->|"adds pickups"| node_inventory
node_items -->|"updates runes"| node_runes
node_runes -->|"replaces active runes"| node_inventory
node_player -.->|"manages effects"| node_effects
node_traps -->|"removes trap lights"| node_raycaster
node_particles -.->|"renders effects"| node_main

click node_player "https://github.com/rasmuslc1/kobold_clash/blob/main/scripts/entities/moving_entities/player/player.py"
click node_enemy "https://github.com/rasmuslc1/kobold_clash/blob/main/scripts/entities/moving_entities/enemies/enemy_handler.py"
click node_ai "https://github.com/rasmuslc1/kobold_clash/blob/main/scripts/entities/moving_entities/enemies/behavior/intent_manager.py"
click node_path_queue "https://github.com/rasmuslc1/kobold_clash/blob/main/scripts/entities/moving_entities/enemies/enemy_pathfinding_handler.py"
click node_a_star "https://github.com/rasmuslc1/kobold_clash/blob/main/scripts/engine/a_star.py"
click node_awakening "https://github.com/rasmuslc1/kobold_clash/blob/main/scripts/engine/awakening/awakening.py"
click node_spawn "https://github.com/rasmuslc1/kobold_clash/blob/main/scripts/entities/moving_entities/enemies/crypt/crypt_spawn.py"
click node_rooms "https://github.com/rasmuslc1/kobold_clash/blob/main/scripts/entities/rooms/crypt_room_initialiser.py"
click node_tilemap "https://github.com/rasmuslc1/kobold_clash/blob/main/scripts/engine/tilemap/tilemap.py"
click node_decorations "https://github.com/rasmuslc1/kobold_clash/blob/main/scripts/entities/decoration/decoration_handler.py"
click node_traps "https://github.com/rasmuslc1/kobold_clash/blob/main/scripts/entities/traps/trap_handler.py"
click node_items "https://github.com/rasmuslc1/kobold_clash/blob/main/scripts/entities/items/item_handler.py"
click node_inventory "https://github.com/rasmuslc1/kobold_clash/blob/main/scripts/interface/inventory/inventory_handler.py"
click node_runes "https://github.com/rasmuslc1/kobold_clash/blob/main/scripts/entities/items/runes/rune_handler.py"
click node_effects "https://github.com/rasmuslc1/kobold_clash/blob/main/scripts/entities/moving_entities/effects/effects_handler.py"
click node_raycaster "https://github.com/rasmuslc1/kobold_clash/blob/main/scripts/engine/ray_caster.py"
click node_particles "https://github.com/rasmuslc1/kobold_clash/blob/main/scripts/engine/particles/particle_handler.py"
click node_save "https://github.com/rasmuslc1/kobold_clash/blob/main/scripts/game/save_load_manager.py"
click node_main "https://github.com/rasmuslc1/kobold_clash/blob/main/main.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_save,node_main toneBlue
class node_awakening,node_spawn,node_rooms,node_tilemap,node_decorations,node_traps toneAmber
class node_player,node_enemy,node_ai,node_effects toneMint
class node_items,node_inventory,node_runes toneRose
class node_path_queue,node_a_star,node_raycaster,node_particles,node_user toneIndigo
```

## Components

### Game Runtime

- [Save and Load](https://github.com/rasmuslc1/kobold_clash/blob/main/scripts/game/save_load_manager.py): `scripts/game/save_load_manager.py`
- [Game Entry Loop](https://github.com/rasmuslc1/kobold_clash/blob/main/main.py): `main.py`

### World Systems

- [Awakening Director](https://github.com/rasmuslc1/kobold_clash/blob/main/scripts/engine/awakening/awakening.py): `scripts/engine/awakening/awakening.py`
- [Biome Enemy Spawners](https://github.com/rasmuslc1/kobold_clash/blob/main/scripts/entities/moving_entities/enemies/crypt/crypt_spawn.py): `scripts/entities/moving_entities/enemies/crypt/crypt_spawn.py`
- [Room Initialization](https://github.com/rasmuslc1/kobold_clash/blob/main/scripts/entities/rooms/crypt_room_initialiser.py): `scripts/entities/rooms/crypt_room_initialiser.py`
- [Tilemap and Queries](https://github.com/rasmuslc1/kobold_clash/blob/main/scripts/engine/tilemap/tilemap.py): `scripts/engine/tilemap/tilemap.py`
- [Decorations](https://github.com/rasmuslc1/kobold_clash/blob/main/scripts/entities/decoration/decoration_handler.py): `scripts/entities/decoration/decoration_handler.py`
- [Traps](https://github.com/rasmuslc1/kobold_clash/blob/main/scripts/entities/traps/trap_handler.py): `scripts/entities/traps/trap_handler.py`

### Combat and AI

- [Player](https://github.com/rasmuslc1/kobold_clash/blob/main/scripts/entities/moving_entities/player/player.py): `scripts/entities/moving_entities/player/player.py`
- [Enemies](https://github.com/rasmuslc1/kobold_clash/blob/main/scripts/entities/moving_entities/enemies/enemy_handler.py): `scripts/entities/moving_entities/enemies/enemy_handler.py`
- [Enemy Intent and AI](https://github.com/rasmuslc1/kobold_clash/blob/main/scripts/entities/moving_entities/enemies/behavior/intent_manager.py): `scripts/entities/moving_entities/enemies/behavior/intent_manager.py`
- [Status Effects](https://github.com/rasmuslc1/kobold_clash/blob/main/scripts/entities/moving_entities/effects/effects_handler.py): `scripts/entities/moving_entities/effects/effects_handler.py`

### Items and Progression

- [Items and Drops](https://github.com/rasmuslc1/kobold_clash/blob/main/scripts/entities/items/item_handler.py): `scripts/entities/items/item_handler.py`
- [Inventory](https://github.com/rasmuslc1/kobold_clash/blob/main/scripts/interface/inventory/inventory_handler.py): `scripts/interface/inventory/inventory_handler.py`
- [Runes](https://github.com/rasmuslc1/kobold_clash/blob/main/scripts/entities/items/runes/rune_handler.py): `scripts/entities/items/runes/rune_handler.py`

### Engine Services

- [Pathfinding Queue](https://github.com/rasmuslc1/kobold_clash/blob/main/scripts/entities/moving_entities/enemies/enemy_pathfinding_handler.py): `scripts/entities/moving_entities/enemies/enemy_pathfinding_handler.py`
- [A* Pathfinding](https://github.com/rasmuslc1/kobold_clash/blob/main/scripts/engine/a_star.py): `scripts/engine/a_star.py`
- [Lighting and Fog](https://github.com/rasmuslc1/kobold_clash/blob/main/scripts/engine/ray_caster.py): `scripts/engine/ray_caster.py`
- [Particles](https://github.com/rasmuslc1/kobold_clash/blob/main/scripts/engine/particles/particle_handler.py): `scripts/engine/particles/particle_handler.py`

### Other components

- **Player**

## Connections

- Player → Game Entry Loop: starts game
- Game Entry Loop → Save and Load: creates manager
- Save and Load → Tilemap and Queries: captures and restores
- Save and Load → Player: captures and restores
- Save and Load → Items and Drops: captures and restores
- Save and Load → Enemies: captures and restores
- Save and Load → Traps: captures and restores
- Save and Load → Inventory: captures and restores
- Save and Load → Decorations: captures and restores
- Save and Load → Lighting and Fog: captures and restores
- Enemies → Enemy Intent and AI: updates intent
- Enemy Intent and AI → Pathfinding Queue: requests paths
- Pathfinding Queue → A* Pathfinding: processes requests
- Enemy Intent and AI → Player: targets player
- Awakening Director → Biome Enemy Spawners: dispatches spawns
- Room Initialization → Biome Enemy Spawners: selects biome spawns
- Room Initialization → Tilemap and Queries: initializes room
- Decorations → Tilemap and Queries: updates tile entities
- Traps → Tilemap and Queries: queries nearby tiles
- Items and Drops → Tilemap and Queries: queries nearby items
- Items and Drops → Inventory: adds pickups
- Items and Drops → Runes: updates runes
- Runes → Inventory: replaces active runes
- Player → Status Effects: manages effects
- Traps → Lighting and Fog: removes trap lights
- Particles → Game Entry Loop: renders effects