# skillissuedd/alphabattleters architecture

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

- Interactive diagram: https://gitdiagram.com/skillissuedd/alphabattleters
- Repository: https://github.com/skillissuedd/alphabattleters

## Overview

#### Purpose and Runtime
This is a packaged Godot game project (`ALPHABATTLETTERS.console.exe`, `ALPHABATTLETTERS.pck`) centered on letter-tile/deck placement, board combat, enemies, and run progression. It runs locally through the Godot engine using GDScript, `.tscn` scene graphs, `.tres` resources, shaders, imported media, and desktop export settings (`project.godot`, `export_presets.cfg`). No backend, network service, or cloud dependency is evident.

#### Application Entry and Scene Flow
The configured Godot entry scene is defined in `project.godot` (its contents are not supplied). The visible scene hierarchy supports a menu-to-run lifecycle:
- Menu, language, options, tutorial, loading, and game-over views: `Entities/Scenes/general/mainMenu/mainMenu.tscn`, `Entities/Scenes/general/loadingScreen/loadingScreen.tscn`, `Entities/Scenes/general/gameover/gameover.tscn`.
- Gameplay is hosted by the run scene: `Entities/Scenes/Rooms/runScene/runScene.tscn`, controlled by `Entities/Scenes/Rooms/runScene/runScene.gd`.
- Scene transitions are centralized rather than implemented solely by individual screens: `Entities/managers/SceneManager/SceneManager.gd`.

#### Global State and Cross-Cutting Services
Godot global/autoload-style scripts appear to hold shared runtime state and event coordination:
- Core globals/signals: `Entities/Globals/Global.gd`, `Entities/Globals/global_signals.gd`.
- Player/meta state and options: `Entities/Globals/GlobalStats.gd`, `Entities/Globals/GlobalOptions.gd`.
- Audio and upgrade catalog services: `Entities/Globals/GlobalAudio.gd`, `Entities/Globals/UpgradeDatabase.gd`.
These form an important boundary: scenes and gameplay objects should coordinate through managers/globals and signals rather than directly owning persistent profile, settings, or shared audio state.

#### Run, Board, Hand, and Deck Loop
A run manager likely owns progression and encounter-level state, while board, hand, and deck managers own the tactical turn state:
- Run orchestration: `Entities/managers/RunManager/run_manager.gd`.
- Board placement/occupancy: `Entities/managers/Board/board_manager.gd`, `Entities/managers/Board/boardManager.tscn`.
- Draw/hand interactions: `Entities/managers/Hand/hand_manager.gd`, `Entities/managers/Hand/hand_wheel.gd`.
- Deck construction/draw source and randomness: `Entities/managers/Decks/deck.gd`, `Entities/managers/RNG/RNG.gd`.
The primary flow is inferred as deck/RNG → hand → player placement on board → combat resolution → run outcome/reward/progression.

#### Letter Entities and Interaction Components
Letters are composable scene entities rather than plain data records:
- Base letter and display logic: `Entities/Letters/LetterBase/letter_base.tscn`, `Entities/Letters/LetterBase/letter_base.gd`, `Entities/Letters/LetterBase/letter_label.gd`.
- Letter state/stat representation: `Entities/Letters/LetterStats/letter_stats.gd`, `Entities/Letters/Components/Properties/propertiesData.gd`.
- Player manipulation is separated into drag, rotation, scaling, status, and visual-shadow components: `Entities/Letters/Components/Drag/drag_component.gd`, `Entities/Letters/Components/Rotation/rotation_component.gd`, `Entities/Letters/Components/Status/status_component.gd`.
This component boundary isolates input/presentation behavior from letter identity and combat-relevant properties.

#### Combat Resolution and Entities
Combat has a distinct simulation-versus-presentation split:
- Rules/state calculation: `Entities/managers/BattleManagers/Simulator/battle_SIMULATOR.gd`.
- Animation/visual sequencing: `Entities/managers/BattleManagers/Animator/battle_ANIMATOR.gd`.
- Shared entity base and enemy definitions: `Entities/EntityBase/entity_base.gd`, `Entities/Enemies/Database/enemy_info.gd`.
Health-bar scenes provide the display boundary for entity health: `Entities/healthBars/health_bar.gd`, `Entities/healthBars/EnemyHealthBar/enemy_health_bar.gd`.

#### Upgrades, UI, and Persistence
Upgrade slots encode tiered tactical modifiers, while popups/UI expose selection and information:
- General upgrades: `Entities/GeneralUpgrades/General_upgrade.gd`, `Entities/Globals/Letter_upgrading.gd`.
- Tiered/special slot implementations: `Entities/Slots/Upgrade/slot_upgrade.gd`, `Entities/Slots/Upgrade/Tier1/Dart/slot_upgrade_dart.gd`, `Entities/Slots/Upgrade/Tier3/Rebirth/slot_upgrade_rebirth.gd`.
- Upgrade/deck/action dialogs: `Entities/UIPopups/UpgradePanel/UpgradePanel.gd`, `Entities/UIPopups/DeckSelector/deck_selector.gd`, `Entities/UIPopups/ActionForm/action_form.gd`.
- Local persistence is handled by `Entities/managers/saveload/SaveManager.gd` with profile/settings resource models under `Entities/managers/saveload/ProfileStats/` and `Entities/managers/saveload/Settings/`.

Main entry points: [`Entities/managers/SceneManager/SceneManager.gd`](https://github.com/skillissuedd/alphabattleters/blob/main/Entities/managers/SceneManager/SceneManager.gd) (Scene Manager), [`Entities/managers/RunManager/run_manager.gd`](https://github.com/skillissuedd/alphabattleters/blob/main/Entities/managers/RunManager/run_manager.gd) (Run Manager), [`Entities/managers/BattleManagers/Simulator/battle_SIMULATOR.gd`](https://github.com/skillissuedd/alphabattleters/blob/main/Entities/managers/BattleManagers/Simulator/battle_SIMULATOR.gd) (Battle Simulator), [`Entities/Globals/Global.gd`](https://github.com/skillissuedd/alphabattleters/blob/main/Entities/Globals/Global.gd) (Global State & Signals)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Godot Runtime"]
  node_entry["Project Entry<br/>Godot project config<br/>[project.godot]"]
  node_scene_manager{{"Scene Manager<br/>scene transition manager<br/>[SceneManager.gd]"}}
  node_screens["Menu &amp; Outcome Screens<br/>Godot scenes<br/>[mainMenu.tscn]"]
end

subgraph group_globals["Global Services"]
  node_global_state{{"Global State &amp; Signals<br/>autoload services<br/>[Global.gd]"}}
  node_profile_options["Profile &amp; Options<br/>autoload state<br/>[GlobalStats.gd]"]
  node_audio_upgrades["Audio &amp; Upgrade Catalog<br/>autoload services<br/>[GlobalAudio.gd]"]
end

subgraph group_run["Run Gameplay"]
  node_run_scene["Run Scene<br/>Godot scene controller<br/>[runScene.gd]"]
  node_run_manager{{"Run Manager<br/>run orchestrator<br/>[run_manager.gd]"}}
  node_deck_rng["Deck &amp; RNG<br/>draw source<br/>[deck.gd]"]
  node_hand["Hand Manager<br/>hand interaction<br/>[hand_manager.gd]"]
  node_board["Board Manager<br/>placement state<br/>[board_manager.gd]"]
  node_letter["Letter Entity<br/>composable scene entity<br/>[letter_base.tscn]"]
  node_letter_components["Letter Interaction Components<br/>input and visual components<br/>[drag_component.gd]"]
end

subgraph group_combat["Combat"]
  node_simulator{{"Battle Simulator<br/>combat rules engine"}}
  node_animator["Battle Animator<br/>combat presentation<br/>[battle_ANIMATOR.gd]"]
  node_enemies["Entity &amp; Enemy Definitions<br/>combat entity models<br/>[enemy_info.gd]"]
  node_health_ui["Health Bars<br/>combat UI<br/>[health_bar.gd]"]
end

subgraph group_meta["Meta, UI &amp; Save"]
  node_upgrade_ui["Upgrades &amp; Selection UI<br/>upgrade interaction<br/>[UpgradePanel.gd]"]
  node_save_manager[("Save Manager<br/>local persistence<br/>[SaveManager.gd]")]
end

node_entry -->|"starts scene flow"| node_scene_manager
node_scene_manager -->|"shows"| node_screens
node_scene_manager -->|"loads"| node_run_scene
node_screens -.->|"navigation requests"| node_scene_manager
node_global_state -.->|"shared signals/state"| node_run_scene
node_profile_options -->|"provides persistent state"| node_global_state
node_audio_upgrades -->|"global services"| node_global_state
node_run_scene -->|"hosts"| node_run_manager
node_run_manager -->|"builds and draws"| node_deck_rng
node_deck_rng -->|"dealt letters"| node_hand
node_hand -->|"places tiles"| node_board
node_letter_components -->|"controls"| node_letter
node_letter -->|"occupies"| node_board
node_board -->|"board state"| node_simulator
node_enemies -->|"enemy data"| node_simulator
node_simulator -->|"resolved actions"| node_animator
node_animator -->|"updates presentation"| node_health_ui
node_simulator -->|"encounter outcome"| node_run_manager
node_run_manager -->|"reward choices"| node_upgrade_ui
node_audio_upgrades -->|"upgrade catalog"| node_upgrade_ui
node_upgrade_ui -->|"modifies deck"| node_deck_rng
node_save_manager -->|"loads and saves"| node_profile_options

click node_entry "https://github.com/skillissuedd/alphabattleters/blob/main/project.godot"
click node_scene_manager "https://github.com/skillissuedd/alphabattleters/blob/main/Entities/managers/SceneManager/SceneManager.gd"
click node_screens "https://github.com/skillissuedd/alphabattleters/blob/main/Entities/Scenes/general/mainMenu/mainMenu.tscn"
click node_run_scene "https://github.com/skillissuedd/alphabattleters/blob/main/Entities/Scenes/Rooms/runScene/runScene.gd"
click node_global_state "https://github.com/skillissuedd/alphabattleters/blob/main/Entities/Globals/Global.gd"
click node_profile_options "https://github.com/skillissuedd/alphabattleters/blob/main/Entities/Globals/GlobalStats.gd"
click node_audio_upgrades "https://github.com/skillissuedd/alphabattleters/blob/main/Entities/Globals/GlobalAudio.gd"
click node_run_manager "https://github.com/skillissuedd/alphabattleters/blob/main/Entities/managers/RunManager/run_manager.gd"
click node_deck_rng "https://github.com/skillissuedd/alphabattleters/blob/main/Entities/managers/Decks/deck.gd"
click node_hand "https://github.com/skillissuedd/alphabattleters/blob/main/Entities/managers/Hand/hand_manager.gd"
click node_board "https://github.com/skillissuedd/alphabattleters/blob/main/Entities/managers/Board/board_manager.gd"
click node_letter "https://github.com/skillissuedd/alphabattleters/blob/main/Entities/Letters/LetterBase/letter_base.tscn"
click node_letter_components "https://github.com/skillissuedd/alphabattleters/blob/main/Entities/Letters/Components/Drag/drag_component.gd"
click node_simulator "https://github.com/skillissuedd/alphabattleters/blob/main/Entities/managers/BattleManagers/Simulator/battle_SIMULATOR.gd"
click node_animator "https://github.com/skillissuedd/alphabattleters/blob/main/Entities/managers/BattleManagers/Animator/battle_ANIMATOR.gd"
click node_enemies "https://github.com/skillissuedd/alphabattleters/blob/main/Entities/Enemies/Database/enemy_info.gd"
click node_health_ui "https://github.com/skillissuedd/alphabattleters/blob/main/Entities/healthBars/health_bar.gd"
click node_upgrade_ui "https://github.com/skillissuedd/alphabattleters/blob/main/Entities/UIPopups/UpgradePanel/UpgradePanel.gd"
click node_save_manager "https://github.com/skillissuedd/alphabattleters/blob/main/Entities/managers/saveload/SaveManager.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_entry,node_scene_manager,node_screens toneBlue
class node_global_state,node_profile_options,node_audio_upgrades toneAmber
class node_run_scene,node_run_manager,node_deck_rng,node_hand,node_board,node_letter,node_letter_components toneMint
class node_simulator,node_animator,node_enemies,node_health_ui toneRose
class node_upgrade_ui,node_save_manager toneIndigo
```

## Components

### Godot Runtime

- [Project Entry](https://github.com/skillissuedd/alphabattleters/blob/main/project.godot): Godot project config · Configures the startup scene and desktop export. · `project.godot`
- [Scene Manager](https://github.com/skillissuedd/alphabattleters/blob/main/Entities/managers/SceneManager/SceneManager.gd): scene transition manager · `Entities/managers/SceneManager/SceneManager.gd`
- [Menu & Outcome Screens](https://github.com/skillissuedd/alphabattleters/blob/main/Entities/Scenes/general/mainMenu/mainMenu.tscn): Godot scenes · Menu, loading, and game-over views. · `Entities/Scenes/general/mainMenu/mainMenu.tscn`

### Global Services

Shared autoload state and coordination.

- [Global State & Signals](https://github.com/skillissuedd/alphabattleters/blob/main/Entities/Globals/Global.gd): autoload services · Shared state and event coordination. · `Entities/Globals/Global.gd`
- [Profile & Options](https://github.com/skillissuedd/alphabattleters/blob/main/Entities/Globals/GlobalStats.gd): autoload state · `Entities/Globals/GlobalStats.gd`
- [Audio & Upgrade Catalog](https://github.com/skillissuedd/alphabattleters/blob/main/Entities/Globals/GlobalAudio.gd): autoload services · `Entities/Globals/GlobalAudio.gd`

### Run Gameplay

- [Run Scene](https://github.com/skillissuedd/alphabattleters/blob/main/Entities/Scenes/Rooms/runScene/runScene.gd): Godot scene controller · Hosts active gameplay. · `Entities/Scenes/Rooms/runScene/runScene.gd`
- [Run Manager](https://github.com/skillissuedd/alphabattleters/blob/main/Entities/managers/RunManager/run_manager.gd): run orchestrator · Owns progression and encounter state. · `Entities/managers/RunManager/run_manager.gd`
- [Deck & RNG](https://github.com/skillissuedd/alphabattleters/blob/main/Entities/managers/Decks/deck.gd): draw source · `Entities/managers/Decks/deck.gd`
- [Hand Manager](https://github.com/skillissuedd/alphabattleters/blob/main/Entities/managers/Hand/hand_manager.gd): hand interaction · `Entities/managers/Hand/hand_manager.gd`
- [Board Manager](https://github.com/skillissuedd/alphabattleters/blob/main/Entities/managers/Board/board_manager.gd): placement state · Owns tile occupancy and placement. · `Entities/managers/Board/board_manager.gd`
- [Letter Entity](https://github.com/skillissuedd/alphabattleters/blob/main/Entities/Letters/LetterBase/letter_base.tscn): composable scene entity · Letter identity, display, and combat properties. · `Entities/Letters/LetterBase/letter_base.tscn`
- [Letter Interaction Components](https://github.com/skillissuedd/alphabattleters/blob/main/Entities/Letters/Components/Drag/drag_component.gd): input and visual components · Drag, rotation, status, and related behavior. · `Entities/Letters/Components/Drag/drag_component.gd`

### Combat

- [Battle Simulator](https://github.com/skillissuedd/alphabattleters/blob/main/Entities/managers/BattleManagers/Simulator/battle_SIMULATOR.gd): combat rules engine · Calculates combat state and outcomes. · `Entities/managers/BattleManagers/Simulator/battle_SIMULATOR.gd`
- [Battle Animator](https://github.com/skillissuedd/alphabattleters/blob/main/Entities/managers/BattleManagers/Animator/battle_ANIMATOR.gd): combat presentation · Sequences combat visuals. · `Entities/managers/BattleManagers/Animator/battle_ANIMATOR.gd`
- [Entity & Enemy Definitions](https://github.com/skillissuedd/alphabattleters/blob/main/Entities/Enemies/Database/enemy_info.gd): combat entity models · `Entities/Enemies/Database/enemy_info.gd`
- [Health Bars](https://github.com/skillissuedd/alphabattleters/blob/main/Entities/healthBars/health_bar.gd): combat UI · `Entities/healthBars/health_bar.gd`

### Meta, UI & Save

- [Upgrades & Selection UI](https://github.com/skillissuedd/alphabattleters/blob/main/Entities/UIPopups/UpgradePanel/UpgradePanel.gd): upgrade interaction · Upgrade slots and deck/action dialogs. · `Entities/UIPopups/UpgradePanel/UpgradePanel.gd`
- [Save Manager](https://github.com/skillissuedd/alphabattleters/blob/main/Entities/managers/saveload/SaveManager.gd): local persistence · Persists local profile and settings. · `Entities/managers/saveload/SaveManager.gd`

## Connections

- Project Entry → Scene Manager: starts scene flow
- Scene Manager → Menu & Outcome Screens: shows
- Scene Manager → Run Scene: loads
- Menu & Outcome Screens → Scene Manager: navigation requests
- Global State & Signals → Run Scene: shared signals/state
- Profile & Options → Global State & Signals: provides persistent state
- Audio & Upgrade Catalog → Global State & Signals: global services
- Run Scene → Run Manager: hosts
- Run Manager → Deck & RNG: builds and draws
- Deck & RNG → Hand Manager: dealt letters
- Hand Manager → Board Manager: places tiles
- Letter Interaction Components → Letter Entity: controls
- Letter Entity → Board Manager: occupies
- Board Manager → Battle Simulator: board state
- Entity & Enemy Definitions → Battle Simulator: enemy data
- Battle Simulator → Battle Animator: resolved actions
- Battle Animator → Health Bars: updates presentation
- Battle Simulator → Run Manager: encounter outcome
- Run Manager → Upgrades & Selection UI: reward choices
- Audio & Upgrade Catalog → Upgrades & Selection UI: upgrade catalog
- Upgrades & Selection UI → Deck & RNG: modifies deck
- Save Manager → Profile & Options: loads and saves