# vcherel/local-ai-rpg architecture

> Architecture diagram of the GitHub repository vcherel/local-ai-rpg, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vcherel/local-ai-rpg
- Repository: https://github.com/vcherel/local-ai-rpg

## Overview

##### Project Type and Purpose
- This is a standalone 2D open-world RPG written in Python with a local AI backend. It uses Pygame for rendering and llama-cpp-python to run a quantized LLM entirely on the user’s GPU/CPU. The game logic, world state, AI-driven dialogue and quest generation, and UI rendering all live in a single project, structured in modular packages.

##### File-Structure Analysis
- Top-level:
- assets – image/media for rendering
- src – all Python code
- README.MD, LICENSE, .gitignore
- src/core – low-level utilities and shared services (camera logic, constants, save/load, other helpers)
- src/game – pure game logic: entities (player, NPCs, monsters, items), world map, quest definitions, main game loop
- src/llm – AI-centric services: dialogue manager, queued LLM requests, name generator, AI-driven quest system
- src/ui – rendering and user-interaction: game renderer, conversation windows, menus, loading indicators
- src/main.py – application entry point, initializes subsystems and starts game loop

##### Key README Insights
- Local AI inference (Llama 2.6B quantized)
- No internet calls; all LLM calls go through a local queue to llama-cpp-python
- Real-time conversation and dynamic quest generation
- Uses GPU via CUDA or falls back to CPU

1. Resource Manager
– loads images (assets/), audio, AI model files (models/LFM2-2.6B-Q4_0.gguf)
2. Core Services
– camera.py (view frustum), constants.py, save.py (persistence), utils.py
3. Game Engine
– game/game.py (game loop, event dispatch)
– world.py (map, zones), entities/ (player, NPCs, items, monsters)
– quest.py (static parts), extended by llm/quest_system.py
4. AI Engine
– llm_request_queue.py (FIFO queue for prompts)
– dialogue_manager.py (routing NPC chats)
– quest_system.py (dynamic quest generation)
– name_generator.py (NPC name generation)
– llama-cpp library (external component)
5. UI Layer
– conversation_ui.py (dialog windows)
– loading_indicator.py
– menus/ (main menu, inventory, quest log, context menus)
6. External Dependencies
– pygame
– llama-cpp-python (with optional CUDA)
– Python standard library

1. main.py → initialize Resource Manager, Core Services
2. main.py → initialize Game Engine & UI Layer
3. Game Loop (game/game.py):
- reads input events → dispatch to UI or directly to Game Engine
- updates world/entities → triggers AI requests via Dialogue Manager or Quest System
4. Dialogue Manager / Quest System → enqueue prompt in llm_request_queue
5. llm_request_queue → llama-cpp-python → returns response → back to Dialogue Manager / Quest System
6. AI response → Game Engine (updates NPC state, quest logs) → UI Layer (re-render conversation or quest menu)
7. On save/load → Core save.py reads/writes world and player state to disk

c. Architectural Patterns & Principles
- Layered architecture (Resource → Core → Engine → LLM → UI)
- Separation of Concerns:
- Core utilities are isolated from game logic
- AI logic in a dedicated package, communicating through a request queue
- UI purely reads from game state, never touches AI internals
- Asynchronous / queued processing for AI calls to avoid blocking frame loop
- Modular design: clear package boundaries, easy to swap out LLM or rendering engine

d. Key Technologies
- Python 3.12
- pygame for 2D rendering & input
- llama-cpp-python (optionally with CUDA acceleration)
- Local file I/O for saving, huggingface model artifacts

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Main Entry Point
    Main["src/main.py"]:::external

    %% Resource Manager
    ResourceManager["Resource Manager"]:::blue
    click ResourceManager "https://github.com/vcherel/local-ai-rpg/tree/main/assets/"

    %% Core Services
    subgraph "Core Services"
        CS["src/core/"]:::blue
        Camera["camera.py"]:::blue
        Constants["constants.py"]:::blue
        SaveLoad["save.py"]:::blue
        Utils["utils.py"]:::blue
    end
    click CS "https://github.com/vcherel/local-ai-rpg/tree/main/src/core/"
    click Camera "https://github.com/vcherel/local-ai-rpg/blob/main/src/core/camera.py"
    click Constants "https://github.com/vcherel/local-ai-rpg/blob/main/src/core/constants.py"
    click SaveLoad "https://github.com/vcherel/local-ai-rpg/blob/main/src/core/save.py"
    click Utils "https://github.com/vcherel/local-ai-rpg/blob/main/src/core/utils.py"

    %% Game Engine
    subgraph "Game Engine" 
        GE["src/game/"]:::green
        GameLoop["game.py"]:::green
        WorldMap["world.py"]:::green
        QuestStatic["quest.py"]:::green
        subgraph "Entities"
            EntitiesDir["src/game/entities/"]:::green
            Player["player.py"]:::green
            NPCs["npcs.py"]:::green
            Monsters["monsters.py"]:::green
            Items["items.py"]:::green
            AllEntities["entities.py"]:::green
        end
    end
    click GE "https://github.com/vcherel/local-ai-rpg/tree/main/src/game/"
    click GameLoop "https://github.com/vcherel/local-ai-rpg/blob/main/src/game/game.py"
    click WorldMap "https://github.com/vcherel/local-ai-rpg/blob/main/src/game/world.py"
    click QuestStatic "https://github.com/vcherel/local-ai-rpg/blob/main/src/game/quest.py"
    click EntitiesDir "https://github.com/vcherel/local-ai-rpg/tree/main/src/game/entities/"
    click Player "https://github.com/vcherel/local-ai-rpg/blob/main/src/game/entities/player.py"
    click NPCs "https://github.com/vcherel/local-ai-rpg/blob/main/src/game/entities/npcs.py"
    click Monsters "https://github.com/vcherel/local-ai-rpg/blob/main/src/game/entities/monsters.py"
    click Items "https://github.com/vcherel/local-ai-rpg/blob/main/src/game/entities/items.py"
    click AllEntities "https://github.com/vcherel/local-ai-rpg/blob/main/src/game/entities/entities.py"

    %% AI Engine
    subgraph "AI Engine"
        AI["src/llm/"]:::orange
        Queue["llm_request_queue.py"]:::orange
        Dialogue["dialogue_manager.py"]:::orange
        QuestDyn["quest_system.py"]:::orange
        NameGen["name_generator.py"]:::orange
        LlamaCPP["llama-cpp-python"]:::external
    end
    click AI "https://github.com/vcherel/local-ai-rpg/tree/main/src/llm/"
    click Queue "https://github.com/vcherel/local-ai-rpg/blob/main/src/llm/llm_request_queue.py"
    click Dialogue "https://github.com/vcherel/local-ai-rpg/blob/main/src/llm/dialogue_manager.py"
    click QuestDyn "https://github.com/vcherel/local-ai-rpg/blob/main/src/llm/quest_system.py"
    click NameGen "https://github.com/vcherel/local-ai-rpg/blob/main/src/llm/name_generator.py"

    %% UI Layer
    subgraph "UI Layer"
        UI["src/ui/"]:::purple
        Renderer["game_renderer.py"]:::purple
        Conversation["conversation_ui.py"]:::purple
        Loading["loading_indicator.py"]:::purple
        subgraph "Menus"
            MenusDir["src/ui/menus/"]:::purple
            BaseMenu["base_menu.py"]:::purple
            MainMenu["main_menu.py"]:::purple
            InvMenu["inventory_menu.py"]:::purple
            QuestMenu["quest_menu.py"]:::purple
            ContextMenu["context_menu.py"]:::purple
        end
    end
    click UI "https://github.com/vcherel/local-ai-rpg/tree/main/src/ui/"
    click Renderer "https://github.com/vcherel/local-ai-rpg/blob/main/src/ui/game_renderer.py"
    click Conversation "https://github.com/vcherel/local-ai-rpg/blob/main/src/ui/conversation_ui.py"
    click Loading "https://github.com/vcherel/local-ai-rpg/blob/main/src/ui/loading_indicator.py"
    click MenusDir "https://github.com/vcherel/local-ai-rpg/tree/main/src/ui/menus/"
    click BaseMenu "https://github.com/vcherel/local-ai-rpg/blob/main/src/ui/menus/base_menu.py"
    click MainMenu "https://github.com/vcherel/local-ai-rpg/blob/main/src/ui/menus/main_menu.py"
    click InvMenu "https://github.com/vcherel/local-ai-rpg/blob/main/src/ui/menus/inventory_menu.py"
    click QuestMenu "https://github.com/vcherel/local-ai-rpg/blob/main/src/ui/menus/quest_menu.py"
    click ContextMenu "https://github.com/vcherel/local-ai-rpg/blob/main/src/ui/menus/context_menu.py"

    %% Data Storage for Models & Save Files
    Models["Model & Save Files"]:::storage

    %% External Dependencies
    Pygame["pygame"]:::external
    PythonStd["Python Std Lib"]:::external

    %% Initialization Flows
    Main -->|"init Resource Manager"| ResourceManager
    Main -->|"init Core Services"| CS
    Main -->|"init Game Engine & UI"| GE
    Main --> Main -->|"init Game Engine & UI"| UI

    %% Core Shared
    CS --> GameLoop
    CS --> Renderer

    %% Resource Loading
    ResourceManager --> Assets[("assets/")]:::storage
    ResourceManager --> Models

    %% Game Loop Flows
    GameLoop -->|"reads input"| UI
    GameLoop -->|"dispatch events"| GE
    GE -->|"update world/entities"| WorldMap
    WorldMap --> EntitiesDir
    GameLoop -->|"trigger AI"| Dialogue
    GameLoop --> QuestDyn

    %% AI Request Pipeline
    Dialogue -->|"enqueue prompt"| Queue
    QuestDyn -->|"enqueue prompt"| Queue
    Queue -->|"send request"| LlamaCPP
    LlamaCPP -->|"AI response"| Queue
    Queue --> Dialogue
    Queue --> QuestDyn

    %% AI back to Game and UI
    Dialogue -->|"update NPC state"| GE
    QuestDyn -->|"update quests"| GE
    GE --> Renderer
    GE --> Conversation
    GE --> QuestMenu

    %% Save/Load
    SaveLoad -->|"read/write state"| Models

    %% External Deps
    GameLoop --> Pygame
    LlamaCPP --> PythonStd

    %% Styles and Classes
    classDef blue fill:#D0E8FF,stroke:#005B96,color:#003F6B;
    classDef green fill:#DFF2D8,stroke:#4C8C2A,color:#3A5D11;
    classDef orange fill:#FFE2B3,stroke:#FF8C00,color:#A35200;
    classDef purple fill:#EAD7FF,stroke:#8C3BCC,color:#57008A;
    classDef grey fill:#EEEEEE,stroke:#AAAAAA,color:#555555;
    classDef external fill:#F5F5F5,stroke:#888888,color:#333333,stroke-dasharray: 5 5;
    classDef storage fill:#FFF2CC,stroke:#D6B656,color:#7A5A00;
```
