| --- |
| title: Mini DungeonRPG |
| emoji: 🌖 |
| colorFrom: green |
| colorTo: red |
| sdk: gradio |
| sdk_version: 6.18.0 |
| python_version: '3.11' |
| app_file: app.py |
| pinned: false |
| license: mit |
| hf_oauth: true |
| short_description: This is an LLM Interactive Dungeon RPG |
| social_media: https://youtu.be/BBRy5JsOpSI |
| tags: |
| - badge:off_brand |
| - badge:best_demo |
| - badge:bonus_quest_champion |
| - badge:judges'willcard |
| - track:wood |
| - achievement:offbrand |
| - achievement:sharing |
| - achievement:fieldnotes |
|
|
| --- |
| |
| # ⚔️ Mini Dungeon Adventure |
|
|
| <p align='center'> |
| <img src="./pics/image.png" width="650" height="480"> |
| </p> |
| |
| An AI-powered text-based fantasy RPG built with **Gradio** and **Hugging Face Inference API**. |
|
|
| The player explores a dangerous dungeon by typing natural language actions. Instead of selecting predefined choices, an LLM interprets the player's response and maps it to the appropriate game action. |
|
|
| You can find the demo video here: https://youtu.be/BBRy5JsOpSI |
|
|
| --- |
|
|
| ## 🎮 Overview |
|
|
| **Mini Dungeon Adventure** is a lightweight interactive RPG where: |
|
|
| - The player types any action they want |
| - The LLM understands the player's intent |
| - The game engine updates the world state |
| - The story progresses through connected events |
| - The adventure ends depending on survival, resources, and decisions |
|
|
| Example: |
|
|
| ``` |
| Player : I raise my sword and attack the guardian. |
| |
| LLM : Action -> PHYSICAL_ATTACK |
| |
| GAME : HP-20, Move to the next state |
| ``` |
|
|
|
|
| The goal is to create the feeling of an open-ended adventure while maintaining a controlled narrative structure. |
|
|
| --- |
|
|
| ## ✨ Features |
|
|
| ### 🧠 Natural Language Action System |
|
|
| Players are not limited to buttons. |
|
|
| Possible inputs: |
|
|
| ``` |
| "Attack the monster" |
| "Try to negotiate" |
| "Use my magic" |
| "Run away" |
| "Search the room" |
| ``` |
|
|
|
|
| The LLM classifies the intent and connects it to the correct game transition. |
|
|
| --- |
|
|
| ### 🗺️ Branching Story Graph |
|
|
| The adventure consists of multiple connected events. For example, |
|
|
| ``` |
| Entrance |
| | |
| ------------------- |
| | | | |
| Battle Magic Run Away |
| ``` |
|
|
| The graph is controlled by the game engine rather than generated freely by the LLM. |
|
|
| This provides: |
|
|
| - Consistent story progression |
| - Predictable game states |
| - Replayable paths |
|
|
| Play it and explore differnet endings. |
|
|
| ## 🐉 Story |
|
|
| The player enters an ancient dungeon beneath a volcanic mountain. |
|
|
| Deep inside lies an ancient dragon. |
|
|
| However, the dragon is not simply a monster. |
|
|
| Long ago, the dragon discovered a dangerous magical core beneath the mountain. If the energy became unstable, the volcano would erupt and destroy the kingdom. |
|
|
| The dragon remained underground to: |
|
|
| - Contain the volcano |
| - Absorb unstable energy |
| - Prevent disaster |
|
|
| Humans misunderstood the dragon's purpose and believed it was the source of the danger. |
|
|
| The player must decide: |
|
|
| - Fight the dragon |
| - Escape with treasure |
| - Discover the truth |
|
|
| --- |
|
|
| ## 🎲 Game Mechanics |
|
|
| The player has three main attributes: |
|
|
| | Attribute | Description | |
| |---|---| |
| | ❤️ HP | Health points. Reaches 0 → defeat | |
| | 🔮 MP | Mana points. Used for magic actions | |
| | 🪙 Coin | Currency collected during the adventure | |
|
|
| ``` |
| HP: 75 |
| MP: 40 |
| Coin: 120 |
| ``` |
| --- |
|
|
| ## 🧩 Architecture |
|
|
| The system is divided into three parts: |
|
|
| ``` |
| Player Input |
| | |
| v |
| LLM Intent Classifier |
| | |
| v |
| Game Engine |
| | |
| v |
| Next Story Event |
| ``` |
|
|
|
|
| --- |
|
|
| ### 1. LLM Layer |
|
|
| The model: **Qwen/Qwen2.5-7B-Instruct**, used to classify the player's response. |
|
|
| ### 2. Game Engine |
|
|
| The engine handles: |
|
|
| - HP changes |
| - MP consumption |
| - Coin rewards |
| - Event transitions |
| - Ending conditions |
|
|
| The LLM does **not** directly control game state. |
|
|
| ### 3. Event System |
|
|
| Each event contains: |
|
|
| ``` |
| Event: |
| title |
| description |
| images |
| possible_actions |
| next_events |
| ``` |
|
|
| ## 🛠️ Tech Stack |
|
|
| | Technology | Purpose | |
| | -------------------------- | --------------------- | |
| | Python | Core implementation | |
| | Gradio | Web interface | |
| | Hugging Face Inference API | LLM inference | |
| | Qwen2.5 | Action understanding | |
| | Pillow | Image processing | |
| | MoviePy | Adventure recap video | |
|
|
|
|
| ## 🚀 Running Locally |
|
|
| ### Install dependencies |
|
|
| ```bash |
| pip install -r requirements.txt |
| ``` |
|
|
| ### Set Hugging Face token |
|
|
| Create an environment variable: |
|
|
| ```bash |
| export HF_TOKEN="your_token_here" |
| ``` |
|
|
| or add it through Hugging Face Space Secrets. |
|
|
| ### Run |
|
|
| ```bash |
| python app.py or main.py |
| ``` |
|
|
| ## 🔮 Future Improvements |
|
|
| Potential extensions: |
|
|
| ``` |
| - More dungeon chapters |
| - Inventory system |
| - Enemy combat simulation |
| - Character classes |
| - Persistent player save system |
| - More advanced LLM action planning |
| ``` |
|
|
| ## 📌 Design Philosophy |
|
|
| This project explores a hybrid approach: |
| ``` |
| Use AI for understanding player creativity, but use traditional game logic for control. |
| ``` |
| The LLM provides flexibility. |
|
|
| The game engine provides reliability. |
|
|
| Together they create a more interactive text adventure experience. |
|
|
| Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference |
|
|
