README.md

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