# quiver-dev/tower-defense-tutorial architecture

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

- Interactive diagram: https://gitdiagram.com/quiver-dev/tower-defense-tutorial
- Repository: https://github.com/quiver-dev/tower-defense-tutorial

## Overview

1. **Project type and runtime**
   - This is a **Godot 4** 2D tower-defense game, organized as a scene-driven project.
   - Core content is split between reusable **`.tscn` scenes** and behavior **`.gd` scripts**.
   - Art/audio assets live under `assets/`, and large binaries are managed with **Git LFS**.

2. **Overall game structure**
   - The game is built from a small set of major gameplay subsystems: **map**, **spawners**, **objective**, **towers**, **enemies**, **projectiles**, and **UI**.
   - These systems communicate mostly through Godot **signals**, node references, and shared state rather than a central game service layer.
   - The architecture is “scene composition first”: each major gameplay object is its own scene with its own script.

3. **Entry points and global state**
   - `project.godot` defines the project configuration and scene setup.
   - `autoloads/global.gd` is the main global singleton boundary, used for cross-scene data or persistent game-wide state.
   - UI screens such as **main menu**, **pause**, and **game over** are separate scenes, indicating scene switching is part of the control flow.

4. **Map and world layer**
   - `maps/map.tscn` and `maps/map.gd` appear to own the playable battlefield and coordinate the major world elements.
   - `maps/camera/camera2d.*` provides a **player-controlled camera**, separating camera behavior from gameplay entities.
   - The map likely anchors navigation/pathing and the placement grid/slots used by towers.

5. **Enemy subsystem**
   - Enemy behavior is centered on `entities/enemies/enemy.gd` plus concrete enemy scenes for **infantry**, **tanks**, and **helicopters**.
   - Enemies are organized with a **finite state machine** under `entities/enemies/states/`, including move, shoot, stationary-shoot, and die states.
   - Helicopters have their own specialized states (`helicopter_move_state.gd`, `helicopter_shoot_stationary_state.gd`), showing enemy-specific behavior extends the common FSM base.

6. **Tower subsystem**
   - Towers are separate scenes for **gatling**, **cannon**, and **missile** variants under `entities/towers/`.
   - `entities/towers/tower.gd` is the shared tower behavior layer, while `tower_slot.gd` suggests the map exposes explicit build points.
   - `tower_costs_json.tres` indicates tower economy data is stored as a resource, separating balance data from behavior.

7. **Combat and projectile flow**
   - Towers and some enemies use the shared shooter layer: `entities/shooter.gd` and `entities/shooter_alternating.gd`.
   - Projectiles are modeled as separate scenes/scripts under `entities/projectiles/`, with different implementations for **bullets**, **shells**, and **missiles**.
   - The main combat flow is: tower or enemy acquires target → shooter emits projectile → projectile collides → hit sound / damage / explosion VFX.

8. **Objectives, spawning, and progression**
   - `maps/objective/objective.*` represents the defended target or loss condition anchor.
   - `maps/spawner/spawner.*` handles enemy generation and likely the wave/progression cadence.
   - This creates the core loop: **spawn enemies → traverse map → attack towers/objective → player defends → economy and UI update**.

9. **Explosion and feedback effects**
   - `entities/explosion_vfx/explosion.tscn` is the visual feedback layer for kills and impacts.
   - The `assets/explosion_vfx/` folders separate default and objective-specific effects, implying feedback varies by event type.
   - Sound assets are also event-driven and closely tied to combat actions and impacts.

10. **UI layer**
   - The UI is split into dedicated screens and HUD components: `hud`, `entity_hud`, `tower_popup`, `pause`, `game_over`, and `main_menu`.
   - `ui/ui_theme.tres` shows the project uses Godot themes for consistent styling.
   - UI likely bridges player input and game state for tower selection, economy display, pause/menu navigation, and entity inspection.

11. **Input and player interaction boundaries**
   - The player interacts primarily through **tower placement**, **camera control**, and **menus/HUD** rather than direct character control.
   - `ui/tower_popup.*` and `entities/towers/tower_slot.*` suggest the build flow is: select slot → choose tower → instantiate tower scene.
   - This cleanly separates strategic placement UI from world simulation.

12. **Asset organization**
   - Art is grouped by gameplay domain: enemies, towers, projectiles, objective, tiles, explosions, and UI.
   - Audio is similarly domain-based, with distinct files for weapon fire, hits, explosions, and unit movement.
   - This mirrors the runtime structure, making the asset tree a good proxy for the in-game component architecture.

13. **Technical patterns used in the codebase**
   - The README confirms the project emphasizes **FSM AI**, **signals**, **inheritance**, **navigation**, **CharacterBody2D**, and **TileMap**.
   - That means the main architectural boundaries are not services or managers, but reusable scene hierarchies plus state objects.
   - Navigation/pathfinding and collision are key engine-level dependencies that shape enemy movement and combat behavior.

14. **How the main gameplay systems connect**
   - The central dependency chain is: **map/world** provides navigation and build slots, **spawner** introduces enemies, **towers** and **enemies** create projectiles via shooter logic, **projectiles** resolve hits, and **UI/global state** reflect economy and game status.
   - For an architecture diagram, the most important boundaries are: **world simulation**, **combat actors**, **projectile/VFX feedback**, and **presentation/UI**.

Main entry points: [`maps/map.tscn`](https://github.com/quiver-dev/tower-defense-tutorial/blob/main/maps/map.tscn) (Map), [`entities/enemies/enemy.gd`](https://github.com/quiver-dev/tower-defense-tutorial/blob/main/entities/enemies/enemy.gd) (Enemy Base), [`entities/enemies/infantry/infantry_t1.tscn`](https://github.com/quiver-dev/tower-defense-tutorial/blob/main/entities/enemies/infantry/infantry_t1.tscn) (Enemy Variants), [`entities/shooter.gd`](https://github.com/quiver-dev/tower-defense-tutorial/blob/main/entities/shooter.gd) (Shooter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core gameplay"]
  node_project["Project<br/>godot config<br/>[project.godot]"]
  node_global["Global<br/>autoload singleton<br/>[global.gd]"]
  node_map["Map<br/>world scene<br/>[map.tscn]"]
  node_camera["Camera<br/>[camera2d.tscn]"]
  node_objective["Objective<br/>world anchor<br/>[objective.tscn]"]
  node_spawner["Spawner<br/>wave generator<br/>[spawner.tscn]"]
  node_tower_slot["Tower Slot<br/>build point<br/>[tower_slot.tscn]"]
  node_tower_base["Tower Base<br/>tower logic<br/>[tower.gd]"]
  node_tower_variants["Tower Variants<br/>tower scenes<br/>[gatling_tower.tscn]"]
  node_enemy_base["Enemy Base<br/>enemy logic<br/>[enemy.gd]"]
  node_enemy_fsm["Enemy FSM<br/>state machine<br/>[move_state.gd]"]
  node_enemy_variants["Enemy Variants<br/>enemy scenes<br/>[infantry_t1.tscn]"]
  node_projectile_base["Projectile Base<br/>projectile logic<br/>[projectile.gd]"]
  node_projectile_variants["Projectile Variants<br/>projectile scenes<br/>[missile.tscn]"]
  node_shooter["Shooter<br/>fire control<br/>[shooter.gd]"]
  node_combat_vfx["Combat VFX<br/>impact effects<br/>[explosion.tscn]"]
end

subgraph group_presentation["Presentation"]
  node_hud["HUD<br/>in-game ui<br/>[hud.tscn]"]
  node_screens["Screens<br/>menus<br/>[main_menu.tscn]"]
  node_theme["Theme<br/>ui styling<br/>[ui_theme.tres]"]
end

subgraph group_assets["Assets"]
  node_enemy_art["Enemy Art<br/>art assets"]
  node_tower_art["Tower Art<br/>art assets"]
  node_projectile_art["Projectile Art<br/>art assets"]
  node_sound_bank["Sound Bank<br/>audio assets"]
end

node_project -->|"starts"| node_map
node_global -.->|"shared state"| node_map
node_map -->|"hosts"| node_camera
node_map -->|"contains"| node_objective
node_map -->|"contains"| node_spawner
node_map -->|"exposes"| node_tower_slot
node_tower_slot -->|"instantiates"| node_tower_variants
node_tower_variants -->|"inherits"| node_tower_base
node_tower_base -->|"fires via"| node_shooter
node_shooter -->|"spawns"| node_projectile_variants
node_projectile_variants -->|"inherits"| node_projectile_base
node_enemy_variants -->|"inherits"| node_enemy_base
node_enemy_base -->|"drives"| node_enemy_fsm
node_enemy_variants -.->|"may use"| node_shooter
node_spawner -->|"spawns"| node_enemy_variants
node_enemy_base -->|"attacks"| node_objective
node_tower_base -->|"targets"| node_enemy_base
node_projectile_base -->|"on hit"| node_combat_vfx
node_projectile_base -.->|"plays"| node_sound_bank
node_combat_vfx -.->|"pairs with"| node_sound_bank
node_hud -.->|"reads state"| node_global
node_screens -.->|"controls flow"| node_global
node_screens -.->|"switches to"| node_map
node_hud -.->|"styled by"| node_theme
node_screens -.->|"styled by"| node_theme
node_tower_art -.->|"supports"| node_tower_variants
node_enemy_art -.->|"supports"| node_enemy_variants
node_projectile_art -.->|"supports"| node_projectile_variants
node_sound_bank -.->|"supports"| node_shooter

click node_project "https://github.com/quiver-dev/tower-defense-tutorial/blob/main/project.godot"
click node_global "https://github.com/quiver-dev/tower-defense-tutorial/blob/main/autoloads/global.gd"
click node_map "https://github.com/quiver-dev/tower-defense-tutorial/blob/main/maps/map.tscn"
click node_camera "https://github.com/quiver-dev/tower-defense-tutorial/blob/main/maps/camera/camera2d.tscn"
click node_objective "https://github.com/quiver-dev/tower-defense-tutorial/blob/main/maps/objective/objective.tscn"
click node_spawner "https://github.com/quiver-dev/tower-defense-tutorial/blob/main/maps/spawner/spawner.tscn"
click node_tower_slot "https://github.com/quiver-dev/tower-defense-tutorial/blob/main/entities/towers/tower_slot.tscn"
click node_tower_base "https://github.com/quiver-dev/tower-defense-tutorial/blob/main/entities/towers/tower.gd"
click node_tower_variants "https://github.com/quiver-dev/tower-defense-tutorial/blob/main/entities/towers/gatling_tower.tscn"
click node_enemy_base "https://github.com/quiver-dev/tower-defense-tutorial/blob/main/entities/enemies/enemy.gd"
click node_enemy_fsm "https://github.com/quiver-dev/tower-defense-tutorial/blob/main/entities/enemies/states/move_state.gd"
click node_enemy_variants "https://github.com/quiver-dev/tower-defense-tutorial/blob/main/entities/enemies/infantry/infantry_t1.tscn"
click node_projectile_base "https://github.com/quiver-dev/tower-defense-tutorial/blob/main/entities/projectiles/projectile.gd"
click node_projectile_variants "https://github.com/quiver-dev/tower-defense-tutorial/blob/main/entities/projectiles/missile/missile.tscn"
click node_shooter "https://github.com/quiver-dev/tower-defense-tutorial/blob/main/entities/shooter.gd"
click node_combat_vfx "https://github.com/quiver-dev/tower-defense-tutorial/blob/main/entities/explosion_vfx/explosion.tscn"
click node_hud "https://github.com/quiver-dev/tower-defense-tutorial/blob/main/ui/hud.tscn"
click node_screens "https://github.com/quiver-dev/tower-defense-tutorial/blob/main/ui/main_menu.tscn"
click node_theme "https://github.com/quiver-dev/tower-defense-tutorial/blob/main/ui/ui_theme.tres"
click node_enemy_art "https://github.com/quiver-dev/tower-defense-tutorial/tree/main/assets/enemies"
click node_tower_art "https://github.com/quiver-dev/tower-defense-tutorial/tree/main/assets/towers"
click node_projectile_art "https://github.com/quiver-dev/tower-defense-tutorial/tree/main/assets/projectiles"
click node_sound_bank "https://github.com/quiver-dev/tower-defense-tutorial/tree/main/assets/sounds"

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_project,node_global,node_map,node_camera,node_objective,node_spawner,node_tower_slot,node_tower_base,node_tower_variants,node_enemy_base,node_enemy_fsm,node_enemy_variants,node_projectile_base,node_projectile_variants,node_shooter,node_combat_vfx toneBlue
class node_hud,node_screens,node_theme toneAmber
class node_enemy_art,node_tower_art,node_projectile_art,node_sound_bank toneMint
```

## Components

### Core gameplay

Scene-driven simulation for map, actors, combat, and progression.

- [Project](https://github.com/quiver-dev/tower-defense-tutorial/blob/main/project.godot): godot config · Project settings and startup scene setup. · `project.godot`
- [Global](https://github.com/quiver-dev/tower-defense-tutorial/blob/main/autoloads/global.gd): autoload singleton · Cross-scene persistent game state and shared data. · `autoloads/global.gd`
- [Map](https://github.com/quiver-dev/tower-defense-tutorial/blob/main/maps/map.tscn): world scene · Playable battlefield that hosts navigation, build slots, and world actors. · `maps/map.tscn`
- [Camera](https://github.com/quiver-dev/tower-defense-tutorial/blob/main/maps/camera/camera2d.tscn): camera scene · Player-controlled 2D camera for world viewing. · `maps/camera/camera2d.tscn`
- [Objective](https://github.com/quiver-dev/tower-defense-tutorial/blob/main/maps/objective/objective.tscn): world anchor · Defended target and loss-condition anchor. · `maps/objective/objective.tscn`
- [Spawner](https://github.com/quiver-dev/tower-defense-tutorial/blob/main/maps/spawner/spawner.tscn): wave generator · Creates enemy waves and drives progression cadence. · `maps/spawner/spawner.tscn`
- [Tower Slot](https://github.com/quiver-dev/tower-defense-tutorial/blob/main/entities/towers/tower_slot.tscn): build point · Explicit placement node used to construct towers. · `entities/towers/tower_slot.tscn`
- [Tower Base](https://github.com/quiver-dev/tower-defense-tutorial/blob/main/entities/towers/tower.gd): tower logic · Shared tower behavior layer for targeting and firing. · `entities/towers/tower.gd`
- [Tower Variants](https://github.com/quiver-dev/tower-defense-tutorial/blob/main/entities/towers/gatling_tower.tscn): tower scenes · Concrete gatling, cannon, and missile tower scenes. · `entities/towers/gatling_tower.tscn`
- [Enemy Base](https://github.com/quiver-dev/tower-defense-tutorial/blob/main/entities/enemies/enemy.gd): enemy logic · Shared enemy behavior and common movement/combat setup. · `entities/enemies/enemy.gd`
- [Enemy FSM](https://github.com/quiver-dev/tower-defense-tutorial/blob/main/entities/enemies/states/move_state.gd): state machine · Reusable enemy state layer for move, shoot, and die behavior. · `entities/enemies/states/move_state.gd`
- [Enemy Variants](https://github.com/quiver-dev/tower-defense-tutorial/blob/main/entities/enemies/infantry/infantry_t1.tscn): enemy scenes · Concrete infantry, tank, and helicopter enemy scenes. · `entities/enemies/infantry/infantry_t1.tscn`
- [Projectile Base](https://github.com/quiver-dev/tower-defense-tutorial/blob/main/entities/projectiles/projectile.gd): projectile logic · Shared projectile movement, collision, and impact handling. · `entities/projectiles/projectile.gd`
- [Projectile Variants](https://github.com/quiver-dev/tower-defense-tutorial/blob/main/entities/projectiles/missile/missile.tscn): projectile scenes · Bullet, shell, and missile projectile implementations. · `entities/projectiles/missile/missile.tscn`
- [Shooter](https://github.com/quiver-dev/tower-defense-tutorial/blob/main/entities/shooter.gd): fire control · Shared firing layer used by towers and some enemies. · `entities/shooter.gd`
- [Combat VFX](https://github.com/quiver-dev/tower-defense-tutorial/blob/main/entities/explosion_vfx/explosion.tscn): impact effects · Explosion feedback for hits, kills, and objective damage. · `entities/explosion_vfx/explosion.tscn`

### Presentation

UI screens and styling for menus, HUD, and overlays.

- [HUD](https://github.com/quiver-dev/tower-defense-tutorial/blob/main/ui/hud.tscn): in-game ui · Gameplay overlay for economy, status, and entity info. · `ui/hud.tscn`
- [Screens](https://github.com/quiver-dev/tower-defense-tutorial/blob/main/ui/main_menu.tscn): menus · Main menu, pause, game over, and popup flow. · `ui/main_menu.tscn`
- [Theme](https://github.com/quiver-dev/tower-defense-tutorial/blob/main/ui/ui_theme.tres): ui styling · Shared visual theme for UI consistency. · `ui/ui_theme.tres`

### Assets

Domain-organized art and audio referenced by gameplay scenes.

- [Enemy Art](https://github.com/quiver-dev/tower-defense-tutorial/tree/main/assets/enemies): art assets · Enemy sprites and related visual content. · `assets/enemies`
- [Tower Art](https://github.com/quiver-dev/tower-defense-tutorial/tree/main/assets/towers): art assets · Tower sprites and build visuals. · `assets/towers`
- [Projectile Art](https://github.com/quiver-dev/tower-defense-tutorial/tree/main/assets/projectiles): art assets · Bullet, shell, and missile art assets. · `assets/projectiles`
- [Sound Bank](https://github.com/quiver-dev/tower-defense-tutorial/tree/main/assets/sounds): audio assets · Weapon fire, hits, explosions, and unit sounds. · `assets/sounds`

## Connections

- Project → Map: starts · Project launches into the main playable scene.
- Global → Map: shared state · Persistent state is available to the world scene.
- Map → Camera: hosts · The battlefield includes the player camera.
- Map → Objective: contains · The battlefield anchors the defended target.
- Map → Spawner: contains · The battlefield owns enemy generation.
- Map → Tower Slot: exposes · Build points are provided by the map.
- Tower Slot → Tower Variants: instantiates · Slots create concrete tower scenes on placement.
- Tower Variants → Tower Base: inherits · Tower scenes share the common tower behavior layer.
- Tower Base → Shooter: fires via · Towers use shared shooter logic to emit projectiles.
- Shooter → Projectile Variants: spawns · Fire control creates projectile scenes.
- Projectile Variants → Projectile Base: inherits · Projectile scenes share common movement and impact logic.
- Enemy Variants → Enemy Base: inherits · Enemy scenes build on the shared enemy script.
- Enemy Base → Enemy FSM: drives · Enemy behavior is organized through state objects.
- Enemy Variants → Shooter: may use · Some enemies reuse the shooter layer for attacks.
- Spawner → Enemy Variants: spawns · Wave generation creates concrete enemies.
- Enemy Base → Objective: attacks · Enemies target the defended objective.
- Tower Base → Enemy Base: targets · Towers acquire enemies as targets.
- Projectile Base → Combat VFX: on hit · Impacts trigger explosion feedback.
- Projectile Base → Sound Bank: plays · Projectile impacts and firing use event sounds.
- Combat VFX → Sound Bank: pairs with · Visual impacts are coupled to audio feedback.
- HUD → Global: reads state · HUD reflects shared game progress and resources.
- Screens → Global: controls flow · Menus and overlays interact with persistent state.
- Screens → Map: switches to · Scene screens transition into gameplay.
- HUD → Theme: styled by · HUD uses the shared UI theme.
- Screens → Theme: styled by · Menu and overlay scenes use the shared UI theme.
- Tower Art → Tower Variants: supports · Tower scenes are backed by domain art.
- Enemy Art → Enemy Variants: supports · Enemy scenes are backed by domain art.
- Projectile Art → Projectile Variants: supports · Projectile scenes are backed by domain art.
- Sound Bank → Shooter: supports · Weapon audio is tied to firing behavior.
