# watershed117/ushio_noa architecture

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

- Interactive diagram: https://gitdiagram.com/watershed117/ushio_noa
- Repository: https://github.com/watershed117/ushio_noa

## Overview

##### Main Components
- Game Engine & Core Logic: The Ren'Py engine forms the heart of the visual novel. In the file tree you see Ren'Py scripts (e.g., script.rpy, gui.rpy, options.rpy, var.rpy), which define gameplay, dialogue flow, and GUI components.
- API Integration Modules:
- Chat Functionality: Files like api_ren.py, api_ver.py, functions_ren.py, and event_loop.py indicate integration with external dialogue models (deepseek-chat).
- Translation Module: The project makes use of chatglm for translating texts. The config.json (modified during runtime) includes settings for the translator_model.
- Multimodal & TTS Functionality: The integration of GPT-SoVITS for voice synthesis, along with configuration of API keys and file organization under GPT-SoVITS-v2, are key to this element. Files such as audio files, tts flag (in config.json), and support scripts (e.g., gsv files, api.bat, api_v2.py) provide clues of this integration.
- Media Assets & Resources: A wide range of assets is found under “game/audio”, “game/images”, “game/fonts”, and the structured background images. These assets are used by the game engine to change backgrounds, animate characters, and produce audio.
- Asynchronous & Utility Modules:
- Modules like async.py, thread_pool.py, and batch.py demonstrate the use of asynchronous execution and handling batch operations, likely for network calls or time-sensitive operations.
- File uploads and history saving are managed by file_upload.py and title_changer.py among others.
- Configuration & External Integration: The config.json file in the game directory holds all API keys and model configuration properties. This, combined with the directory names under “python-packages”, shows a bundled dependency environment for third-party libraries (e.g., colorama) used for terminal output or logging.

##### Relationships and Data Flow
- User Interaction → Ren'Py GUI: The game’s dialogue interface, mapped out in the GUI (buttons and interface files in game/gui, prompts in game/prompts) triggers events.
- On-Click Events: Interface buttons (for playing voice, saving voice, clearing context, saving conversation) invoke functions contained in modules (e.g., file_upload.py, api modules) to process the data.
- External Communication: From the in-game dialogue, API calls are made to:
- deepseek-chat for generating dialogue responses,
- chatglm for translation (Chinese to Japanese) of dialogue,
- gpt-sovits for TTS synthesis (which uses GPT-SoVITS and associated helper scripts).
- Asynchronous Processing: Modules like async.py and thread_pool.py manage calls to these external services so that gameplay remains responsive.
- Asset Delivery: Visual and audio assets are stored locally (organized under game/images and game/audio) and are loaded/changed in response to user choices.

##### Architectural Patterns and Design Principles
- Modular Design: The project is cleanly divided into components for game logic, GUI, API integrations, and resource management. This separation of concerns simplifies maintenance and potential future expansion.
- Configuration Driven: The architecture relies on a central configuration file (config.json) to manage API keys, endpoints, and toggles (e.g., tts flag) that dynamically change behavior.
- Asynchronous and Event-driven Execution: An event loop and thread pool indicate the design includes asynchronous handling for tasks such as network I/O and TTS generation.
- Extensibility: Given the use of external open-source projects (Ren’Py, GPT-SoVITS, renpy-SWHolo), there is a plug-in style integration, making interfaces with external models replaceable or configurable.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface & Ren'Py Engine Subgraph
    subgraph "User Interface & Ren'Py Engine"
        UI_Script["Script (Ren'Py)"]:::ui
        UI_GUI["GUI (Ren'Py)"]:::ui
        UI_Options["Options (Ren'Py)"]:::ui
        UI_Var["Variables (Ren'Py)"]:::ui
        UI_Screens["Screens (Ren'Py)"]:::ui
    end

    %% API Integration Modules Subgraph
    subgraph "API Integration Modules"
        %% Chat API Integration
        subgraph "Chat API Integration"
            API_Ren["Chat API: Ren"]:::api
            API_Functions["Chat API: Functions"]:::api
            API_EventLoop["Chat API: Event Loop"]:::api
            API_Ver["Chat API: Ver"]:::api
        end
        %% Translation Module
        subgraph "Translation Module"
            T_Models["Translation: Gemini Models"]:::api
            T_Translator["Translation: Translator Prompt"]:::api
        end
        %% TTS/Multimodal Integration
        subgraph "TTS/Multimodal Integration"
            TTS_GSV["TTS: GSV Assets"]:::api
            TTS_AudioGen["TTS: Audio Generator"]:::api
        end
    end

    %% Asynchronous & Utility Modules Subgraph
    subgraph "Asynchronous & Utility Modules"
        Async_Mod["Async"]:::async
        ThreadPool["Thread Pool"]:::async
        Batch_Mod["Batch"]:::async
        FileUpload["File Upload"]:::async
        TitleChanger["Title Changer"]:::async
    end

    %% Media Assets & Resources Subgraph
    subgraph "Media Assets & Resources"
        Asset_Audio["Audio Assets"]:::assets
        Asset_Images["Image Assets"]:::assets
        Asset_Fonts["Font Assets"]:::assets
    end

    %% Configuration & External Integration Subgraph
    subgraph "Configuration & External Integration"
        Config_GSV["GSV Config"]:::config
        Config_PythonPkgs["Python Packages"]:::config
    end

    %% Connections between UI & API Integration
    UI_GUI -->|"triggersChat"| API_Ren
    UI_GUI -->|"triggersTranslation"| T_Models
    UI_GUI -->|"triggersTTS"| TTS_AudioGen

    %% Internal Chat API Integration Flow
    API_Ren -->|"calls"| API_Functions
    API_Functions -->|"manages"| API_EventLoop
    API_EventLoop -->|"routes"| API_Ver

    %% Asynchronous Integration with Chat API
    API_Ren -->|"asyncCall"| Async_Mod
    API_Ver -->|"asyncCall"| Async_Mod
    API_Functions -->|"asyncCall"| Async_Mod
    API_EventLoop -->|"asyncCall"| Async_Mod

    %% Distribution within Asynchronous Modules
    Async_Mod -->|"delegates"| ThreadPool
    Async_Mod -->|"batches"| Batch_Mod
    Async_Mod -->|"handles"| FileUpload
    Async_Mod -->|"managesTitles"| TitleChanger

    %% Feedback from API Integration to UI
    API_Ren -->|"response"| UI_GUI
    T_Translator -->|"feedsTranslation"| UI_GUI

    %% Translation Module internal connection
    T_Models -->|"configures"| T_Translator

    %% TTS Integration connections
    TTS_GSV -->|"config"| Config_GSV
    Config_GSV -->|"enablesTTS"| TTS_AudioGen

    %% UI accesses Media Assets
    UI_GUI -->|"loadsAssets"| Asset_Audio
    UI_GUI -->|"loadsAssets"| Asset_Images
    UI_GUI -->|"loadsAssets"| Asset_Fonts

    %% Configuration influences Asynchronous Utilities
    Config_PythonPkgs -->|"dependencies"| Async_Mod

    %% Styles
    classDef ui fill:#aee1f9,stroke:#333,stroke-width:2px;
    classDef api fill:#f9d6a5,stroke:#333,stroke-width:2px;
    classDef async fill:#c7f9cc,stroke:#333,stroke-width:2px;
    classDef assets fill:#ffe699,stroke:#333,stroke-width:2px;
    classDef config fill:#d3e0ea,stroke:#333,stroke-width:2px;

    %% Click Events for Game Engine & Core Logic
    click UI_Script "https://github.com/watershed117/ushio_noa/blob/main/game/script.rpy"
    click UI_GUI "https://github.com/watershed117/ushio_noa/blob/main/game/gui.rpy"
    click UI_Options "https://github.com/watershed117/ushio_noa/blob/main/game/options.rpy"
    click UI_Var "https://github.com/watershed117/ushio_noa/blob/main/game/var.rpy"
    click UI_Screens "https://github.com/watershed117/ushio_noa/blob/main/game/screens.rpy"

    %% Click Events for Chat API Integration Module
    click API_Ren "https://github.com/watershed117/ushio_noa/blob/main/game/api_ren.py"
    click API_Ver "https://github.com/watershed117/ushio_noa/blob/main/game/api_ver.py"
    click API_Functions "https://github.com/watershed117/ushio_noa/blob/main/game/functions_ren.py"
    click API_EventLoop "https://github.com/watershed117/ushio_noa/blob/main/game/event_loop.py"

    %% Click Events for Translation Module
    click T_Models "https://github.com/watershed117/ushio_noa/blob/main/game/gemini_models.json"
    click T_Translator "https://github.com/watershed117/ushio_noa/blob/main/game/prompts/translator.txt"

    %% Click Events for TTS/Multimodal Integration
    click TTS_GSV "https://github.com/watershed117/ushio_noa/tree/main/game/audio/gsv"
    click TTS_AudioGen "https://github.com/watershed117/ushio_noa/blob/main/game/audio_generator.py"

    %% Click Events for Asynchronous & Utility Modules
    click Async_Mod "https://github.com/watershed117/ushio_noa/blob/main/game/async.py"
    click ThreadPool "https://github.com/watershed117/ushio_noa/blob/main/game/thread_pool.py"
    click Batch_Mod "https://github.com/watershed117/ushio_noa/blob/main/game/batch.py"
    click FileUpload "https://github.com/watershed117/ushio_noa/blob/main/game/file_upload.py"
    click TitleChanger "https://github.com/watershed117/ushio_noa/blob/main/game/title_changer.py"

    %% Click Events for Media Assets & Resources
    click Asset_Audio "https://github.com/watershed117/ushio_noa/tree/main/game/audio"
    click Asset_Images "https://github.com/watershed117/ushio_noa/tree/main/game/images"
    click Asset_Fonts "https://github.com/watershed117/ushio_noa/tree/main/game/fonts"

    %% Click Events for Configuration & External Integration
    click Config_GSV "https://github.com/watershed117/ushio_noa/blob/main/game/audio/gsv/config.json"
    click Config_PythonPkgs "https://github.com/watershed117/ushio_noa/tree/main/game/python-packages"
```
