# priyanshu792/idle-viewport-game architecture

> Architecture diagram of the GitHub repository priyanshu792/idle-viewport-game, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/priyanshu792/idle-viewport-game
- Repository: https://github.com/priyanshu792/idle-viewport-game

## Overview

#### Purpose and runtime
This is a Godot idle/viewport combat game. Godot project metadata and the configured startup scene are in `project.godot`; gameplay is assembled from `.tscn` scenes and GDScript, with resource-based unit, weapon, and upgrade definitions. No server or web runtime is evident.

#### Entry and scene composition
The application begins through Godot’s project entry configuration, then transitions between menu, gameplay, settings, and UI scene roots. The main gameplay composition appears centered on `scene/main.tscn`, driven by `script/main.gd`; menu flow uses `scene/main_menu.tscn` and `script/main_menu.gd`. The player, enemy, spawner, and shared UI are separately instanced scenes: `scene/player.tscn`, `scene/enemy.tscn`, `scene/spawner.tscn`.

#### Global coordination
Autoload-style global managers provide cross-scene control boundaries: event dispatch in `globals/game_events.gd`, level/progression coordination in `globals/level_manager.gd`, and window/UI visibility management in `globals/windows_manager.gd`. Gameplay systems should communicate through these globals or scene signals rather than tightly coupling projectile, UI, and level nodes.

#### Combat loop
The player and enemy actors drive the core loop: spawning enemies, targeting/firing weapons, applying damage, resolving health, and producing rewards/effects. Key implementations are `script/player.gd`, `script/enemy.gd`, `script/spawner.gd`, with reusable combat primitives in `script/damage.gd`, `script/damage_calculator.gd`, and `script/health.gd`. Enemies can drop collectible currency via `scene/dropped_orb.tscn` and `script/dropped_orb.gd`.

#### Weapon and projectile families
Weapons are implemented as independently instanced projectile scenes, allowing unlocks and upgrades to alter distinct behaviors. Families include base projectile (`projectiles/projectile1/projectile.tscn`), laser (`projectiles/Laser/laser_projectile.tscn`), multi-hit, orbital, spread-fire, and nuclear blast variants. Their scripts encapsulate movement/hit behavior, while visual effects use Godot shaders such as `assets/shaders/laser_projectile.gdshader`.

#### Data-driven stats and progression
Baseline actor and weapon values are Godot resources: `resources/Base_Player_stats.tres`, `resources/Base_Enemy_stats.tres`, and `resources/Base_Weapon_stats.tres`, backed by stat/resource scripts including `resources/weapons_stat.gd`. Individual upgrades are serialized `.tres` definitions under `resources/upgrades/`, including unlock, damage, speed, interval, radius, and target-count changes. This separates balancing data from runtime combat code.

#### Upgrade-tree and UI boundary
Upgrade selection is a dedicated scene subsystem: `upgrades/upgrade_tree.tscn`, `upgrades/upgrade_tree.gd`, and `upgrades/upgrade_tree_node.gd`. It consumes upgrade resource definitions and presents them through gameplay UI logic in `script/upgrade_ui.gd` and `scene/ui.tscn` / `script/ui.gd`. Settings are similarly isolated in `scene/settings.tscn` and `script/settings.gd`.

#### Tooling and external integrations
A custom editor CSV importer exists in `addons/csv_importer/csv_importer.gd`, with source spreadsheet/CSV content under `csv_s/`; it likely supports authoring/import of tabular upgrade or game data. The repository also vendors the Godot Git editor plugin under `addons/godot-git-plugin/`. These are editor integrations, not gameplay services.

Main entry points: [`project.godot`](https://github.com/priyanshu792/idle-viewport-game/blob/main/project.godot) (Project Entry), [`scene/main.tscn`](https://github.com/priyanshu792/idle-viewport-game/blob/main/scene/main.tscn) (Gameplay Root), [`scene/enemy.tscn`](https://github.com/priyanshu792/idle-viewport-game/blob/main/scene/enemy.tscn) (Enemy), [`scene/player.tscn`](https://github.com/priyanshu792/idle-viewport-game/blob/main/scene/player.tscn) (Player)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Godot Runtime"]
  node_project["Project Entry<br/>Godot project config<br/>[project.godot]"]
  node_main_menu["Main Menu<br/>scene + controller<br/>[main_menu.tscn]"]
  node_main["Gameplay Root<br/>scene + controller<br/>[main.tscn]"]
  node_settings["Settings<br/>scene + controller<br/>[settings.tscn]"]
  node_game_events{{"Game Events<br/>autoload event bus<br/>[game_events.gd]"}}
  node_level_manager{{"Level Manager<br/>autoload progression manager<br/>[level_manager.gd]"}}
  node_windows_manager{{"Windows Manager<br/>autoload UI manager<br/>[windows_manager.gd]"}}
end

subgraph group_combat["Combat Systems"]
  node_player["Player<br/>actor scene + script<br/>[player.tscn]"]
  node_spawner["Enemy Spawner<br/>scene + script<br/>[spawner.tscn]"]
  node_enemy["Enemy<br/>actor scene + script<br/>[enemy.tscn]"]
  node_combat_primitives["Damage &amp; Health<br/>combat primitives"]
  node_projectiles["Weapon Projectiles<br/>instanced projectile families<br/>[projectile.tscn]"]
  node_dropped_orb["Dropped Orb<br/>collectible scene + script<br/>[dropped_orb.tscn]"]
end

subgraph group_content["Game Data &amp; UI"]
  node_stats[("Base Stats<br/>Godot resources")]
  node_upgrades[("Upgrade Definitions<br/>serialized resources")]
  node_upgrade_tree["Upgrade Tree<br/>scene + controller<br/>[upgrade_tree.tscn]"]
  node_game_ui["Gameplay UI<br/>scene + controller<br/>[ui.tscn]"]
end

subgraph group_tooling["Editor Tooling"]
  node_csv_importer["CSV Importer<br/>Godot editor plugin<br/>[csv_importer.gd]"]
  node_godot_git["Godot Git Plugin<br/>Godot editor plugin"]
end

node_project -->|"starts"| node_main_menu
node_main_menu -->|"begins game"| node_main
node_project -->|"autoloads"| node_game_events
node_project -->|"autoloads"| node_level_manager
node_project -->|"autoloads"| node_windows_manager
node_main_menu -->|"opens"| node_settings
node_main -->|"instances"| node_player
node_main -->|"instances"| node_spawner
node_main -->|"instances"| node_game_ui
node_spawner -->|"spawns"| node_enemy
node_player -->|"fires"| node_projectiles
node_projectiles -->|"applies damage"| node_combat_primitives
node_enemy -->|"uses health"| node_combat_primitives
node_enemy -->|"drops on defeat"| node_dropped_orb
node_stats -.->|"configures"| node_player
node_stats -.->|"configures"| node_enemy
node_stats -.->|"configures"| node_projectiles
node_upgrades -->|"populates"| node_upgrade_tree
node_upgrade_tree -->|"presents through"| node_game_ui
node_upgrades -.->|"modifies unlocks and stats"| node_player
node_level_manager -->|"coordinates progression"| node_upgrade_tree
node_game_events -.->|"notifies"| node_game_ui
node_windows_manager -->|"controls visibility"| node_game_ui
node_csv_importer -.->|"imports authoring data"| node_upgrades

click node_project "https://github.com/priyanshu792/idle-viewport-game/blob/main/project.godot"
click node_main_menu "https://github.com/priyanshu792/idle-viewport-game/blob/main/scene/main_menu.tscn"
click node_main "https://github.com/priyanshu792/idle-viewport-game/blob/main/scene/main.tscn"
click node_settings "https://github.com/priyanshu792/idle-viewport-game/blob/main/scene/settings.tscn"
click node_game_events "https://github.com/priyanshu792/idle-viewport-game/blob/main/globals/game_events.gd"
click node_level_manager "https://github.com/priyanshu792/idle-viewport-game/blob/main/globals/level_manager.gd"
click node_windows_manager "https://github.com/priyanshu792/idle-viewport-game/blob/main/globals/windows_manager.gd"
click node_player "https://github.com/priyanshu792/idle-viewport-game/blob/main/scene/player.tscn"
click node_spawner "https://github.com/priyanshu792/idle-viewport-game/blob/main/scene/spawner.tscn"
click node_enemy "https://github.com/priyanshu792/idle-viewport-game/blob/main/scene/enemy.tscn"
click node_combat_primitives "https://github.com/priyanshu792/idle-viewport-game/blob/main/script/damage_calculator.gd"
click node_projectiles "https://github.com/priyanshu792/idle-viewport-game/blob/main/projectiles/projectile1/projectile.tscn"
click node_dropped_orb "https://github.com/priyanshu792/idle-viewport-game/blob/main/scene/dropped_orb.tscn"
click node_stats "https://github.com/priyanshu792/idle-viewport-game/blob/main/resources/Base_Player_stats.tres"
click node_upgrade_tree "https://github.com/priyanshu792/idle-viewport-game/blob/main/upgrades/upgrade_tree.tscn"
click node_game_ui "https://github.com/priyanshu792/idle-viewport-game/blob/main/scene/ui.tscn"
click node_csv_importer "https://github.com/priyanshu792/idle-viewport-game/blob/main/addons/csv_importer/csv_importer.gd"

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_main_menu,node_main,node_settings,node_game_events,node_level_manager,node_windows_manager toneBlue
class node_player,node_spawner,node_enemy,node_combat_primitives,node_projectiles,node_dropped_orb toneAmber
class node_stats,node_upgrades,node_upgrade_tree,node_game_ui toneMint
class node_csv_importer,node_godot_git toneRose
```

## Components

### Godot Runtime

- [Project Entry](https://github.com/priyanshu792/idle-viewport-game/blob/main/project.godot): Godot project config · Configures startup scene and autoloads. · `project.godot`
- [Main Menu](https://github.com/priyanshu792/idle-viewport-game/blob/main/scene/main_menu.tscn): scene + controller · `scene/main_menu.tscn`
- [Gameplay Root](https://github.com/priyanshu792/idle-viewport-game/blob/main/scene/main.tscn): scene + controller · Composes the active combat session. · `scene/main.tscn`
- [Settings](https://github.com/priyanshu792/idle-viewport-game/blob/main/scene/settings.tscn): scene + controller · `scene/settings.tscn`
- [Game Events](https://github.com/priyanshu792/idle-viewport-game/blob/main/globals/game_events.gd): autoload event bus · `globals/game_events.gd`
- [Level Manager](https://github.com/priyanshu792/idle-viewport-game/blob/main/globals/level_manager.gd): autoload progression manager · `globals/level_manager.gd`
- [Windows Manager](https://github.com/priyanshu792/idle-viewport-game/blob/main/globals/windows_manager.gd): autoload UI manager · `globals/windows_manager.gd`

### Combat Systems

- [Player](https://github.com/priyanshu792/idle-viewport-game/blob/main/scene/player.tscn): actor scene + script · `scene/player.tscn`
- [Enemy Spawner](https://github.com/priyanshu792/idle-viewport-game/blob/main/scene/spawner.tscn): scene + script · `scene/spawner.tscn`
- [Enemy](https://github.com/priyanshu792/idle-viewport-game/blob/main/scene/enemy.tscn): actor scene + script · `scene/enemy.tscn`
- [Damage & Health](https://github.com/priyanshu792/idle-viewport-game/blob/main/script/damage_calculator.gd): combat primitives · Calculates damage and resolves health changes. · `script/damage_calculator.gd`
- [Weapon Projectiles](https://github.com/priyanshu792/idle-viewport-game/blob/main/projectiles/projectile1/projectile.tscn): instanced projectile families · Independent weapon behaviors for firing, movement, and hits. · `projectiles/projectile1/projectile.tscn`
- [Dropped Orb](https://github.com/priyanshu792/idle-viewport-game/blob/main/scene/dropped_orb.tscn): collectible scene + script · `scene/dropped_orb.tscn`

### Game Data & UI

- [Base Stats](https://github.com/priyanshu792/idle-viewport-game/blob/main/resources/Base_Player_stats.tres): Godot resources · Baseline player, enemy, and weapon values. · `resources/Base_Player_stats.tres`
- **Upgrade Definitions**: serialized resources · Defines unlock and stat-modifier choices.
- [Upgrade Tree](https://github.com/priyanshu792/idle-viewport-game/blob/main/upgrades/upgrade_tree.tscn): scene + controller · `upgrades/upgrade_tree.tscn`
- [Gameplay UI](https://github.com/priyanshu792/idle-viewport-game/blob/main/scene/ui.tscn): scene + controller · `scene/ui.tscn`

### Editor Tooling

- [CSV Importer](https://github.com/priyanshu792/idle-viewport-game/blob/main/addons/csv_importer/csv_importer.gd): Godot editor plugin · Imports tabular authoring data. · `addons/csv_importer/csv_importer.gd`
- **Godot Git Plugin**: Godot editor plugin

## Connections

- Project Entry → Main Menu: starts
- Main Menu → Gameplay Root: begins game
- Project Entry → Game Events: autoloads
- Project Entry → Level Manager: autoloads
- Project Entry → Windows Manager: autoloads
- Main Menu → Settings: opens
- Gameplay Root → Player: instances
- Gameplay Root → Enemy Spawner: instances
- Gameplay Root → Gameplay UI: instances
- Enemy Spawner → Enemy: spawns
- Player → Weapon Projectiles: fires
- Weapon Projectiles → Damage & Health: applies damage
- Enemy → Damage & Health: uses health
- Enemy → Dropped Orb: drops on defeat
- Base Stats → Player: configures
- Base Stats → Enemy: configures
- Base Stats → Weapon Projectiles: configures
- Upgrade Definitions → Upgrade Tree: populates
- Upgrade Tree → Gameplay UI: presents through
- Upgrade Definitions → Player: modifies unlocks and stats
- Level Manager → Upgrade Tree: coordinates progression
- Game Events → Gameplay UI: notifies
- Windows Manager → Gameplay UI: controls visibility
- CSV Importer → Upgrade Definitions: imports authoring data