https://github.com/dpasca/roguellm
An LLM-enhanced RPG prototype
https://github.com/dpasca/roguellm
Last synced: about 11 hours ago
JSON representation
An LLM-enhanced RPG prototype
- Host: GitHub
- URL: https://github.com/dpasca/roguellm
- Owner: dpasca
- Created: 2024-10-23T05:58:33.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2026-06-05T04:09:53.000Z (about 1 month ago)
- Last Synced: 2026-06-05T07:09:35.379Z (about 1 month ago)
- Language: Python
- Homepage:
- Size: 9.21 MB
- Stars: 5
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# RogueLLM
RogueLLM is an experimental roguelike game that combines traditional dungeon-crawling
mechanics with LLM (Large Language Model) integration for dynamic gameplay experiences.
The player can request **any kind of setting** for the game to be generated.
Locations, enemies, and items are all procedurally generated based on the theme requested.
The theme request can be as short as a single word (e.g. "fantasy"), or much more detailed,
up to 3,000 characters.
Play mechanics are currently limited to combat and inventory management.
## Overview
The game features:
- **LLM integration** for dynamic narrative and interactions
- Procedurally generated settings
- Item and equipment systems
- Combat mechanics
- Inventory management
## Installation
### Prerequisites
- Python 3.10 or higher
- pip package manager
### Quick Setup (Recommended)
For new developers, use the automated setup script:
```bash
# Clone the repository and navigate to it
git clone
cd roguellm
# Run the setup script
./setup_dev.sh
```
This script will:
- Check Python version compatibility
- Create a virtual environment
- Install all dependencies
- Provide activation instructions
### Manual Setup
If you prefer to set up manually:
#### 1. Create Virtual Environment
```bash
# Create virtual environment
python3 -m venv venv
# Activate it (MacOS/Linux)
source venv/bin/activate
# Or on Windows
venv\Scripts\activate
```
#### 2. Install Dependencies
```bash
pip install --upgrade pip
pip install -r requirements.txt
```
### Development Environment
#### VS Code/Cursor Integration
The project includes VS Code settings that will automatically:
- Detect the virtual environment
- Set the correct Python interpreter
- Enable code formatting and linting
#### Activating the Environment
After initial setup, activate the environment using:
```bash
# Standard activation
source venv/bin/activate
# Or use the convenience script
source activate.sh
```
#### Deactivating
```bash
deactivate
```
## Model Configuration
**⚠️ IMPORTANT**: RogueLLM requires API keys to function. You must configure these before running the application.
### Required Setup
1. **Create a `.env` file** in the project root directory
2. **Copy the template** from `_env.example` to `.env`
3. **Add your API keys** to the `.env` file
### Getting API Keys
- **OpenAI**: Get your API key from [OpenAI Platform](https://platform.openai.com/api-keys)
- **Other providers**: Check their respective documentation
### Basic Configuration
RogueLLM uses `gpt-4o-mini` by default. Minimum required configuration in `.env`:
```bash
# Required: OpenAI API keys
LOW_SPEC_MODEL_API_KEY=your_openai_api_key_here
HIGH_SPEC_MODEL_API_KEY=your_openai_api_key_here
```
### Advanced Configuration
For custom models or providers:
```bash
# Model configuration (optional)
LOW_SPEC_MODEL_NAME=gemini-2.5-flash-preview-05-20
HIGH_SPEC_MODEL_NAME=gemini-2.5-flash-preview-05-20
LOW_SPEC_MODEL_BASE_URL=https://generativelanguage.googleapis.com/v1beta/
HIGH_SPEC_MODEL_BASE_URL=https://generativelanguage.googleapis.com/v1beta/
LOW_SPEC_MODEL_API_KEY=
HIGH_SPEC_MODEL_API_KEY=
```
## Search Provider Configuration
*RogueLLM* uses web search to improve newly generated game descriptions.
Sample setup (env variables or `.env` file):
```bash
# Possible providers: duckduckgo, serpapi
SEARCH_PROVIDER=serpapi
# SerpApi key if using SerpApi provider
SERPAPI_KEY=
```
Notice that *DuckDuckGo* does not require an API key, but it may rate-limit and fail.
## Running the Game
1. Launch with `./run.sh` for MacOS/Linux or `run.bat` for Windows.
2. Open browser and navigate to `http://127.0.0.1:8000/`.
See `game_config.json` and `game_items.json` for more details.
### Seed Dev Worlds
For repeatable local testing without generating new world definitions, seed stable
dev worlds:
```bash
venv/bin/python tools/ensure_dev_worlds.py
```
This creates or refreshes a Piedone world and a small English fantasy world, seeds
cached language views for dev testing, then prints their World IDs. The local
Quick Start button prefers the seeded Piedone world when it is present.
For reproducible local smoke tests, add a debug seed to a dev quick-start URL:
```bash
http://127.0.0.1:8000/?dev_quick=en-piedone&debug_seed=123
```
`debug_seed` is accepted only from localhost or when `ENABLE_DEBUG_SEED=1` is set.
Normal launches continue to use a fresh seed.
## Icons generation
```bash
python tools/generate_icons.py square_icon.png wide-promotional-image.png
```
## Firebase Analytics Integration (Optional)
The game includes optional Firebase Analytics integration to track basic usage statistics. This is completely optional and the game works perfectly without it.
### Setup
1. Create a project in [Firebase Console](https://console.firebase.google.com/)
2. Add a web app to your project
3. Get your Firebase configuration from the project settings
4. Add the following variables to your `.env`:
```env
# Firebase Configuration (Optional)
FIREBASE_API_KEY=
FIREBASE_AUTH_DOMAIN=
FIREBASE_PROJECT_ID=
FIREBASE_STORAGE_BUCKET=
FIREBASE_MESSAGING_SENDER_ID=
FIREBASE_APP_ID=
FIREBASE_MEASUREMENT_ID=
```
### What's Being Tracked
When Firebase Analytics is configured, the following events are tracked:
- Page views (landing and game pages)
- Game start events with selected theme and language
- Combat events
- Game completion events with basic stats
### Development
Firebase Analytics doesn't track events from localhost by default, but debug mode is automatically enabled in development environments. Check your browser's console to see if events are being tracked correctly.