README.md

---
title: dungeon-smasher-lite
emoji: 👁
colorFrom: yellow
colorTo: pink
sdk: gradio
sdk_version: 5.35.0
app_file: app.py
pinned: true
thumbnail: >-
  https://cdn-uploads.huggingface.co/production/uploads/683d2ec2540df93aae2532f4/Xagf2XzjnOEUZB-a1ofXZ.png
license: afl-3.0
short_description: Create PCs and NPCs on the fly.
---

# 🧠 Dungeon Smasher

*An Agentic Toolkit for Dynamic RPG Storytelling*  
---

## 🌟 Overview

**Dungeon Smasher** is an experimental AI toolkit for building intelligent, reactive RPG environments.  
This modular agent demo showcases three core systems:

- 🎭 **DM Assistant**
- 👥 **NPC Generator**
- 🐉 **Character Creator**

Each module uses LLM reasoning and symbolic world logic to help GMs and players co-create immersive adventures—no prep required.

---

## ⚙️ Core Features

| Feature                | Description                                                                                   |
|------------------------|-----------------------------------------------------------------------------------------------|
| 🎭 AI Dungeon Master   | Orchestrates scenes, conflicts, and roleplay hooks with dramatic tone                         |
| 👥 NPC Generator       | Builds named characters with secrets, flaws, goals, and voice                                 |
| 🗺️ World Builder      | Assembles regions, ruins, factions, and mythic histories                                      |
| 💰 Loot Master         | Designs magical items that reflect player actions and narrative symbols                       |
| 🐉 Character Creator   | Generates heroes with stats, backstories, class synergy, and emotional arcs                   |

---

## 🧪 Demo Capabilities

- ✅ Campaign, PC, NPC creation with image generation  
- ✅ Modular agent logic with memory and context threading  
- ✅ Gradio-based interactive frontend for testing each system  
- ✅ Rich character builder with storytelling-first logic

**Explore the toolkit using these suggested flows:**

### 👥 NPC Generator
> *Prompt with:* `"a cursed knight guarding forgotten ruins"`  
> *Get a complex NPC with motives, secrets, and drama potential.*

### 🐉 Character Creator
> *Prompt with:* `"A storm sorcerer who fears their own power"`  
> *Returns stat blocks, class alignment, flaws, and heroic potential.*

---

## 🛠️ Technologies

- **Gradio 5.33.1** — Live demo interface
- **OpenAI GPT-4** — Agent reasoning and generation
- **Python (modular)** — Custom agent scaffolding and game logic

---

**Or view the live app at:**  
🌐 [https://huggingface.co/spaces/ghost-logic/dungeon-smasher-lite]