--- 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

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