Spaces:
Sleeping
Sleeping
| title: Mini DungeonGame | |
| 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: | |
| - track:Thousand_Token_Wood | |
| - badge:off_brand | |
| - badge:best_demo | |
| - badge:bonus_quest_champion | |
| - badge:judges'willcard | |
| # ⚔️ 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 | |