# modestv/dreamisle architecture

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

- Interactive diagram: https://gitdiagram.com/modestv/dreamisle
- Repository: https://github.com/modestv/dreamisle

## Overview

1. `Dreamisle` is a single-player 2D top-down game built in Python with Pygame. The repository is organized around one runtime app, a scene-based game state machine, and a set of reusable gameplay systems that are shared across scenes.

2. The entry point is `main.py`, which hands control to `src/dreamisle/game.py`. `Game` is the central coordinator: it owns the window, main loop, scene switching, save/load flow, and the overall presentation scale/resolution behavior.

3. The core architectural boundary is the scene system under `src/dreamisle/scenes/`. Each scene represents one screen or mode of play: menu, hub, mine, shop, inventory, pause, settings, and end. `scenes/base.py` provides the common scene contract, while the `Game` object swaps scenes rather than embedding all UI and gameplay logic in one loop.

4. The world is split into two major play spaces. `scenes/hub.py` handles the fixed island hub with buildings and farm/monument interactions, while `scenes/mine.py` handles the procedural dungeon. The README makes clear that progression flows from the hub into the mine, then back to the hub through selling, upgrading, and restoration tasks.

5. The mine subsystem is the most algorithm-heavy part of the repo. `src/dreamisle/algorithms.py` contains BSP generation, BFS/flood-fill reachability checks, A* pathfinding, weighted selection, spatial hashing, and PRD. These algorithms support level generation, zombie navigation, loot proximity queries, and controlled randomness.

6. Game entities and progression are modeled in focused domain modules: `player.py`, `models.py`, `items.py`, `inventory.py`, `shop.py`, `upgrades.py`, `balance.py`, and `game_data.py`. This suggests a separation between stateful runtime objects (`player`, inventory, upgrades) and static definitions/data (`items`, balance values, item tables, paths, assets).

7. The economic loop is explicit in the architecture. Ore and berries are gathered in the world, converted through the shop into gems, coins, inventory capacity, and upgrades, then spent toward restoring the monument. The `shop.py` and `upgrades.py` modules are the main boundary for that progression logic.

8. Rendering and atmosphere are supported by dedicated systems rather than being embedded in scenes. `tilemap.py` likely handles world tile/grid representation, `lighting.py` provides the mine lightmap effect, `audio.py` manages music and sound playback, and `assets.py` centralizes asset loading and lookup. These modules form the presentation layer that scenes consume.

9. Persistence is handled by `save_system.py`, with the README stating that the game saves to one JSON file and restores the current scene, including the mine state. That means save/load is a cross-cutting subsystem that must serialize scene state, player progression, inventory, and world progression consistently.

10. User-facing text and options are separated from gameplay rules. `localization.py` covers `ru/en` language switching, while `config.py` contains application-level settings such as window size. `src/dreamisle/scenes/settings.py` is the UI surface for those configuration changes.

11. Asset structure mirrors the runtime domains: sprites are grouped by buildings, entities, items, and terrain; audio is split by music tracks; UI assets are separate. This indicates the game is data-driven at the presentation layer, with code loading named assets rather than hardcoding media details.

12. The test suite maps well to the architecture: `test_algorithms.py` validates the procedural/pathfinding core, `test_gameplay_systems.py` covers player/economy/inventory systems, `test_scene_flows.py` checks scene transitions, `test_save_system.py` verifies persistence, and `test_assets_and_data.py` guards content/data wiring. The tests reinforce that the repo is organized around independently verifiable subsystems rather than one monolithic game file.

Main entry points: [`src/dreamisle/game.py`](https://github.com/modestv/dreamisle/blob/main/src/dreamisle/game.py) (Game), [`src/dreamisle/scenes/hub.py`](https://github.com/modestv/dreamisle/blob/main/src/dreamisle/scenes/hub.py) (Hub), [`src/dreamisle/scenes/mine.py`](https://github.com/modestv/dreamisle/blob/main/src/dreamisle/scenes/mine.py) (Mine), [`src/dreamisle/save_system.py`](https://github.com/modestv/dreamisle/blob/main/src/dreamisle/save_system.py) (Save System)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main["Main<br/>entrypoint<br/>[main.py]"]
  node_game["Game<br/>app coordinator<br/>[game.py]"]
end

subgraph group_scenes["Scenes"]
  node_scene_base["Scene Base<br/>scene contract<br/>[base.py]"]
  node_menu_scene["Menu<br/>scene<br/>[menu.py]"]
  node_hub_scene["Hub<br/>scene<br/>[hub.py]"]
  node_mine_scene["Mine<br/>scene<br/>[mine.py]"]
  node_shop_scene["Shop<br/>scene<br/>[shop.py]"]
  node_inventory_scene["Inventory<br/>scene<br/>[inventory.py]"]
  node_pause_scene["Pause<br/>scene<br/>[pause.py]"]
  node_settings_scene["Settings<br/>scene<br/>[settings.py]"]
  node_end_scene["End<br/>scene<br/>[end.py]"]
end

subgraph group_systems["Systems"]
  node_algorithms{{"Algorithms<br/>procedural core<br/>[algorithms.py]"}}
  node_player(("Player<br/>runtime state<br/>[player.py]"))
  node_inventory[("Inventory<br/>storage system<br/>[inventory.py]")]
  node_shop["Shop Logic<br/>economy system<br/>[shop.py]"]
  node_upgrades["Upgrades<br/>progression system<br/>[upgrades.py]"]
  node_save_system[("Save System<br/>persistence<br/>[save_system.py]")]
  node_presentation["Presentation<br/>render/audio"]
end

subgraph group_data["Data"]
  node_game_data["Game Data<br/>definitions<br/>[game_data.py]"]
  node_config["Config<br/>app settings<br/>[config.py]"]
end

node_main -->|"starts"| node_game
node_game -->|"uses"| node_scene_base
node_game -->|"opens"| node_menu_scene
node_game -->|"switches to"| node_hub_scene
node_game -->|"switches to"| node_mine_scene
node_game -->|"switches to"| node_shop_scene
node_game -->|"switches to"| node_inventory_scene
node_game -->|"switches to"| node_pause_scene
node_game -->|"switches to"| node_settings_scene
node_game -->|"switches to"| node_end_scene
node_hub_scene -->|"enters"| node_mine_scene
node_mine_scene -->|"uses"| node_algorithms
node_mine_scene -->|"updates"| node_player
node_mine_scene -->|"fills"| node_inventory
node_hub_scene -->|"uses"| node_shop
node_shop_scene -->|"drives"| node_shop
node_inventory_scene -->|"drives"| node_inventory
node_hub_scene -->|"uses"| node_upgrades
node_game -->|"saves"| node_save_system
node_save_system -->|"serializes"| node_player
node_save_system -->|"serializes"| node_inventory
node_save_system -->|"restores"| node_hub_scene
node_settings_scene -->|"edits"| node_config
node_game -->|"loads"| node_presentation
node_presentation -->|"reads"| node_game_data
node_game -->|"uses"| node_game_data

click node_main "https://github.com/modestv/dreamisle/blob/main/main.py"
click node_game "https://github.com/modestv/dreamisle/blob/main/src/dreamisle/game.py"
click node_scene_base "https://github.com/modestv/dreamisle/blob/main/src/dreamisle/scenes/base.py"
click node_menu_scene "https://github.com/modestv/dreamisle/blob/main/src/dreamisle/scenes/menu.py"
click node_hub_scene "https://github.com/modestv/dreamisle/blob/main/src/dreamisle/scenes/hub.py"
click node_mine_scene "https://github.com/modestv/dreamisle/blob/main/src/dreamisle/scenes/mine.py"
click node_shop_scene "https://github.com/modestv/dreamisle/blob/main/src/dreamisle/scenes/shop.py"
click node_inventory_scene "https://github.com/modestv/dreamisle/blob/main/src/dreamisle/scenes/inventory.py"
click node_pause_scene "https://github.com/modestv/dreamisle/blob/main/src/dreamisle/scenes/pause.py"
click node_settings_scene "https://github.com/modestv/dreamisle/blob/main/src/dreamisle/scenes/settings.py"
click node_end_scene "https://github.com/modestv/dreamisle/blob/main/src/dreamisle/scenes/end.py"
click node_algorithms "https://github.com/modestv/dreamisle/blob/main/src/dreamisle/algorithms.py"
click node_player "https://github.com/modestv/dreamisle/blob/main/src/dreamisle/player.py"
click node_inventory "https://github.com/modestv/dreamisle/blob/main/src/dreamisle/inventory.py"
click node_shop "https://github.com/modestv/dreamisle/blob/main/src/dreamisle/shop.py"
click node_upgrades "https://github.com/modestv/dreamisle/blob/main/src/dreamisle/upgrades.py"
click node_save_system "https://github.com/modestv/dreamisle/blob/main/src/dreamisle/save_system.py"
click node_game_data "https://github.com/modestv/dreamisle/blob/main/src/dreamisle/game_data.py"
click node_config "https://github.com/modestv/dreamisle/blob/main/src/dreamisle/config.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,node_game toneBlue
class node_scene_base,node_menu_scene,node_hub_scene,node_mine_scene,node_shop_scene,node_inventory_scene,node_pause_scene,node_settings_scene,node_end_scene toneAmber
class node_algorithms,node_player,node_inventory,node_shop,node_upgrades,node_save_system,node_presentation toneMint
class node_game_data,node_config toneRose
```

## Components

### Runtime

Executable entrypoint and app coordinator

- [Main](https://github.com/modestv/dreamisle/blob/main/main.py): entrypoint · Program entry script · `main.py`
- [Game](https://github.com/modestv/dreamisle/blob/main/src/dreamisle/game.py): app coordinator · Owns loop, scene switching, resolution, and save flow · `src/dreamisle/game.py`

### Scenes

Scene-based screens and modes

- [Scene Base](https://github.com/modestv/dreamisle/blob/main/src/dreamisle/scenes/base.py): scene contract · Shared interface for all scenes · `src/dreamisle/scenes/base.py`
- [Menu](https://github.com/modestv/dreamisle/blob/main/src/dreamisle/scenes/menu.py): scene · Title and start flow · `src/dreamisle/scenes/menu.py`
- [Hub](https://github.com/modestv/dreamisle/blob/main/src/dreamisle/scenes/hub.py): scene · Island hub, buildings, and restoration flow · `src/dreamisle/scenes/hub.py`
- [Mine](https://github.com/modestv/dreamisle/blob/main/src/dreamisle/scenes/mine.py): scene · Procedural dungeon exploration and combat · `src/dreamisle/scenes/mine.py`
- [Shop](https://github.com/modestv/dreamisle/blob/main/src/dreamisle/scenes/shop.py): scene · Trading and upgrade interface · `src/dreamisle/scenes/shop.py`
- [Inventory](https://github.com/modestv/dreamisle/blob/main/src/dreamisle/scenes/inventory.py): scene · Item and capacity management UI · `src/dreamisle/scenes/inventory.py`
- [Pause](https://github.com/modestv/dreamisle/blob/main/src/dreamisle/scenes/pause.py): scene · In-run pause overlay · `src/dreamisle/scenes/pause.py`
- [Settings](https://github.com/modestv/dreamisle/blob/main/src/dreamisle/scenes/settings.py): scene · User configuration UI · `src/dreamisle/scenes/settings.py`
- [End](https://github.com/modestv/dreamisle/blob/main/src/dreamisle/scenes/end.py): scene · Game over or completion screen · `src/dreamisle/scenes/end.py`

### Systems

Reusable gameplay and presentation subsystems

- [Algorithms](https://github.com/modestv/dreamisle/blob/main/src/dreamisle/algorithms.py): procedural core · Generation, pathfinding, reachability, and randomness helpers · `src/dreamisle/algorithms.py`
- [Player](https://github.com/modestv/dreamisle/blob/main/src/dreamisle/player.py): runtime state · Player stats, position, and progression state · `src/dreamisle/player.py`
- [Inventory](https://github.com/modestv/dreamisle/blob/main/src/dreamisle/inventory.py): storage system · Item slots, capacity, and item movement · `src/dreamisle/inventory.py`
- [Shop Logic](https://github.com/modestv/dreamisle/blob/main/src/dreamisle/shop.py): economy system · Trading, pricing, and conversion rules · `src/dreamisle/shop.py`
- [Upgrades](https://github.com/modestv/dreamisle/blob/main/src/dreamisle/upgrades.py): progression system · Persistent upgrade and restoration logic · `src/dreamisle/upgrades.py`
- [Save System](https://github.com/modestv/dreamisle/blob/main/src/dreamisle/save_system.py): persistence · JSON save and load of game and scene state · `src/dreamisle/save_system.py`
- **Presentation**: render/audio · Assets, tilemaps, lighting, audio, and localization

### Data

Static definitions, balance, and configuration

- [Game Data](https://github.com/modestv/dreamisle/blob/main/src/dreamisle/game_data.py): definitions · Static item tables, balance, and content metadata · `src/dreamisle/game_data.py`
- [Config](https://github.com/modestv/dreamisle/blob/main/src/dreamisle/config.py): app settings · Window and application settings · `src/dreamisle/config.py`

## Connections

- Main → Game: starts · Entry script launches the game coordinator
- Game → Scene Base: uses · Scene lifecycle is built on the shared scene contract
- Game → Menu: opens · Initial scene is the menu
- Game → Hub: switches to · Main progression returns to the hub
- Game → Mine: switches to · Core exploration scene
- Game → Shop: switches to · Trading scene
- Game → Inventory: switches to · Inventory management scene
- Game → Pause: switches to · Pause overlay scene
- Game → Settings: switches to · Settings UI scene
- Game → End: switches to · Completion or game-over scene
- Hub → Mine: enters · Hub progression leads into the mine
- Mine → Algorithms: uses · Mine generation, pathfinding, and loot queries depend on algorithms
- Mine → Player: updates · Movement, health, and progression state
- Mine → Inventory: fills · Loot is stored through the inventory system
- Hub → Shop Logic: uses · Selling and buying route through economy logic
- Shop → Shop Logic: drives · UI exposes trading rules
- Inventory → Inventory: drives · UI exposes storage management
- Hub → Upgrades: uses · Restoration and progression upgrades are applied here
- Game → Save System: saves · Centralized persistence for scene and progress state
- Save System → Player: serializes · Player progress is persisted
- Save System → Inventory: serializes · Inventory contents are persisted
- Save System → Hub: restores · Scene state includes current world progression
- Settings → Config: edits · Settings changes update application config
- Game → Presentation: loads · Core runtime consumes shared presentation systems
- Presentation → Game Data: reads · Assets and content metadata are driven by static definitions
- Game → Game Data: uses · Runtime content tables and balance data