Nighthawk/VDM

Fork 0

mirror of https://github.com/Nighthawk42/VDM.git synced 2026-08-30 04:30:21 +00:00

Files

T

Nighthawk ec66e77cac Moved to uv managed venv

2025-09-05 08:09:03 -04:00

5.7 KiB

Raw Blame History

VDM - The Virtual Dungeon Master

VDM is a multiplayer, AI-driven storytelling game designed for immersive, collaborative role-playing. It combines a powerful, locally-run backend with a clean, modular web interface, allowing you and your friends to create and experience epic adventures narrated by a sophisticated AI Game Master.

The project is built with a focus on stability and cutting-edge features, leveraging modern, high-performance tools to create a robust foundation that is easy to understand, maintain, and extend.

✨ Features

Core Gameplay

AI-Powered Game Master: A sophisticated LLM acts as the storyteller, reacting to player actions, describing the world, and narrating events.
Real-Time Multiplayer: Join a room with friends from anywhere. The game state is synchronized in real-time for a seamless collaborative experience.
Turn-Based System: A structured turn system allows players to declare their actions, which are then submitted to the GM as a single turn for resolution.
Permanent Room Ownership: The first player to create a room becomes its permanent owner, ensuring they always have host controls when they rejoin.

Advanced AI Memory

State-of-the-Art RAG Pipeline: The AI has a true long-term memory, powered by Google's EmbeddingGemma model for top-tier embeddings and the Chonkie library for intelligent semantic chunking.
Local Vector Store: All memories are stored locally in a ChromaDB vector database.
Manual Memory Control: Players can use the /remember command to ensure critical facts are permanently stored in the AI's memory.

Immersive Experience

High-Quality Voice Narration: The GM's responses are brought to life with server-side Text-to-Speech using the kokoro library.
Speech-to-Text Input: A "Hold to Talk" microphone button allows players to speak their actions instead of typing.
Markdown Rendering: Chat messages are rendered with Markdown for rich text formatting (italics, bold).

Modern UI/UX

Clean & Responsive Interface: A modern single-page application that works on any device.
Light/Dark Modes: A persistent theme toggle for user comfort.
Modular Frontend: The JavaScript is broken down into small, maintainable modules.
Visual Turn Indicator: See at a glance which players have submitted their action for the current turn.

Robust Backend

Modern Python Packaging: Uses a pyproject.toml file and a src layout, following the latest Python standards.
Pluggable AI Backends: Easily switch between different LLM providers (LM Studio, Ollama, OpenRouter).
Secure User Accounts: Player accounts are stored with hashed passwords in a dedicated SQLite database.
Persistent Sessions: User logins survive server restarts for a seamless reconnection experience.

🚀 Getting Started

Follow these steps to get your VDM server up and running.

Prerequisites

Python 3.11 or higher installed on your system.
uv: A fast Python package manager. If you don't have it, run:
```
pip install uv
```

1. Setup and Environment Activation

Open your terminal and run the following commands from the directory where you want to store the project.

# 1. Clone the project repository
git clone https://github.com/Nighthawk42/VDM.git
cd VDM

# 2. Create a seeded virtual environment with Python 3.11 (required step)
uv venv --seed --python 3.11

# 3. Activate the new environment
# On Windows:
.venv\Scripts\activate
# On macOS / Linux:
# source .venv/bin/activate

2. Install Dependencies

This project can be run on a CPU, but an NVIDIA GPU is highly recommended for the best performance. Choose one of the following installation options.

For NVIDIA GPU Systems (Recommended):

uv pip install ".[gpu]" --extra-index-url https://download.pytorch.org/whl/cu121

For CPU-Only Systems:

uv pip install .

Note: This step will download large AI models for embeddings and TTS, which may take some time.

3. Configure the VDM

Environment Variables: Copy .env.example to .env and fill in any necessary API keys or change the default URLs for your local LLM providers.
Main Configuration: Open settings.yml to configure the core behavior, especially the llm and memory sections.
Prompts (Optional): Edit prompts.yml to change the GM's personality.

4. Launch the Server!

Simply run the launch script.

uv run uvicorn vdm_server.main:app --reload --reload-dir ./src/vdm_server --reload-dir ./web --host 127.0.0.1 --port 8000

The server will be running at http://127.0.0.1:8000.

🎮 How to Play

Connect: Open your browser to the server's address.
Login/Register: Create a persistent player account.
Join a Room: Enter a Room ID to join or create a game. The first player becomes the room's permanent owner.
Start the Game: The room owner clicks "Start Game" to begin the collaborative setup.
Declare Actions: During gameplay, type or speak what your character does or says. Your action is added to the turn queue.
Submit the Turn: When all players are ready, anyone can click the "Continue Story" button (or type /next) to submit the turn to the GM.
Enjoy the Story: The GM will narrate the outcome of your combined actions.

⌨️ Slash Commands

/roll [dice]: Rolls dice (e.g., /roll 2d6+3). Defaults to 1d20.
/ooc [message]: Sends an out-of-character message to other players.
/remember [fact]: Saves a critical fact to the GM's long-term memory.
/save: Saves the current game session.
/next: Submits the current turn's actions to the GM.

5.7 KiB Raw Blame History