# bubsee/kotowaza architecture

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

- Interactive diagram: https://gitdiagram.com/bubsee/kotowaza
- Repository: https://github.com/bubsee/kotowaza

## Overview

Kotowaza is a Pygame top-down exploration game. The main loop turns keyboard input into player movement, draws the tiled village and layered scenery, updates wandering villagers, and presents prompts and a notebook overlay. The documented exploration, randomized grass, responsive movement, and Japanese-inspired scenery map to these runtime modules. NPC pathfinding and collision details are supported by sampled code; the README’s broader promise of discovering secrets is not shown as a separate implemented system.

Main entry points: [`Main.py`](https://github.com/bubsee/kotowaza/blob/main/Main.py) (Game Loop), [`NPCs.py`](https://github.com/bubsee/kotowaza/blob/main/NPCs.py) (Villager Simulation), [`hitboxes.py`](https://github.com/bubsee/kotowaza/blob/main/hitboxes.py) (Collision Checks), [`map.py`](https://github.com/bubsee/kotowaza/blob/main/map.py) (Tile Map)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_game["Game Loop"]
  node_main["Game Loop<br/>[Main.py]"]
end

subgraph group_world["Village World"]
  node_map["Tile Map<br/>[map.py]"]
  node_village["Village Scenery<br/>[village_objects.py]"]
  node_entries["Building Entries<br/>[entries.py]"]
end

subgraph group_simulation["Movement and NPCs"]
  node_collision["Collision Checks<br/>[hitboxes.py]"]
  node_hitboxlist["Obstacle Rectangles"]
  node_npcs["Villager Simulation<br/>[NPCs.py]"]
end

subgraph group_presentation["Visuals and UI"]
  node_objects["Art Assets<br/>[objects.py]"]
  node_sprites["Player Animation<br/>[sprites.py]"]
  node_notebook["Notebook Overlay<br/>[Notebook.py]"]
  node_popups["Interaction Prompt<br/>[Text_popups.py]"]
end

node_player(("Player"))

node_player -->|"provides input"| node_main
node_main -->|"checks movement"| node_collision
node_collision -->|"reads tiles"| node_map
node_collision -->|"checks obstacles"| node_hitboxlist
node_main -->|"reads tiles"| node_map
node_main -->|"draws floor"| node_objects
node_main -->|"draws scenery"| node_village
node_village -->|"blits assets"| node_objects
node_main -->|"selects animation"| node_sprites
node_main -->|"updates villagers"| node_npcs
node_npcs -->|"routes on paths"| node_map
node_npcs -->|"checks obstacles"| node_hitboxlist
node_npcs -->|"gets spawn points"| node_entries
node_npcs -->|"uses idle sprites"| node_sprites
node_main -->|"draws overlay"| node_notebook
node_notebook -->|"uses notebook art"| node_objects
node_main -->|"shows prompt"| node_popups

click node_main "https://github.com/bubsee/kotowaza/blob/main/Main.py"
click node_map "https://github.com/bubsee/kotowaza/blob/main/map.py"
click node_objects "https://github.com/bubsee/kotowaza/blob/main/objects.py"
click node_village "https://github.com/bubsee/kotowaza/blob/main/village_objects.py"
click node_entries "https://github.com/bubsee/kotowaza/blob/main/entries.py"
click node_collision "https://github.com/bubsee/kotowaza/blob/main/hitboxes.py"
click node_hitboxlist "https://github.com/bubsee/kotowaza/blob/main/list_of_hitboxes.py"
click node_sprites "https://github.com/bubsee/kotowaza/blob/main/sprites.py"
click node_npcs "https://github.com/bubsee/kotowaza/blob/main/NPCs.py"
click node_notebook "https://github.com/bubsee/kotowaza/blob/main/Notebook.py"
click node_popups "https://github.com/bubsee/kotowaza/blob/main/Text_popups.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_main toneBlue
class node_map,node_village,node_entries toneAmber
class node_collision,node_hitboxlist,node_npcs toneMint
class node_objects,node_sprites,node_notebook,node_popups toneRose
class node_player toneIndigo
```

## Components

### Game Loop

- [Game Loop](https://github.com/bubsee/kotowaza/blob/main/Main.py): `Main.py`

### Village World

- [Tile Map](https://github.com/bubsee/kotowaza/blob/main/map.py): `map.py`
- [Village Scenery](https://github.com/bubsee/kotowaza/blob/main/village_objects.py): `village_objects.py`
- [Building Entries](https://github.com/bubsee/kotowaza/blob/main/entries.py): `entries.py`

### Movement and NPCs

- [Collision Checks](https://github.com/bubsee/kotowaza/blob/main/hitboxes.py): `hitboxes.py`
- [Obstacle Rectangles](https://github.com/bubsee/kotowaza/blob/main/list_of_hitboxes.py): `list_of_hitboxes.py`
- [Villager Simulation](https://github.com/bubsee/kotowaza/blob/main/NPCs.py): `NPCs.py`

### Visuals and UI

- [Art Assets](https://github.com/bubsee/kotowaza/blob/main/objects.py): `objects.py`
- [Player Animation](https://github.com/bubsee/kotowaza/blob/main/sprites.py): `sprites.py`
- [Notebook Overlay](https://github.com/bubsee/kotowaza/blob/main/Notebook.py): `Notebook.py`
- [Interaction Prompt](https://github.com/bubsee/kotowaza/blob/main/Text_popups.py): `Text_popups.py`

### Other components

- **Player**

## Connections

- Player → Game Loop: provides input
- Game Loop → Collision Checks: checks movement
- Collision Checks → Tile Map: reads tiles
- Collision Checks → Obstacle Rectangles: checks obstacles
- Game Loop → Tile Map: reads tiles
- Game Loop → Art Assets: draws floor
- Game Loop → Village Scenery: draws scenery
- Village Scenery → Art Assets: blits assets
- Game Loop → Player Animation: selects animation
- Game Loop → Villager Simulation: updates villagers
- Villager Simulation → Tile Map: routes on paths
- Villager Simulation → Obstacle Rectangles: checks obstacles
- Villager Simulation → Building Entries: gets spawn points
- Villager Simulation → Player Animation: uses idle sprites
- Game Loop → Notebook Overlay: draws overlay
- Notebook Overlay → Art Assets: uses notebook art
- Game Loop → Interaction Prompt: shows prompt