modestv/dreamisle

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.