# theshaggydev/unto-deepest-depths-prototype architecture

> Architecture diagram of the GitHub repository theshaggydev/unto-deepest-depths-prototype, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/theshaggydev/unto-deepest-depths-prototype
- Repository: https://github.com/theshaggydev/unto-deepest-depths-prototype

## Overview

##### Project type and purpose
- This is a Godot 4 prototype for a turn-based tactical game (“Unto Deepest Depths Prototype”).
- It demonstrates the core game loop, battle scenes, unit composition, map handling, and global services (event bus, navigation).

##### File structure
- Top level: project.godot (main Godot project), README, license, .gitignore.
- src/
- battle/: battle scene (`battle.tscn` + `battle.gd`) and units sub-nodes
- global/: singleton-style scripts (`config.gd`, `event_bus.gd`, `navigation.gd`)
- maps/: tilesets (`.tres`), highlight scene, test map
- unit/: unit scene (`unit.tscn` + `unit.gd`), art (spriteframes), definitions (`.tres` + `unit_definition.gd`), components (health bar), type_components (per-class ability generators), action_collection/definition

##### README
- Confirms this is an early learning example of how to structure a turn-based game in GDScript.

a. Main components
- Godot 4 Engine (runtime host)
- Scenes & Node Hierarchies
– BattleScene (BattleManager + UnitContainer + MapContainer)
– UnitScene (Unit node + Components + Sprite)
– HighlightScene (visual feedback)
- Global Services (singletons)
– EventBus (pub/sub for turn events, actions)
– Navigation (grid graph, pathfinding)
– Config (game settings, constants)
- Data Assets
– .tres resources (unit definitions, abilities DB, tilesets, spriteframes)
- Type-specific Components
– MageAttackGenerator, etc., attached under unit nodes

b. Relationships and interactions
- BattleManager loads MapContainer and spawns UnitScenes based on unit_definition resources.
- On each turn, BattleManager emits events via EventBus (“unit_selected”, “action_performed”).
- UnitScene scripts subscribe to EventBus, query their ActionCollection/Definition to execute abilities.
- Navigation singleton calculates paths for movement on Map grid.
- HighlightScene listens to EventBus for “tile_hover”/“move_range” and renders overlays.

c. Architectural patterns & principles
- Node-scene composition (Godot’s scene graph) as a form of ECS: each unit is a root node with child “component” nodes.
- EventBus for decoupled messaging between controllers, view (scenes), and model (definitions).
- Resource-driven definitions (separate data .tres assets from logic scripts).

d. Key technologies, frameworks & libraries
- Godot 4 engine, GDScript
- .tscn scene files and node hierarchies
- .tres resource files for data assets
- Godot’s built-in navigation API (or custom grid nav in navigation.gd)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Engine
    Engine["Godot 4 Engine"]:::engine

    %% Scenes
    subgraph "Scenes"
        direction TB
        BattleScene["BattleScene\n(battle.tscn)"]:::scene
        UnitScene["UnitScene\n(unit.tscn)"]:::scene
        HighlightScene["HighlightScene\n(cell_highlights.tscn)"]:::scene
    end

    %% Singletons / Global Services
    subgraph "Global Services"
        direction TB
        EventBus["EventBus\n(event_bus.gd)"]:::service
        Navigation["Navigation\n(navigation.gd)"]:::service
        Config["Config\n(config.gd)"]:::service
    end

    %% Data Resources
    subgraph "Data Resources"
        direction TB
        Tileset["Grass Tileset\n(grass_open_tileset.tres)"]:::data
        TestMap["Test Map\n(test)"]:::data
        UnitDefs["Unit Definitions"]:::data
        SpriteFrames["SpriteFrames"]:::data
    end

    %% UnitSubcomponents
    subgraph "UnitScene Components"
        direction TB
        HealthBar["HealthBar\n(health_bar.tscn)"]:::component
        AbilitiesDB["AbilitiesDB\n(abilities_db.tscn)"]:::component
        TypeComponents["TypeComponents"]:::component
        ArtAssets["Art Assets\n(spriteframes)"]:::component
    end

    %% Type-specific Components
    subgraph "Type-Specific Components"
        direction TB
        MageGenerator["MageAttackFlameGenerator\n(mage_attack_flame_generator.tscn)"]:::component
    end

    %% Definitions Resources
    subgraph "Unit Definition Files"
        direction TB
        ArcherDef["archer.tres"]:::data
        KnightDef["knight.tres"]:::data
        MageDef["mage.tres"]:::data
        PeasantDef["peasant.tres"]:::data
    end

    %% SpriteFrames Resources
    subgraph "SpriteFrame Files"
        direction TB
        ArcherSF["archer_spriteframes.tres"]:::data
        KnightSF["knight_spriteframes.tres"]:::data
        MageSF["mage_spriteframes.tres"]:::data
        FlameSF["tile_flame_spriteframes.tres"]:::data
        PeasantSF["peasant_spriteframes.tres"]:::data
        RogueSF["rogue_spriteframes.tres"]:::data
    end

    %% Action System
    ActionCollection["ActionCollection API\n(action_collection.gd)"]:::component
    ActionDefinition["ActionDefinition API\n(action_definition.gd)"]:::component
    UnitDefLoader["DefinitionLoader\n(unit_definition.gd)"]:::component

    %% Relationships
    Engine --> Scenes
    Scenes --> EventBus
    Scenes --> Navigation
    Scenes --> Config

    BattleScene -->|loads/spawns| UnitScene
    BattleScene -->|publishes events| EventBus
    UnitScene -->|subscribes to| EventBus
    UnitScene -->|uses| Navigation
    UnitScene -->|queries| UnitDefLoader
    UnitDefLoader -->|loads| UnitDefs

    HighlightScene -->|listens to| EventBus
    HighlightScene -->|renders on| Tileset

    UnitScene --> UnitSubcomponents
    UnitSubcomponents --> HealthBar
    UnitSubcomponents --> AbilitiesDB
    UnitSubcomponents --> TypeComponents
    UnitSubcomponents --> ArtAssets

    TypeComponents --> MageGenerator

    DataResources -->|provides| BattleScene
    DataResources -->|provides| UnitScene

    UnitDefs --> ArcherDef
    UnitDefs --> KnightDef
    UnitDefs --> MageDef
    UnitDefs --> PeasantDef

    SpriteFrames --> ArcherSF
    SpriteFrames --> KnightSF
    SpriteFrames --> MageSF
    SpriteFrames --> FlameSF
    SpriteFrames --> PeasantSF
    SpriteFrames --> RogueSF

    %% Click Events
    click BattleScene "https://github.com/theshaggydev/unto-deepest-depths-prototype/blob/main/src/battle/battle.tscn"
    click BattleScene "https://github.com/theshaggydev/unto-deepest-depths-prototype/blob/main/src/battle/battle.gd"
    click UnitScene "https://github.com/theshaggydev/unto-deepest-depths-prototype/blob/main/src/unit/unit.tscn"
    click UnitScene "https://github.com/theshaggydev/unto-deepest-depths-prototype/blob/main/src/unit/unit.gd"
    click HealthBar "https://github.com/theshaggydev/unto-deepest-depths-prototype/blob/main/src/unit/components/health_bar/health_bar.tscn"
    click HealthBar "https://github.com/theshaggydev/unto-deepest-depths-prototype/blob/main/src/unit/components/health_bar/health_bar.gd"
    click AbilitiesDB "https://github.com/theshaggydev/unto-deepest-depths-prototype/blob/main/src/battle/nodes/units/components/abilities_db.tscn"
    click AbilitiesDB "https://github.com/theshaggydev/unto-deepest-depths-prototype/blob/main/src/battle/nodes/units/components/abilities_db.gd"
    click HighlightScene "https://github.com/theshaggydev/unto-deepest-depths-prototype/blob/main/src/maps/highlights/cell_highlights.tscn"
    click HighlightScene "https://github.com/theshaggydev/unto-deepest-depths-prototype/blob/main/src/maps/highlights/cell_highlights.gd"
    click EventBus "https://github.com/theshaggydev/unto-deepest-depths-prototype/blob/main/src/global/event_bus.gd"
    click Navigation "https://github.com/theshaggydev/unto-deepest-depths-prototype/blob/main/src/global/navigation.gd"
    click Config "https://github.com/theshaggydev/unto-deepest-depths-prototype/blob/main/src/global/config.gd"
    click Tileset "https://github.com/theshaggydev/unto-deepest-depths-prototype/blob/main/src/maps/grass_open/grass_open_tileset.tres"
    click TestMap "https://github.com/theshaggydev/unto-deepest-depths-prototype/tree/main/src/maps/test"
    click ArcherDef "https://github.com/theshaggydev/unto-deepest-depths-prototype/blob/main/src/unit/definitions/archer.tres"
    click KnightDef "https://github.com/theshaggydev/unto-deepest-depths-prototype/blob/main/src/unit/definitions/knight.tres"
    click MageDef "https://github.com/theshaggydev/unto-deepest-depths-prototype/blob/main/src/unit/definitions/mage.tres"
    click PeasantDef "https://github.com/theshaggydev/unto-deepest-depths-prototype/blob/main/src/unit/definitions/peasant.tres"
    click UnitDefLoader "https://github.com/theshaggydev/unto-deepest-depths-prototype/blob/main/src/unit/definitions/unit_definition.gd"
    click ActionCollection "https://github.com/theshaggydev/unto-deepest-depths-prototype/blob/main/src/unit/action_collection.gd"
    click ActionDefinition "https://github.com/theshaggydev/unto-deepest-depths-prototype/blob/main/src/unit/action_definition.gd"
    click ArcherSF "https://github.com/theshaggydev/unto-deepest-depths-prototype/blob/main/src/unit/art/archer/archer_spriteframes.tres"
    click KnightSF "https://github.com/theshaggydev/unto-deepest-depths-prototype/blob/main/src/unit/art/knight/knight_spriteframes.tres"
    click MageSF "https://github.com/theshaggydev/unto-deepest-depths-prototype/blob/main/src/unit/art/mage/mage_spriteframes.tres"
    click FlameSF "https://github.com/theshaggydev/unto-deepest-depths-prototype/blob/main/src/unit/art/mage/tile_flame_spriteframes.tres"
    click PeasantSF "https://github.com/theshaggydev/unto-deepest-depths-prototype/blob/main/src/unit/art/peasant/peasant_spriteframes.tres"
    click RogueSF "https://github.com/theshaggydev/unto-deepest-depths-prototype/blob/main/src/unit/art/rogue/rogue_spriteframes.tres"
    click MageGenerator "https://github.com/theshaggydev/unto-deepest-depths-prototype/blob/main/src/unit/type_components/mage/mage_attack_flame_generator.tscn"
    click MageGenerator "https://github.com/theshaggydev/unto-deepest-depths-prototype/blob/main/src/unit/type_components/mage/mage_attack_flame_generator.gd"

    %% Styles
    classDef engine fill:#f9f,stroke:#333,stroke-width:1px
    classDef scene fill:#ccf,stroke:#333,stroke-width:1px
    classDef service fill:#cfc,stroke:#333,stroke-width:1px
    classDef data fill:#ffc,stroke:#333,stroke-width:1px
    classDef component fill:#eee,stroke:#333,stroke-width:1px
```
