# empty-zzj/hoilai-galgame-framework architecture

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

- Interactive diagram: https://gitdiagram.com/empty-zzj/hoilai-galgame-framework
- Repository: https://github.com/empty-zzj/hoilai-galgame-framework

## Overview

##### Project type and purpose
- HOILAI Galgame Framework (HGF) is an open-source Unity framework for building “Galgame” (visual novel) style games.
- It provides both runtime modules (scene management, UI, text parser, choice logic, animations) and editor extensions (custom attributes, property drawers) to accelerate development.

##### File structure
- Top-level “HOILAI_Galgame_Framework” folder is a Unity project:
- Assets/HGF/Scripts — core runtime code (GalManager_*, GameAPI, start logic)
- Assets/HGF/Tetra Attributes — editor-only code (custom attributes & drawers)
- Assets/Resources/HGF — data files (XML story, JSON char metadata, prefabs, audio, images)
- Assets/Plugins/Demigiant — third-party tweening libraries (DOTween, DemiLib)
- Assets/Scenes — sample Unity scene that bootstraps HGF
- ProjectSettings and Packages specify Unity settings and package dependencies.

##### README for additional insights
- HGF emphasizes pure-text story scripts (XML), hot-reloadable assets, nested branching, character & background animations.
- Version 2.0 updated character loading logic and bug fixes.

a. Main components
- Unity Engine (core runtime, scene update loop)
- HGF Runtime Modules
– HGFStartter / HGFStartModel: bootstraps framework in a Scene
– GameAPI: facade for external code to interact with HGF
– GalManager_*: sub-modules handling background, characters (image, animation, dialogue), text, choices
– Utility scripts: BGScaler, ZoomImage, StringInList
- Resource Manager
– XML/JSON parser loads plot and character data from Assets/Resources/HGF
– Prefab loader (Buttons, Character images)
– Audio loader (mp3 files)
- DOTween / DemiLib (Plugins)
– Provides tweening engine used by GalManager_CharacterAnimate, text fade, UI animations
- Editor Extensions (Tetra Attributes)
– Custom attributes & property drawers enhancing Unity Inspector for HGF components
- Sample Scene (Assets/Scenes/Demo.unity / SampleScene.unity)
– Contains HGFStartter component, references to scripts & resources

b. Relationships and interactions
- On Scene load → HGFStartter invokes HGFStartModel → GameAPI initializes GalManager modules
- GalManager modules request data from Resource Manager → XML/JSON → instantiate prefabs (images, buttons)
- UI modules use DOTween to animate transitions (fade, slide, shake)
- Editor Extensions do not run at runtime; they hook into Unity Editor to render custom inspectors for HGF components

c. Architectural patterns & design principles
- Modular design: each concern (text, choice, character, background) is in its own GalManager_* class
- Facade pattern: GameAPI unifies access to multiple subsystems
- Data-driven: story & character data externalized as XML/JSON, supporting hot-reload
- Dependency injection by Unity’s component model: managers attach to GameObjects in Scene

d. Key technologies, frameworks, libraries
- Unity 2021+ (URP settings in Assets/Settings)
- DOTween / DOTweenPro for animations
- TetraCreations.Attributes for custom editor attributes

##### Detail and essential elements
- Both runtime and editor phases.
- Do not overthink: more granularity gives a clearer view of responsibilities and dependencies.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Scenes
    subgraph "Scenes"
        direction TB
        DemoScene["Demo.unity Scene"]:::scene
        SampleScene["SampleScene.unity"]:::scene
    end

    %% Runtime Modules
    subgraph "HGF Runtime Modules"
        direction TB
        Startter["HGFStartter"]:::runtime
        Model["HGFStartModel"]:::runtime
        API["GameAPI"]:::runtime
        Core["GalManager (Core)"]:::runtime
        BackImg["GalManager_BackImg"]:::runtime
        CharImg["GalManager_CharacterImg"]:::runtime
        CharAnimate["GalManager_CharacterAnimate"]:::runtime
        CharMessage["GalManager_CharacterMessage"]:::runtime
        TextDisp["GalManager_Text"]:::runtime
        ChoiceLogic["GalManager_Choice"]:::runtime
        ChoiceComp["GalComponent_Choice"]:::runtime
        BGScaler["BGScaler"]:::runtime
        ZoomImg["ZoomImage"]:::runtime
        StrList["StringInList"]:::runtime
    end

    %% Resource Manager
    subgraph "Resource Manager" 
        direction TB
        Resources["Assets/Resources/HGF"]:::data
    end

    %% Plugins
    subgraph "Third-Party Plugins"
        direction TB
        DOTween["DOTween"]:::external
        DemiLib["DemiLib"]:::external
    end

    %% Editor Extensions
    subgraph "Editor Extensions (Tetra Attributes)"
        direction TB
        TECore["Tetra Attributes Core"]:::editor
        TEDrawers["Property Drawers"]:::editor
    end

    %% Relationships
    DemoScene -->|loads| Startter
    SampleScene -->|loads| Startter
    Startter -->|invokes| Model
    Model -->|initializes| API
    API -->|facade to| Core
    Core --> BackImg
    Core --> CharImg
    Core --> CharAnimate
    Core --> CharMessage
    Core --> TextDisp
    Core --> ChoiceLogic
    Core --> ChoiceComp
    Core --> BGScaler
    Core --> ZoomImg
    Core --> StrList

    BackImg -->|requests data| Resources
    CharImg -->|requests data| Resources
    CharAnimate -->|uses animations from| DOTween
    CharMessage -->|uses text fade| DOTween
    TextDisp -->|uses fade| DOTween
    ChoiceLogic -->|generates buttons| Resources
    ChoiceComp -->|generates UI| Resources

    Resources -->|contains| StoryXML["Test_Plot.xml"]:::data
    Resources -->|contains| CharJSON["Test_Character.json"]:::data
    Resources -->|contains| PrefabChoice["Button-Choice.prefab"]:::data
    Resources -->|contains| PrefabChar["Img-Character.prefab"]:::data
    Resources -->|contains| AudioFolder["audio/"]:::data
    Resources -->|contains| ImageFolder["img/"]:::data

    %% Editor does not link at runtime
    TECore -.-> TECore
    TEDrawers -.-> TEDrawers

    %% Click Events
    click Startter "https://github.com/empty-zzj/hoilai-galgame-framework/blob/master/HOILAI_Galgame_Framework/Assets/HGF/Scripts/HGFStartter.cs"
    click Model "https://github.com/empty-zzj/hoilai-galgame-framework/blob/master/HOILAI_Galgame_Framework/Assets/HGF/Scripts/HGFStartModel.cs"
    click API "https://github.com/empty-zzj/hoilai-galgame-framework/blob/master/HOILAI_Galgame_Framework/Assets/HGF/Scripts/GameAPI.cs"
    click Core "https://github.com/empty-zzj/hoilai-galgame-framework/blob/master/HOILAI_Galgame_Framework/Assets/HGF/Scripts/Galgame/GalManager.cs"
    click BackImg "https://github.com/empty-zzj/hoilai-galgame-framework/blob/master/HOILAI_Galgame_Framework/Assets/HGF/Scripts/Galgame/GalManager_BackImg.cs"
    click CharImg "https://github.com/empty-zzj/hoilai-galgame-framework/blob/master/HOILAI_Galgame_Framework/Assets/HGF/Scripts/Galgame/GalManager_CharacterImg.cs"
    click CharAnimate "https://github.com/empty-zzj/hoilai-galgame-framework/blob/master/HOILAI_Galgame_Framework/Assets/HGF/Scripts/Galgame/GalManager_CharacterAnimate.cs"
    click CharMessage "https://github.com/empty-zzj/hoilai-galgame-framework/blob/master/HOILAI_Galgame_Framework/Assets/HGF/Scripts/Galgame/GalManager_CharacterMessage.cs"
    click TextDisp "https://github.com/empty-zzj/hoilai-galgame-framework/blob/master/HOILAI_Galgame_Framework/Assets/HGF/Scripts/Galgame/GalManager_Text.cs"
    click ChoiceLogic "https://github.com/empty-zzj/hoilai-galgame-framework/blob/master/HOILAI_Galgame_Framework/Assets/HGF/Scripts/Galgame/GalManager_Choice.cs"
    click ChoiceComp "https://github.com/empty-zzj/hoilai-galgame-framework/blob/master/HOILAI_Galgame_Framework/Assets/HGF/Scripts/Galgame/GalComponent_Choice.cs"
    click BGScaler "https://github.com/empty-zzj/hoilai-galgame-framework/blob/master/HOILAI_Galgame_Framework/Assets/HGF/Scripts/BGScaler.cs"
    click ZoomImg "https://github.com/empty-zzj/hoilai-galgame-framework/blob/master/HOILAI_Galgame_Framework/Assets/HGF/Scripts/ZoomImage.cs"
    click StrList "https://github.com/empty-zzj/hoilai-galgame-framework/blob/master/HOILAI_Galgame_Framework/Assets/HGF/Scripts/StringInList.cs"
    click Resources "https://github.com/empty-zzj/hoilai-galgame-framework/tree/master/HOILAI_Galgame_Framework/Assets/Resources/HGF"
    click PrefabChoice "https://github.com/empty-zzj/hoilai-galgame-framework/blob/master/HOILAI_Galgame_Framework/Assets/Resources/HGF/Button-Choice.prefab"
    click PrefabChar "https://github.com/empty-zzj/hoilai-galgame-framework/blob/master/HOILAI_Galgame_Framework/Assets/Resources/HGF/Img-Character.prefab"
    click StoryXML "https://github.com/empty-zzj/hoilai-galgame-framework/blob/master/HOILAI_Galgame_Framework/Assets/Resources/HGF/Test_Plot.xml"
    click CharJSON "https://github.com/empty-zzj/hoilai-galgame-framework/blob/master/HOILAI_Galgame_Framework/Assets/Resources/HGF/Test_Character.json"
    click AudioFolder "https://github.com/empty-zzj/hoilai-galgame-framework/tree/master/HOILAI_Galgame_Framework/Assets/Resources/HGF/audio"
    click ImageFolder "https://github.com/empty-zzj/hoilai-galgame-framework/tree/master/HOILAI_Galgame_Framework/Assets/Resources/HGF/img"
    click DOTween "https://github.com/empty-zzj/hoilai-galgame-framework/tree/master/HOILAI_Galgame_Framework/Assets/Plugins/Demigiant/DOTween"
    click DemiLib "https://github.com/empty-zzj/hoilai-galgame-framework/tree/master/HOILAI_Galgame_Framework/Assets/Plugins/Demigiant/DemiLib"
    click TECore "https://github.com/empty-zzj/hoilai-galgame-framework/tree/master/HOILAI_Galgame_Framework/Assets/HGF/Tetra Attributes/Core"
    click TEDrawers "https://github.com/empty-zzj/hoilai-galgame-framework/tree/master/HOILAI_Galgame_Framework/Assets/HGF/Tetra Attributes/Editor/Property Drawers"
    click DemoScene "https://github.com/empty-zzj/hoilai-galgame-framework/blob/master/HOILAI_Galgame_Framework/Assets/HGF/Scenes/Demo.unity"
    click SampleScene "https://github.com/empty-zzj/hoilai-galgame-framework/blob/master/HOILAI_Galgame_Framework/Assets/Scenes/SampleScene.unity"

    %% Styles
    classDef runtime fill:#D6EAF8,stroke:#1B4F72,color:#1B2631
    classDef data fill:#D5F5E3,stroke:#145A32,color:#1D8348
    classDef external fill:#FAD7A0,stroke:#B9770E,color:#7E5109
    classDef editor fill:#E8DAEF,stroke:#6C3483,color:#4A235A
    classDef scene fill:#F2F3F4,stroke:#566573,color:#2C3E50
```
