README.md

metadata

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

pip install -r requirements.txt

Set Hugging Face token

Create an environment variable:

export HF_TOKEN="your_token_here"

or add it through Hugging Face Space Secrets.

Run

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