# AI RPG - Text Adventure Game

An AI-powered text-based RPG with persistent context management, character progression, and immersive storytelling.

## 🎮 Features

### Core Gameplay
- **AI Game Master** - Powered by local LLM (LM Studio) for dynamic storytelling
- **Persistent Context** - Each session maintains its own characters, locations, inventory, and story
- **Character System** - Full RPG stats, abilities, and progression
- **Journal System** - Automatic story tracking with summaries and key events

### Character Classes
- ⚔️ **Warrior** - Master of combat with high Strength and Constitution
- 🔮 **Mage** - Wielder of arcane magic with powerful Intelligence
- 🗡️ **Rogue** - Cunning specialist with exceptional Dexterity
- ✨ **Cleric** - Holy warrior blessed with divine Wisdom

### Adventure Templates
- 🐉 **The Dragon's Lair** - Classic fantasy dragon slaying quest
- 👻 **The Haunted Manor** - Gothic horror mystery investigation
- 🗺️ **The Lost City** - Pulp adventure exploration
- 📝 **Custom Adventure** - Create your own story from scratch

### Quick Commands
- `/look` - Describe surroundings
- `/inventory` or `/i` - Show inventory
- `/status` or `/sheet` - Open character sheet
- `/examine [thing]` - Inspect something closely
- `/talk [name]` - Start conversation
- `/rest` - Rest and recover
- `/roll [dice]` - Roll dice (d4, d6, d8, d10, d12, d20, d100)
- `/attack` - Attack enemy
- `/defend` - Take defensive action
- `/flee` - Try to escape
- `/help` - Show all commands

### Action Bar
Quick access buttons for common actions:
- 👁️ Look - Survey your surroundings
- 🎒 Inventory - Check your items
- 📊 Status - View character stats
- 💬 Talk - Engage in dialogue
- 🔍 Examine - Inspect closely
- 🏕️ Rest - Recover HP/MP
- 🎲 Dice Roller - Roll for skill checks

## 🚀 Getting Started

### Prerequisites
- Node.js 16+ installed
- LM Studio running locally on port 1234

### Installation

1. Install dependencies:
```bash
npm run install:all
```

2. Start LM Studio:
   - Download from https://lmstudio.ai/
   - Load a compatible model (recommended: Mistral, Llama, or similar)
   - Start the local server on port 1234

3. Run the application:
```bash
npm start
```

This starts both the server (port 3001) and client (port 5173).

4. Open your browser to `http://localhost:5173`

## 🎯 How to Play

1. **Create Your Character**
   - Enter a name for your hero
   - Choose a class (Warrior, Mage, Rogue, or Cleric)
   - Select an adventure template or create custom

2. **Begin Your Adventure**
   - Read the opening narration
   - Type actions in natural language
   - Use quick action buttons for common commands

3. **Track Your Progress**
   - Journal tab shows story summary and key events
   - Characters tab tracks NPCs you meet
   - Inventory tab shows your items
   - Quests tab displays active objectives

4. **Combat & Challenges**
   - Action bar changes during combat
   - Roll dice for skill checks
   - Use abilities and items strategically

## 📁 Data Storage

All session data is stored in `/data/sessions/`:
- Each session is a single JSON file
- Contains: messages, character, context, journal
- Sessions are completely isolated from each other
- Safe to delete individual sessions

## 🛠️ Development

### Project Structure
```
AiRPG/
├── client/              # React frontend
│   ├── src/
│   │   ├── components/  # UI components
│   │   ├── data/        # Game data (templates, classes)
│   │   ├── App.jsx      # Main app component
│   │   └── index.css    # Fantasy theme styles
│   └── index.html
├── server/
│   └── index.js         # Express API server
├── data/
│   └── sessions/        # Session storage
└── package.json
```

### Available Scripts
- `npm start` - Run both server and client
- `npm run server` - Run server only (port 3001)
- `npm run client` - Run client only (port 5173)
- `npm run install:all` - Install all dependencies

## 🎨 Theme

The game features a dark fantasy aesthetic with:
- Mystical animated backgrounds
- Golden accents and glowing effects
- Floating particles and fog
- Ornate UI elements
- Responsive action bars
- Character sheets with stat tracking

## 📝 Tips

- **Save frequently** - Sessions auto-save but you can create multiple
- **Read the journal** - It tracks important story beats
- **Use slash commands** - Faster than typing full sentences
- **Check your sheet** - Know your stats for skill checks
- **Experiment** - The AI responds to creative actions

## 🐛 Troubleshooting

**Can't connect to server:**
- Make sure LM Studio is running on port 1234
- Check that the server is running (`npm run server`)

**Context not updating:**
- The AI extracts context automatically
- You can manually add items/characters via commands

**Build errors:**
- Run `npm run install:all` to ensure dependencies are installed
- Clear node_modules and reinstall if needed

## 📄 License

ISC

---

**Forge your legend, brave adventurer! 🐉⚔️**
