mirror of
https://github.com/Nighthawk42/VDM.git
synced 2026-08-30 04:30:21 +00:00
135 lines
5.7 KiB
Markdown
135 lines
5.7 KiB
Markdown
# 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:
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
# 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):**
|
|
```bash
|
|
uv pip install ".[gpu]" --extra-index-url https://download.pytorch.org/whl/cu121
|
|
```
|
|
|
|
**For CPU-Only Systems:**
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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
|
|
|
|
1. **Connect:** Open your browser to the server's address.
|
|
2. **Login/Register:** Create a persistent player account.
|
|
3. **Join a Room:** Enter a Room ID to join or create a game. The first player becomes the room's permanent owner.
|
|
4. **Start the Game:** The room owner clicks "Start Game" to begin the collaborative setup.
|
|
5. **Declare Actions:** During gameplay, type or speak what your character does or says. Your action is added to the turn queue.
|
|
6. **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.
|
|
7. **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.
|