How vcherel/local-ai-rpg works
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