# ligameacademy/projectsx architecture

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

- Interactive diagram: https://gitdiagram.com/ligameacademy/projectsx
- Repository: https://github.com/ligameacademy/projectsx

## Overview

##### Project type and purpose
- This is a full-game project built on the Godot engine (“card_roguelike”), inspired by Slay the Spire.
- Core features (from README): turn-based card combat, deck building, data-driven CSV configs, extendable Ability/Buff/Attribute systems, predictable monster AI (behavior tree).

##### File structure
- Top-level:
- addons/li_framework: custom UI framework, auto managers, and state-machine base classes
- datatables/: CSV files + imports for cards, buffs, stats, monsters, abilities
- source/: all GDScript code subdivided into:
– UI (forms + widgets)
– auto (audio_manager, game_instance, scene_manager)
– entities (player, enemies, Damage, models + scenes)
– scenes (combat_scene, map_scene + base class)
– system (buff_system, card_system, effect_system, intent_system)
– utility (asset_utility, plus docs/xls2csv scripts for CSV→Godot imports)
- main.gd / main.tscn + project.godot: entry point

##### Key insights from README
- There are two high-level flows (game procedure & combat procedure) already documented in docs/ as PNGs.
- Data is driven via CSVs → datatable_manager (in li_framework/auto & source/auto).
- Systems: buff, card, effect, intent each have “C_*System.gd” controllers and models/data classes.
- UI is entirely modular (forms + widgets) and managed by a UIManager in the addon.

a. Main components
1) Godot Engine Core (scene tree, signal/event loop)
2) Addon Frameworks
– UI framework (UIBase, UIForm, UIManager, UIPopup)
– Auto managers (scene_manager, audio_manager, datatable_manager, event_bus)
– State-machine base classes (for AI and other stateful systems)
3) Game Flow Controller (main.gd → game_instance)
4) Scenes Layer
– MapScene, CombatScene (inherit SceneBase)
5) UI Layer
– Forms (menu, map_form, combat_form)
– Widgets (cards, health bars, intents, tooltips, turn indicators)
6) Game Logic Systems
– CardSystem: draws, plays, discards, deck management
– BuffSystem: applies abstract buffs, attribute updates
– EffectSystem: damage, shield, vulnerable, custom effects
– IntentSystem: AI intent generation from behavior trees/state machine
7) Entities / Models
– Player, Enemy (with their .gd models + .tscn)
– CharacterModel, EnemyModel, PlayerModel, Damage entity
8) Data Layer
– CSV datatables → loaded by datatable_manager → model classes
9) Utility & Assets
– asset_utility, xls2csv scripts (off-line), plus all assets (audio/texture/font)

b. Relationships & interactions
- On startup, main.gd initializes GameInstance → loads datatables via DatatableManager.
- SceneManager loads the initial MapScene (game flow).
- Scenes subscribe to EventBus for global events (e.g., “card_played”, “turn_start”).
- UIManager renders UIForms/Widgets on top of the active Scene.
- Player/Enemy Entities reside in the Scene tree; their Models feed into Systems.
- When a card is played: UI widget → EventBus → CardSystem → updates Entity and triggers EffectSystem/BuffSystem → EventBus → UI & Scene update.
- AudioManager plays SFX/Music in response to system events.

##### Architectural patterns & design principles
- Layered MVC-style:
- Model (Entities + Data)
- View (Scenes + UI + Assets)
- Controller (Systems + Managers)
- Data-driven configuration: CSV → datatables → models
- Event-driven communication: EventBus decouples UI, Scenes, Systems
- State machine for AI & other stateful logic (via base_state classes)
- Modular UI via a plugin (li_framework/UIframework)

##### Technologies & frameworks
- Godot Engine (v3.x or 4.x)
- GDScript for all code
- li_framework (custom Godot plugin for UI, auto managers, state machine)
- CSV import pipeline (via docs/xls2csv.py & plugin)
- Behavior trees/state machines for AI
- Data files: .tscn scenes, .tres resources, .csv configs

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Godot Engine"
        direction TB

        %% Data Layer
        subgraph "Data Layer"
            direction TB
            CSVData["CSV Datatables"]:::data
        end

        %% Auto Managers
        subgraph "Auto Managers" 
            direction TB
            DM["DatatableManager"]:::manager
            EB["EventBus"]:::manager
            SM["SceneManager"]:::manager
            AM["AudioManager"]:::manager
        end

        %% Game Flow Controller
        GI["GameInstance"]:::manager

        %% Scenes Layer
        subgraph "Scenes Layer"
            direction TB
            SB["SceneBase"]:::view
            MS["MapScene"]:::view
            CS["CombatScene"]:::view
        end

        %% UI Layer
        subgraph "UI Layer"
            direction TB
            subgraph "Forms"
                direction TB
                MenuForm["MenuForm"]:::ui
                MapForm["MapForm"]:::ui
                CombatForm["CombatForm"]:::ui
            end
            subgraph "Widgets"
                direction TB
                CardWidget["Card Widgets"]:::ui
                HealthBar["Health Bar"]:::ui
                BuffWidget["Buff Widget"]:::ui
                IntentWidget["Intent Status"]:::ui
                Tooltip["Tooltip"]:::ui
                TurnIndicator["Turn Indicator"]:::ui
            end
        end

        %% Systems
        subgraph "Game Logic Systems"
            direction TB
            CardSys["CardSystem"]:::system
            BuffSys["BuffSystem"]:::system
            EffectSys["EffectSystem"]:::system
            IntentSys["IntentSystem"]:::system
        end

        %% Entities / Models
        subgraph "Entities / Models"
            direction TB
            PM["PlayerModel"]:::entity
            EM["EnemyModel"]:::entity
            CM["CharacterModel"]:::entity
            DMG["Damage"]:::entity
        end

        %% Utility & Assets
        subgraph "Utility & Assets"
            direction TB
            AssetUtil["AssetUtility"]:::utility
            XLS2CSV["xls2csv Scripts"]:::utility
        end

        %% Plugin UI & StateMachine
        subgraph "li_framework Plugin"
            direction TB
            UIBase["UIBase"]:::plugin
            UIForm["UIForm"]:::plugin
            UIManager["UIManager"]:::plugin
            UIPopup["UIPopup"]:::plugin
            BaseState["BaseState"]:::plugin
            BaseSM["BaseStateMachine"]:::plugin
        end

        %% Entry Point
        Main["main.gd / main.tscn"]:::entry

        %% Relationships
        Main -->|initializes| GI
        GI -->|load_csv| DM
        DM -->|reads| CSVData
        GI -->|setup managers| SM
        GI -->|setup managers| AM
        GI -->|setup managers| EB

        SM -->|load initial scene| MS
        SB -->|base for| MS
        SB -->|base for| CS

        MS -->|subscribe| EB
        CS -->|subscribe| EB

        UIManager -->|renders| MenuForm
        UIManager -->|renders| MapForm
        UIManager -->|renders| CombatForm
        UIManager -->|renders| CardWidget

        MenuForm -->|user action| EB
        CardWidget -->|play_card_event| EB
        EB -->|play_card_event| CardSys
        CardSys -->|update entity| PM
        CardSys -->|trigger| EffectSys
        EffectSys -->|apply| PM
        EffectSys -->|apply| EM
        CardSys -->|trigger| BuffSys
        BuffSys -->|apply| PM
        IntentSys -->|generate intents| EM
        IntentSys -->|send| EB
        EB -->|intent_update| IntentWidget

        AM -->|on events| EB

        AssetUtil -->|manage assets| CSVData
        XLS2CSV -->|generate| CSVData

    end

    subgraph Legend
        direction TB
        LM["Managers"]:::manager
        LS["Systems"]:::system
        LE["Entities"]:::entity
        LU["UI Components"]:::ui
        LD["Data Stores"]:::data
        LPL["Plugin Components"]:::plugin
        LEN["Entry Point"]:::entry
        LUT["Utilities"]:::utility
    end

    %% Click Events
    click UIBase "https://github.com/ligameacademy/projectsx/blob/master/addons/li_framework/UIframework/UIBase.gd"
    click UIForm "https://github.com/ligameacademy/projectsx/blob/master/addons/li_framework/UIframework/UIForm.gd"
    click UIManager "https://github.com/ligameacademy/projectsx/blob/master/addons/li_framework/UIframework/UIManager.gd"
    click UIPopup "https://github.com/ligameacademy/projectsx/blob/master/addons/li_framework/UIframework/UIPopup.gd"
    click DM "https://github.com/ligameacademy/projectsx/blob/master/addons/li_framework/auto/datatable_manager.gd"
    click EB "https://github.com/ligameacademy/projectsx/blob/master/addons/li_framework/auto/event_bus.gd"
    click BaseState "https://github.com/ligameacademy/projectsx/blob/master/addons/li_framework/state_machine/base_state.gd"
    click BaseSM "https://github.com/ligameacademy/projectsx/blob/master/addons/li_framework/state_machine/base_state_machine.gd"
    click GI "https://github.com/ligameacademy/projectsx/blob/master/source/auto/game_instance.gd"
    click SM "https://github.com/ligameacademy/projectsx/blob/master/source/auto/scene_manager.gd"
    click AM "https://github.com/ligameacademy/projectsx/blob/master/source/auto/audio_manager.gd"
    click MS "https://github.com/ligameacademy/projectsx/blob/master/source/scenes/map_scene.gd"
    click CS "https://github.com/ligameacademy/projectsx/blob/master/source/scenes/combat_scene.gd"
    click SB "https://github.com/ligameacademy/projectsx/blob/master/source/scenes/scene_base.gd"
    click MenuForm "https://github.com/ligameacademy/projectsx/blob/master/source/UI/form/menu_form.tscn"
    click MapForm "https://github.com/ligameacademy/projectsx/blob/master/source/UI/form/map_form.tscn"
    click CombatForm "https://github.com/ligameacademy/projectsx/blob/master/source/UI/form/combat_form.tscn"
    click CardSys "https://github.com/ligameacademy/projectsx/blob/master/source/system/card_system/C_CardSystem.gd"
    click BuffSys "https://github.com/ligameacademy/projectsx/blob/master/source/system/buff_system/C_BuffSystem.gd"
    click EffectSys "https://github.com/ligameacademy/projectsx/blob/master/source/system/effect_system/effect.gd"
    click IntentSys "https://github.com/ligameacademy/projectsx/blob/master/source/system/intent_system/C_IntentSystem.gd"
    click PM "https://github.com/ligameacademy/projectsx/blob/master/source/entities/player_model.gd"
    click EM "https://github.com/ligameacademy/projectsx/blob/master/source/entities/enemy_model.gd"
    click CM "https://github.com/ligameacademy/projectsx/blob/master/source/entities/character_model.gd"
    click DMG "https://github.com/ligameacademy/projectsx/blob/master/source/entities/Damage.gd"
    click AssetUtil "https://github.com/ligameacademy/projectsx/blob/master/source/utility/asset_utility.gd"
    click XLS2CSV "https://github.com/ligameacademy/projectsx/blob/master/docs/xls2csv.py"

    %% Styles
    classDef manager fill:#AED6F1,stroke:#1B4F72
    classDef system fill:#A9DFBF,stroke:#1D8348
    classDef entity fill:#F5CBA7,stroke:#935116
    classDef ui fill:#F9E79F,stroke:#B7950B
    classDef data fill:#D5D8DC,stroke:#616A6B
    classDef plugin fill:#FADBD8,stroke:#943126
    classDef utility fill:#E8DAEF,stroke:#6C3483
    classDef view fill:#D6EAF8,stroke:#2874A6
    classDef entry fill:#FDEBD0,stroke:#BA4A00
```
