# mirondorin/dq-rl architecture

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

- Interactive diagram: https://gitdiagram.com/mirondorin/dq-rl
- Repository: https://github.com/mirondorin/dq-rl

## Overview

1. **Project shape**
   - This is a **Godot 2D game client** (scene/script-driven), packaged as `GD_Client.exe/.pck` and a demo build in `demo/`.
   - The repo is mostly **content + gameplay code**, not a general application backend. There is no visible server/service layer in the tree.

2. **Runtime entry and session flow**
   - The main user flow appears to start in **`scenes/Menu.tscn`**, move through **`scenes/lobby.tscn`**, then into **`scenes/MainScene.tscn`** where actual gameplay runs.
   - Supporting launch assets like `keybinds.ini` and `open_2_clients.bat` suggest the build supports configurable input and possibly multi-instance testing.

3. **World composition**
   - The game world is assembled from **level scenes** (`scenes/levels/level0.tscn` through `level6.tscn`) plus reusable environment scenes like **parallax backgrounds** and **world boundaries**.
   - `MainScene.tscn` is the likely orchestration layer that places level geometry, spawn points, doors, HUD, and combat entities into one playable session.

4. **Progression and room transitions**
   - Door and transition logic is split into dedicated scene/script pairs:
     - `BossDoor.tscn` / `scripts/BossDoor.gd`
     - `NewLevelDoor.tscn` / `scripts/NewLevelDoor.gd`
     - `DoorBase.gd`
   - These act as progression boundaries between rooms/levels and likely gate movement based on combat or level state.

5. **Player subsystem**
   - The player is isolated as **`PlayableCharacter.tscn`** with logic in **`scripts/PlayableCharacter.gd`**.
   - Input and action handling are likely driven by key bindings plus the HUD/UI layer, with the character interacting with weapons, pickups, and level transitions rather than owning the entire game flow.

6. **Combat architecture**
   - Combat uses a clear inheritance hierarchy:
     - `Entity.gd` and `PhysicsEntity.gd` for shared actor behavior
     - `scripts/Weapons/Weapon_base.gd` and `scripts/mobs/Mob_base.gd` for weapon/enemy common logic
   - Concrete weapon scenes/scripts include **Hammer**, **WeaponProjectile**, **WeaponBomb**, and **HomingProjectile** variants, each with separate projectile/bullet scenes.

7. **Enemy and boss layer**
   - Regular enemies and bosses are separated into reusable mob scenes under `scenes/Mobs/` with matching scripts under `scripts/mobs/`.
   - Bosses include **BoDBoss** and **GolemBoss**; smaller enemy/projectile behaviors are split into **MobProjectile** and **MobHomingProjectile**.
   - This suggests a pattern where enemy AI, attack patterns, and death behavior are encapsulated per mob type, while shared movement/health logic lives in the base mob script.

8. **Spawner-driven encounter setup**
   - `DynamicSpawner.tscn`, `EnemySpawner.tscn`, and their scripts indicate that enemy placement is **runtime-driven**, not fully hardcoded into levels.
   - This is a key architectural boundary: level scenes define the environment, while spawners inject encounters and scale difficulty during play.

9. **Pickups and progression rewards**
   - Item rewards are handled by dedicated pickup scenes/scripts:
     - `HealthPickup`
     - `MaxHealthPickup`
     - `DamageBoost`
     - `ItemPickup.gd`
   - These are separate from combat entities, which keeps reward logic distinct from enemy/player logic and makes level drops easy to reuse.

10. **UI/HUD layer**
   - `HUD.tscn` and `scripts/HUD.gd` form the player-facing state display and likely health/cooldown feedback.
   - `Cooldown.tscn` and `KeyButton.gd` suggest modular UI elements for action timers and control hints/remapping.

11. **Data, art, audio, and rendering support**
   - The game is heavily data-driven through Godot resources: tilesets (`tilesets/Terrain.tres`), materials (`materials/white.tres`), shaders, fonts, and many imported sounds.
   - Large asset packs under `assets/` provide tiles, character animations, cave backgrounds, HUD art, and sprite effects; these are referenced by scenes rather than embedded in code.

12. **Editor-time extension**
   - `addons/tool_button/` is an editor plugin, so the project includes custom Godot editor tooling.
   - That tooling is separate from runtime gameplay and likely exists to speed up scene/content authoring.

13. **Content organization**
   - The repository uses a strong **scene/script pairing convention**: gameplay objects are authored as `.tscn` scenes with matching `.gd` scripts in parallel folders.
   - This makes the architecture easy to diagram as reusable runtime modules connected through scene instancing and shared base classes.

14. **Likely high-level diagram boundaries**
   - A useful architecture diagram would show:
     - **Menu/Lobby flow** → **Main gameplay scene**
     - **Main scene** orchestrating **levels, spawners, doors, HUD**
     - **Player** and **mobs/bosses** interacting through **weapons/projectiles/pickups**
     - **Assets/resources** feeding all runtime scenes
     - **Editor addon/tooling** as a separate non-runtime boundary

Main entry points: [`scenes/MainScene.tscn`](https://github.com/mirondorin/dq-rl/blob/main/scenes/MainScene.tscn) (Main Scene), [`scenes/PlayableCharacter.tscn`](https://github.com/mirondorin/dq-rl/blob/main/scenes/PlayableCharacter.tscn) (Player), [`tilesets/Terrain.tres`](https://github.com/mirondorin/dq-rl/blob/main/tilesets/Terrain.tres) (Assets & Resources), [`scenes/Weapons/WeaponProjectile.tscn`](https://github.com/mirondorin/dq-rl/blob/main/scenes/Weapons/WeaponProjectile.tscn) (Projectiles)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime flow"]
  node_menu["Menu<br/>scene<br/>[Menu.tscn]"]
  node_lobby["Lobby<br/>scene/script<br/>[lobby.tscn]"]
  node_main_scene["Main Scene<br/>scene/script<br/>[MainScene.tscn]"]
  node_gamestate[("Game State<br/>autoload/state<br/>[Gamestate.gd]")]
  node_settings[("Settings<br/>autoload/config<br/>[GlobalSettings.gd]")]
end

subgraph group_combat["Combat entities"]
  node_player["Player<br/>character"]
  node_entity_base["Entity Base<br/>actor base<br/>[Entity.gd]"]
  node_physics_base["Physics Base<br/>physics actor<br/>[PhysicsEntity.gd]"]
  node_mob_base["Mob Base<br/>enemy base<br/>[Mob_base.gd]"]
  node_bosses["Bosses<br/>enemy scenes<br/>[BoDBoss.tscn]"]
  node_projectiles["Projectiles<br/>weapon/projectile"]
  node_weapons["Weapons<br/>combat scenes<br/>[Weapon.tscn]"]
  node_pickups["Pickups<br/>reward scenes<br/>[HealthPickup.tscn]"]
end

subgraph group_content["World content"]
  node_levels["Levels<br/>environment scenes<br/>[level0.tscn]"]
  node_doors["Doors<br/>transition scenes<br/>[NewLevelDoor.tscn]"]
  node_spawners["Spawners<br/>encounter systems<br/>[EnemySpawner.tscn]"]
  node_hud["HUD<br/>ui scene<br/>[HUD.tscn]"]
  node_environment["Environment<br/>world scenes"]
end

subgraph group_tooling["Tooling and assets"]
  node_addons["Editor Addon<br/>plugin<br/>[TB_Plugin.gd]"]
  node_assets["Assets & Resources<br/>[Terrain.tres]"]
end

node_menu -->|"start"| node_lobby
node_lobby -->|"enter run"| node_main_scene
node_main_scene -->|"instance"| node_levels
node_main_scene -->|"place gates"| node_doors
node_main_scene -->|"spawn encounters"| node_spawners
node_main_scene -->|"attach UI"| node_hud
node_main_scene -->|"spawn player"| node_player
node_main_scene -->|"use scenery"| node_environment
node_player -->|"inherits"| node_entity_base
node_entity_base -->|"extends"| node_physics_base
node_bosses -->|"inherits"| node_mob_base
node_projectiles -->|"used by"| node_weapons
node_weapons -->|"emit"| node_projectiles
node_mob_base -->|"attack with"| node_projectiles
node_pickups -->|"affect"| node_player
node_doors -->|"check state"| node_gamestate
node_spawners -->|"read progress"| node_gamestate
node_hud -->|"display state"| node_gamestate
node_settings -->|"bind input"| node_player
node_assets -->|"feed content"| node_levels
node_assets -->|"feed visuals"| node_weapons
node_assets -->|"feed ui"| node_hud
node_addons -.->|"editor aid"| node_main_scene

click node_menu "https://github.com/mirondorin/dq-rl/blob/main/scenes/Menu.tscn"
click node_lobby "https://github.com/mirondorin/dq-rl/blob/main/scenes/lobby.tscn"
click node_main_scene "https://github.com/mirondorin/dq-rl/blob/main/scenes/MainScene.tscn"
click node_gamestate "https://github.com/mirondorin/dq-rl/blob/main/scripts/Gamestate.gd"
click node_settings "https://github.com/mirondorin/dq-rl/blob/main/scripts/GlobalSettings.gd"
click node_player "https://github.com/mirondorin/dq-rl/blob/main/scenes/PlayableCharacter.tscn"
click node_entity_base "https://github.com/mirondorin/dq-rl/blob/main/scripts/Entity.gd"
click node_physics_base "https://github.com/mirondorin/dq-rl/blob/main/scripts/PhysicsEntity.gd"
click node_mob_base "https://github.com/mirondorin/dq-rl/blob/main/scripts/mobs/Mob_base.gd"
click node_bosses "https://github.com/mirondorin/dq-rl/blob/main/scenes/Mobs/BoDBoss.tscn"
click node_projectiles "https://github.com/mirondorin/dq-rl/blob/main/scenes/Weapons/WeaponProjectile.tscn"
click node_weapons "https://github.com/mirondorin/dq-rl/blob/main/scenes/Weapons/Weapon.tscn"
click node_pickups "https://github.com/mirondorin/dq-rl/blob/main/scenes/items/HealthPickup.tscn"
click node_levels "https://github.com/mirondorin/dq-rl/blob/main/scenes/levels/level0.tscn"
click node_doors "https://github.com/mirondorin/dq-rl/blob/main/scenes/NewLevelDoor.tscn"
click node_spawners "https://github.com/mirondorin/dq-rl/blob/main/scenes/EnemySpawner.tscn"
click node_hud "https://github.com/mirondorin/dq-rl/blob/main/scenes/HUD.tscn"
click node_environment "https://github.com/mirondorin/dq-rl/blob/main/scenes/other/ParallaxBackground.tscn"
click node_addons "https://github.com/mirondorin/dq-rl/blob/main/addons/tool_button/TB_Plugin.gd"
click node_assets "https://github.com/mirondorin/dq-rl/blob/main/tilesets/Terrain.tres"

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_menu,node_lobby,node_main_scene,node_gamestate,node_settings toneBlue
class node_player,node_entity_base,node_physics_base,node_mob_base,node_bosses,node_projectiles,node_weapons,node_pickups toneAmber
class node_levels,node_doors,node_spawners,node_hud,node_environment toneMint
class node_addons,node_assets toneRose
```

## Components

### Runtime flow

Menu to lobby to main gameplay and supporting session systems.

- [Menu](https://github.com/mirondorin/dq-rl/blob/main/scenes/Menu.tscn): scene · Entry screen and initial navigation. · `scenes/Menu.tscn`
- [Lobby](https://github.com/mirondorin/dq-rl/blob/main/scenes/lobby.tscn): scene/script · Interim setup and session staging. · `scenes/lobby.tscn`
- [Main Scene](https://github.com/mirondorin/dq-rl/blob/main/scenes/MainScene.tscn): scene/script · Orchestrates a playable run and assembles the session. · `scenes/MainScene.tscn`
- [Game State](https://github.com/mirondorin/dq-rl/blob/main/scripts/Gamestate.gd): autoload/state · Global session state shared across scenes. · `scripts/Gamestate.gd`
- [Settings](https://github.com/mirondorin/dq-rl/blob/main/scripts/GlobalSettings.gd): autoload/config · Global configuration and input-related settings. · `scripts/GlobalSettings.gd`

### Combat entities

Player, enemies, weapons, projectiles, and pickups.

- [Player](https://github.com/mirondorin/dq-rl/blob/main/scenes/PlayableCharacter.tscn): character · Controllable character and input-driven actions. · `scenes/PlayableCharacter.tscn`
- [Entity Base](https://github.com/mirondorin/dq-rl/blob/main/scripts/Entity.gd): actor base · Shared actor behavior for movable living entities. · `scripts/Entity.gd`
- [Physics Base](https://github.com/mirondorin/dq-rl/blob/main/scripts/PhysicsEntity.gd): physics actor · Physics-enabled common behavior for actors. · `scripts/PhysicsEntity.gd`
- [Mob Base](https://github.com/mirondorin/dq-rl/blob/main/scripts/mobs/Mob_base.gd): enemy base · Shared enemy logic for health, movement, and death. · `scripts/mobs/Mob_base.gd`
- [Bosses](https://github.com/mirondorin/dq-rl/blob/main/scenes/Mobs/BoDBoss.tscn): enemy scenes · Major encounters with dedicated behaviors and patterns. · `scenes/Mobs/BoDBoss.tscn`
- [Projectiles](https://github.com/mirondorin/dq-rl/blob/main/scenes/Weapons/WeaponProjectile.tscn): weapon/projectile · Weapon and enemy projectile variants. · `scenes/Weapons/WeaponProjectile.tscn`
- [Weapons](https://github.com/mirondorin/dq-rl/blob/main/scenes/Weapons/Weapon.tscn): combat scenes · Player weapon implementations and attack variants. · `scenes/Weapons/Weapon.tscn`
- [Pickups](https://github.com/mirondorin/dq-rl/blob/main/scenes/items/HealthPickup.tscn): reward scenes · Health and stat rewards collected during play. · `scenes/items/HealthPickup.tscn`

### World content

Levels, doors, HUD, and reusable environment scenes.

- [Levels](https://github.com/mirondorin/dq-rl/blob/main/scenes/levels/level0.tscn): environment scenes · Reusable level maps and room layouts. · `scenes/levels/level0.tscn`
- [Doors](https://github.com/mirondorin/dq-rl/blob/main/scenes/NewLevelDoor.tscn): transition scenes · Progression gates between rooms and levels. · `scenes/NewLevelDoor.tscn`
- [Spawners](https://github.com/mirondorin/dq-rl/blob/main/scenes/EnemySpawner.tscn): encounter systems · Runtime enemy injection and encounter pacing. · `scenes/EnemySpawner.tscn`
- [HUD](https://github.com/mirondorin/dq-rl/blob/main/scenes/HUD.tscn): ui scene · Player-facing state display and cooldown feedback. · `scenes/HUD.tscn`
- [Environment](https://github.com/mirondorin/dq-rl/blob/main/scenes/other/ParallaxBackground.tscn): world scenes · Backgrounds, boundaries, and other reusable world pieces. · `scenes/other/ParallaxBackground.tscn`

### Tooling and assets

Editor extension and shared resources that support the runtime.

- [Editor Addon](https://github.com/mirondorin/dq-rl/blob/main/addons/tool_button/TB_Plugin.gd): plugin · Godot editor tooling for faster content authoring. · `addons/tool_button/TB_Plugin.gd`
- [Assets & Resources](https://github.com/mirondorin/dq-rl/blob/main/tilesets/Terrain.tres): resources · Tiles, fonts, shaders, sounds, and imported art assets. · `tilesets/Terrain.tres`

## Connections

- Menu → Lobby: start · Menu leads into lobby/setup.
- Lobby → Main Scene: enter run · Lobby transitions into gameplay.
- Main Scene → Levels: instance · Main scene composes the active level layout.
- Main Scene → Doors: place gates · Main scene wires progression boundaries.
- Main Scene → Spawners: spawn encounters · Main scene activates runtime enemy spawning.
- Main Scene → HUD: attach UI · Main scene mounts the player HUD.
- Main Scene → Player: spawn player · Main scene instantiates the controllable character.
- Main Scene → Environment: use scenery · Main scene includes background and boundary scenes.
- Player → Entity Base: inherits · Player builds on shared entity behavior.
- Entity Base → Physics Base: extends · Entity logic sits on physics-enabled base behavior.
- Bosses → Mob Base: inherits · Bosses reuse shared enemy base logic.
- Projectiles → Weapons: used by · Projectile scenes support weapon attacks.
- Weapons → Projectiles: emit · Weapons create projectiles or bullets.
- Mob Base → Projectiles: attack with · Enemy behaviors can drive projectile patterns.
- Pickups → Player: affect · Pickups modify player health or stats.
- Doors → Game State: check state · Doors likely gate progression using shared game state.
- Spawners → Game State: read progress · Spawner logic can scale encounters from shared state.
- HUD → Game State: display state · HUD reflects run state and player status.
- Settings → Player: bind input · Global settings support player controls.
- Assets & Resources → Levels: feed content · Resources provide tiles, art, audio, and materials for scenes.
- Assets & Resources → Weapons: feed visuals · Weapon scenes rely on shared art and sound resources.
- Assets & Resources → HUD: feed ui · HUD uses shared fonts, icons, and materials.
- Editor Addon → Main Scene: editor aid · Editor plugin supports authoring and inspection.