{"id":51436906,"url":"https://github.com/dpasca/roguellm","last_synced_at":"2026-07-05T07:30:26.726Z","repository":{"id":259267080,"uuid":"877120677","full_name":"dpasca/roguellm","owner":"dpasca","description":"An LLM-enhanced RPG prototype","archived":false,"fork":false,"pushed_at":"2026-06-05T04:09:53.000Z","size":9657,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2026-06-05T07:09:35.379Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dpasca.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-10-23T05:58:33.000Z","updated_at":"2026-06-05T04:09:56.000Z","dependencies_parsed_at":"2024-10-24T01:25:45.022Z","dependency_job_id":"a98ed9e6-d18b-4944-b4e1-361df44a3752","html_url":"https://github.com/dpasca/roguellm","commit_stats":null,"previous_names":["dpasca/roguellm"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/dpasca/roguellm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dpasca%2Froguellm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dpasca%2Froguellm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dpasca%2Froguellm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dpasca%2Froguellm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dpasca","download_url":"https://codeload.github.com/dpasca/roguellm/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dpasca%2Froguellm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35147199,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-05T02:00:06.290Z","response_time":100,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-05T07:30:26.075Z","updated_at":"2026-07-05T07:30:26.720Z","avatar_url":"https://github.com/dpasca.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RogueLLM\n\nRogueLLM is an experimental roguelike game that combines traditional dungeon-crawling\nmechanics with LLM (Large Language Model) integration for dynamic gameplay experiences.\n\nThe player can request **any kind of setting** for the game to be generated.\nLocations, enemies, and items are all procedurally generated based on the theme requested.\nThe theme request can be as short as a single word (e.g. \"fantasy\"), or much more detailed,\nup to 3,000 characters.\n\nPlay mechanics are currently limited to combat and inventory management.\n\n![Screenshot](docs/roguellm_sshot_01.png)\n\n## Overview\n\nThe game features:\n- **LLM integration** for dynamic narrative and interactions\n- Procedurally generated settings\n- Item and equipment systems\n- Combat mechanics\n- Inventory management\n\n## Installation\n\n### Prerequisites\n- Python 3.10 or higher\n- pip package manager\n\n### Quick Setup (Recommended)\n\nFor new developers, use the automated setup script:\n\n```bash\n# Clone the repository and navigate to it\ngit clone \u003crepository-url\u003e\ncd roguellm\n\n# Run the setup script\n./setup_dev.sh\n```\n\nThis script will:\n- Check Python version compatibility\n- Create a virtual environment\n- Install all dependencies\n- Provide activation instructions\n\n### Manual Setup\n\nIf you prefer to set up manually:\n\n#### 1. Create Virtual Environment\n\n```bash\n# Create virtual environment\npython3 -m venv venv\n\n# Activate it (MacOS/Linux)\nsource venv/bin/activate\n\n# Or on Windows\nvenv\\Scripts\\activate\n```\n\n#### 2. Install Dependencies\n```bash\npip install --upgrade pip\npip install -r requirements.txt\n```\n\n### Development Environment\n\n#### VS Code/Cursor Integration\nThe project includes VS Code settings that will automatically:\n- Detect the virtual environment\n- Set the correct Python interpreter\n- Enable code formatting and linting\n\n#### Activating the Environment\nAfter initial setup, activate the environment using:\n\n```bash\n# Standard activation\nsource venv/bin/activate\n\n# Or use the convenience script\nsource activate.sh\n```\n\n#### Deactivating\n```bash\ndeactivate\n```\n\n## Model Configuration\n\n**⚠️ IMPORTANT**: RogueLLM requires API keys to function. You must configure these before running the application.\n\n### Required Setup\n\n1. **Create a `.env` file** in the project root directory\n2. **Copy the template** from `_env.example` to `.env`\n3. **Add your API keys** to the `.env` file\n\n### Getting API Keys\n\n- **OpenAI**: Get your API key from [OpenAI Platform](https://platform.openai.com/api-keys)\n- **Other providers**: Check their respective documentation\n\n### Basic Configuration\n\nRogueLLM uses `gpt-4o-mini` by default. Minimum required configuration in `.env`:\n\n```bash\n# Required: OpenAI API keys\nLOW_SPEC_MODEL_API_KEY=your_openai_api_key_here\nHIGH_SPEC_MODEL_API_KEY=your_openai_api_key_here\n```\n\n### Advanced Configuration\n\nFor custom models or providers:\n\n```bash\n# Model configuration (optional)\nLOW_SPEC_MODEL_NAME=gemini-2.5-flash-preview-05-20\nHIGH_SPEC_MODEL_NAME=gemini-2.5-flash-preview-05-20\nLOW_SPEC_MODEL_BASE_URL=https://generativelanguage.googleapis.com/v1beta/\nHIGH_SPEC_MODEL_BASE_URL=https://generativelanguage.googleapis.com/v1beta/\nLOW_SPEC_MODEL_API_KEY=\u003cyour_api_key\u003e\nHIGH_SPEC_MODEL_API_KEY=\u003cyour_api_key\u003e\n```\n\n## Search Provider Configuration\n\n*RogueLLM* uses web search to improve newly generated game descriptions.\nSample setup (env variables or `.env` file):\n\n```bash\n# Possible providers: duckduckgo, serpapi\nSEARCH_PROVIDER=serpapi\n# SerpApi key if using SerpApi provider\nSERPAPI_KEY=\u003cyour_api_key\u003e\n```\n\nNotice that *DuckDuckGo* does not require an API key, but it may rate-limit and fail.\n\n## Running the Game\n1. Launch with `./run.sh` for MacOS/Linux or `run.bat` for Windows.\n2. Open browser and navigate to `http://127.0.0.1:8000/`.\n\nSee `game_config.json` and `game_items.json` for more details.\n\n### Seed Dev Worlds\n\nFor repeatable local testing without generating new world definitions, seed stable\ndev worlds:\n\n```bash\nvenv/bin/python tools/ensure_dev_worlds.py\n```\n\nThis creates or refreshes a Piedone world and a small English fantasy world, seeds\ncached language views for dev testing, then prints their World IDs. The local\nQuick Start button prefers the seeded Piedone world when it is present.\n\nFor reproducible local smoke tests, add a debug seed to a dev quick-start URL:\n\n```bash\nhttp://127.0.0.1:8000/?dev_quick=en-piedone\u0026debug_seed=123\n```\n\n`debug_seed` is accepted only from localhost or when `ENABLE_DEBUG_SEED=1` is set.\nNormal launches continue to use a fresh seed.\n\n## Icons generation\n\n```bash\npython tools/generate_icons.py square_icon.png wide-promotional-image.png\n```\n\n## Firebase Analytics Integration (Optional)\n\nThe game includes optional Firebase Analytics integration to track basic usage statistics. This is completely optional and the game works perfectly without it.\n\n### Setup\n\n1. Create a project in [Firebase Console](https://console.firebase.google.com/)\n2. Add a web app to your project\n3. Get your Firebase configuration from the project settings\n4. Add the following variables to your `.env`:\n\n```env\n# Firebase Configuration (Optional)\nFIREBASE_API_KEY=\nFIREBASE_AUTH_DOMAIN=\nFIREBASE_PROJECT_ID=\nFIREBASE_STORAGE_BUCKET=\nFIREBASE_MESSAGING_SENDER_ID=\nFIREBASE_APP_ID=\nFIREBASE_MEASUREMENT_ID=\n```\n\n### What's Being Tracked\n\nWhen Firebase Analytics is configured, the following events are tracked:\n- Page views (landing and game pages)\n- Game start events with selected theme and language\n- Combat events\n- Game completion events with basic stats\n\n### Development\n\nFirebase 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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdpasca%2Froguellm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdpasca%2Froguellm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdpasca%2Froguellm/lists"}