# blackbarman/zach-tower architecture

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

- Interactive diagram: https://gitdiagram.com/blackbarman/zach-tower
- Repository: https://github.com/blackbarman/zach-tower

## Overview

##### Project Type and Purpose
- This is a Godot‐based “PuzzleTowerDefense” game project. It is neither a typical web app nor a compiler; it’s an interactive single‐player tower defense game built with Godot Engine.
- The file tree shows Godot scenes (`.tscn`), GDScript files (`.gd`), assets (audio, sprites, tiles), custom components, global scripts, entities, UI, and editor addons.

##### High-Level Architectural Overview
At runtime the game orchestrates several layers:
- Godot Engine Core – Node/Scene system, resource loading, rendering, input, audio.
- Game Systems – TurnManager, AudioManager, LevelManager.
- Domain Entities – Towers, Enemies, Bullets, SacredCrystal. Composed via Scenes + GDScript components.
- Data/Resources – TowerData, Wave definitions, enums, global state.
- Presentation/UI – MainMenu, HUD (WaveInfo, DefenseInfo, TowerSelecter, Popups).

##### Main Components and Their Interactions
- **Startup & Menu**
- project.godot ➔ loads MainMenu.tscn (UI nodes: StartBattleButton, MainMenuButtons)
- On “Start” ▶ LevelManager loads a specific level scene (lv_1.tscn).
- **Level & Game Loop**
- **LevelManager** (Levels/Level_Manager.gd & .tscn) instantiates:
– Tilemaps & PlacementTilemap
– SacredCrystal
– WaveResource & Waves
- **TurnManager** ticks the game:
– Spawns enemies per Wave resource
– Advances enemy movement, tower attacks
– Emits signals to AudioManager for sound cues
- **Entities**
- **Enemies** (Entities/Enemies) and **Towers** (Entities/Towers) are Scenes with attached GDScript:
– Common behaviours factored in Custom_Components (Health_Component, Weapon, AttackRangeComponent)
– Each entity uses signals to communicate damage, death, projectile spawning.
- **Bullets** (Entities/Bullets) are spawned by Tower. They detect collisions via HurtBoxArea2D/HitBoxArea2D.
- **Systems**
- **AudioManager** centralizes all sound playback (Assets/Audio).
- **GlobalState** & **TowerDataManager** maintain persistent data: unlocked towers, current state, enums.
- **UI Layer**
- HUD overlays (WaveInfo, DefenseInfo, Tooltip, fast_forward_button) subscribe to game signals (wave start/end, player actions).
- TowerSelecterUI lets players place towers; uses PlacementTilemap to validate spots.
- **Editor Add-Ons** (optional, not part of runtime): Asset_Drawer, SignalVisualizer, Todo_Manager – enhance Godot editor productivity.

##### Architectural Patterns & Design Principles
- **Entity-Component-System (ECS) style**: Entities are Godot Scenes, behaviours extracted into reusable Component scripts.
- **Signal-driven communication**: Components and systems publish/subscribe to Godot Signals (decoupling).
- **Resource-driven data**: Wave definitions and tower stats are stored as `.tres` resources.
- **Service Locator** for singletons: GlobalState, AudioManager, TurnManager loaded as Autoloads.

##### Essential Elements Checklist
- All major components labeled clearly
- Signal/event flows vs. control flows distinguished
- Annotations for file locations (e.g., `Levels/Level_Manager.gd`) if needed for context

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Godot Engine Core"
        Engine["Godot Engine Core"]:::engine
    end

    subgraph "Systems/Services"
        GS["GlobalState"]:::systems
        TDM["TowerDataManager"]:::systems
        LM["LevelManager"]:::systems
        TM["TurnManager"]:::systems
        AM["AudioManager"]:::systems
    end

    subgraph "Resources"
        Enums["Enums"]:::resources
        TDRes["TowerData Resources"]:::resources
        WaveRes["Wave Resources"]:::resources
    end

    subgraph "Entities & Components"
        subgraph Entities
            TWR["Towers"]:::entities
            ENM["Enemies"]:::entities
            BLT["Bullets"]:::entities
            SC["SacredCrystal"]:::entities
        end
        subgraph Components
            HC["Health_Component"]:::entities
            WR["Weapon"]:::entities
            AR["AttackRangeComponent"]:::entities
            HB["HitBoxArea2D"]:::entities
            UB["HurtBoxArea2D"]:::entities
        end
    end

    subgraph "UI"
        MM["MainMenu"]:::ui
        TS["TowerSelecterUI"]:::ui
        UIHUD["HUD Panels"]:::ui
        Controls["UI Controls"]:::ui
        Popups["Popups"]:::ui
    end

    subgraph "Assets & Editor"
        AssetsAudio["Audio Assets"]:::assets
        AssetsSprites["Sprites/Tilesets/Fonts"]:::assets
        Addons["Editor Add-ons"]:::assets
    end

    Engine -->|runs| GS
    Engine -->|runs| LM
    Engine -->|runs| TM
    Engine -->|runs| AM
    Engine -->|renders| Entities
    Engine -->|renders| UI
    Engine -->|loads| Resources

    MM -->|"start game"| LM
    TS -->|"place tower"| TWR
    LM -->|"setup level"| SC
    LM -->|"load waves"| WaveRes
    LM -->|"init turn"| TM
    TM -->|"spawn towers"| TWR
    TM -->|"spawn enemies"| ENM
    TM -->|"spawn bullets"| BLT

    TWR -->|uses| HC
    TWR -->|uses| WR
    TWR -->|uses| AR
    ENM -->|uses| HB
    ENM -->|uses| UB

    Entities -.->|signals| AM
    Entities -.->|signals| UIHUD

    TDM -->|provides data| TWR
    Enums -->|used by| Systems
    Enums -->|used by| Entities
    AssetsAudio -->|used by| AM
    AssetsSprites -->|used by| Engine

    classDef engine fill:#E0E0E0,stroke:#333,stroke-width:1px
    classDef systems fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef entities fill:#90EE90,stroke:#333,stroke-width:1px
    classDef ui fill:#FFA500,stroke:#333,stroke-width:1px
    classDef resources fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef assets fill:#D3D3D3,stroke:#333,stroke-width:1px

    click GS "https://github.com/blackbarman/zach-tower/blob/main/PuzzleTowerDefense/Globals/GlobalState.gd"
    click TDM "https://github.com/blackbarman/zach-tower/blob/main/PuzzleTowerDefense/Globals/tower_data_manager.gd"
    click Enums "https://github.com/blackbarman/zach-tower/blob/main/PuzzleTowerDefense/Globals/Enums.gd"
    click Popups "https://github.com/blackbarman/zach-tower/blob/main/PuzzleTowerDefense/Globals/Popups.tscn"
    click Popups "https://github.com/blackbarman/zach-tower/blob/main/PuzzleTowerDefense/Globals/Popups.gd"
    click LM "https://github.com/blackbarman/zach-tower/blob/main/PuzzleTowerDefense/Levels/Level_Manager.tscn"
    click LM "https://github.com/blackbarman/zach-tower/blob/main/PuzzleTowerDefense/Levels/Level_Manager.gd"
    click TM "https://github.com/blackbarman/zach-tower/blob/main/PuzzleTowerDefense/Systems/TurnManager.tscn"
    click TM "https://github.com/blackbarman/zach-tower/blob/main/PuzzleTowerDefense/Systems/TurnManager.gd"
    click AM "https://github.com/blackbarman/zach-tower/blob/main/PuzzleTowerDefense/Systems/AudioManager.tscn"
    click AM "https://github.com/blackbarman/zach-tower/blob/main/PuzzleTowerDefense/Systems/AudioManager.gd"
    click TWR "https://github.com/blackbarman/zach-tower/blob/main/PuzzleTowerDefense/Entities/Towers/tower.tscn"
    click TWR "https://github.com/blackbarman/zach-tower/blob/main/PuzzleTowerDefense/Entities/Towers/Tower.gd"
    click ENM "https://github.com/blackbarman/zach-tower/blob/main/PuzzleTowerDefense/Entities/Enemies/enemy.tscn"
    click ENM "https://github.com/blackbarman/zach-tower/blob/main/PuzzleTowerDefense/Entities/Enemies/enemy.gd"
    click BLT "https://github.com/blackbarman/zach-tower/blob/main/PuzzleTowerDefense/Entities/Bullets/bullet.tscn"
    click BLT "https://github.com/blackbarman/zach-tower/blob/main/PuzzleTowerDefense/Entities/Bullets/Bullet.gd"
    click SC "https://github.com/blackbarman/zach-tower/blob/main/PuzzleTowerDefense/Entities/SacredCrystal.tscn"
    click SC "https://github.com/blackbarman/zach-tower/blob/main/PuzzleTowerDefense/Entities/SacredCrystal.gd"
    click HC "https://github.com/blackbarman/zach-tower/blob/main/PuzzleTowerDefense/Custom_Components/Health_Component.tscn"
    click HC "https://github.com/blackbarman/zach-tower/blob/main/PuzzleTowerDefense/Custom_Components/Health_Component.gd"
    click WR "https://github.com/blackbarman/zach-tower/blob/main/PuzzleTowerDefense/Custom_Components/Weapon.tscn"
    click WR "https://github.com/blackbarman/zach-tower/blob/main/PuzzleTowerDefense/Custom_Components/Weapon.gd"
    click AR "https://github.com/blackbarman/zach-tower/blob/main/PuzzleTowerDefense/Custom_Components/AttackRangeComponent.tscn"
    click AR "https://github.com/blackbarman/zach-tower/blob/main/PuzzleTowerDefense/Custom_Components/AttackRangeComponent.gd"
    click HB "https://github.com/blackbarman/zach-tower/blob/main/PuzzleTowerDefense/Custom_Components/HitBoxArea2D.tscn"
    click HB "https://github.com/blackbarman/zach-tower/blob/main/PuzzleTowerDefense/Custom_Components/HitBoxArea2D.gd"
    click UB "https://github.com/blackbarman/zach-tower/blob/main/PuzzleTowerDefense/Custom_Components/HurtBoxArea2D.tscn"
    click UB "https://github.com/blackbarman/zach-tower/blob/main/PuzzleTowerDefense/Custom_Components/HurtBoxArea2D.gd"
    click TDRes "https://github.com/blackbarman/zach-tower/blob/main/PuzzleTowerDefense/Custom_Resources/TowerData.gd"
    click WaveRes "https://github.com/blackbarman/zach-tower/blob/main/PuzzleTowerDefense/Custom_Resources/WaveResourceBase.tres"
    click MM "https://github.com/blackbarman/zach-tower/blob/main/PuzzleTowerDefense/Levels/Screens/MainMenu.tscn"
    click MM "https://github.com/blackbarman/zach-tower/blob/main/PuzzleTowerDefense/Levels/Screens/MainMenu.gd"
    click TS "https://github.com/blackbarman/zach-tower/blob/main/PuzzleTowerDefense/UI/TowerSelecterUI.tscn"
    click TS "https://github.com/blackbarman/zach-tower/blob/main/PuzzleTowerDefense/UI/TowerSelecter.gd"
    click UIHUD "https://github.com/blackbarman/zach-tower/blob/main/PuzzleTowerDefense/UI/WaveInfo.tscn"
    click UIHUD "https://github.com/blackbarman/zach-tower/blob/main/PuzzleTowerDefense/UI/WaveInfo.gd"
    click Controls "https://github.com/blackbarman/zach-tower/blob/main/PuzzleTowerDefense/UI/fast_forward_button.tscn"
    click Controls "https://github.com/blackbarman/zach-tower/blob/main/PuzzleTowerDefense/UI/fast_forward_button.gd"
    click AssetsAudio "https://github.com/blackbarman/zach-tower/tree/main/PuzzleTowerDefense/Assets/Audio/"
    click AssetsSprites "https://github.com/blackbarman/zach-tower/tree/main/PuzzleTowerDefense/Assets/Enemies"
    click AssetsSprites "https://github.com/blackbarman/zach-tower/tree/main/PuzzleTowerDefense/Assets/Towers"
    click AssetsSprites "https://github.com/blackbarman/zach-tower/tree/main/PuzzleTowerDefense/Assets/Tiles"
    click AssetsSprites "https://github.com/blackbarman/zach-tower/tree/main/PuzzleTowerDefense/Assets/UI_assets"
    click Addons "https://github.com/blackbarman/zach-tower/tree/main/PuzzleTowerDefense/addons/Asset_Drawer"
    click Addons "https://github.com/blackbarman/zach-tower/tree/main/PuzzleTowerDefense/addons/SignalVisualizer"
    click Addons "https://github.com/blackbarman/zach-tower/tree/main/PuzzleTowerDefense/addons/Todo_Manager"
```
