storyteller/docs/features/DEMO_SESSION.md

# 🎲 Demo Session - "The Cursed Tavern"

**Pre-configured test session for quick development and testing**

---

## Quick Access

When you start the server, a demo session is automatically created with:

- **Session ID:** `demo-session-001`
- **Session Name:** "The Cursed Tavern"
- **2 Pre-configured Characters**
- **Starting Scene & Adventure Hook**

---

## How to Use

### From the Home Page (Easiest)

Three big colorful buttons appear at the top:

1. **🎲 Join as Storyteller** - Opens storyteller dashboard
2. **⚔️ Play as Bargin (Dwarf Warrior)** - Opens character view as Bargin
3. **🏹 Play as Willow (Elf Ranger)** - Opens character view as Willow

Just click and you're in!

### Manual Access

If you want to manually enter the session:

**As Storyteller:**
- Session ID: `demo-session-001`

**As Bargin:**
- Session ID: `demo-session-001`
- Character ID: `char-bargin-001`

**As Willow:**
- Session ID: `demo-session-001`
- Character ID: `char-willow-002`

---

## Characters

### Bargin Ironforge ⚔️

**Race:** Dwarf  
**Class:** Warrior  
**Personality:** Brave but reckless. Loves a good fight and a strong ale. Quick to anger but fiercely loyal to companions.

**Description:**
A stout dwarf warrior with a braided red beard and battle-scarred armor. Carries a massive war axe named 'Grudgekeeper'.

**Character ID:** `char-bargin-001`  
**LLM Model:** GPT-3.5 Turbo

---

### Willow Moonwhisper 🏹

**Race:** Elf  
**Class:** Ranger  
**Personality:** Cautious and observant. Prefers to scout ahead and avoid unnecessary conflict. Has an affinity for nature and animals.

**Description:**
An elven ranger with silver hair and piercing green eyes. Moves silently through shadows, bow always at the ready.

**Character ID:** `char-willow-002`  
**LLM Model:** GPT-3.5 Turbo

---

## The Adventure

### Scenario: The Cursed Tavern

The village of Millhaven has a problem. The old Rusty Flagon tavern, once a cheerful gathering place, has become a source of terror. Locals report:

- **Ghostly figures** moving through the windows
- **Unearthly screams** echoing from within
- **Eerie green light** flickering after dark
- Strange whispers that drive people mad

The village elder has hired adventurers to investigate and put an end to the disturbances.

### Starting Scene

```
You stand outside the weathered doors of the Rusty Flagon tavern. 
Strange whispers echo from within, and the windows flicker with an 
eerie green light. The townspeople warned you about this place, 
but the reward for investigating is too good to pass up.
```

### Initial Message (Both Characters)

When the characters first join, they see:

```
Welcome to the Cursed Tavern adventure! You've been hired by the 
village elder to investigate strange happenings at the old tavern. 
Locals report seeing ghostly figures and hearing unearthly screams. 
Your mission: discover what's causing the disturbances and put an 
end to it. What would you like to do?
```

---

## Testing Scenarios

### Test the Message System

1. **Private Messages:**
   - Bargin: "I quietly check the door for traps"
   - Willow: "I scan the area for signs of danger"
   - Storyteller should see both privately

2. **Public Messages:**
   - Bargin: "I kick open the door!" (public)
   - Willow should see this action
   - Storyteller sees it too

3. **Mixed Messages:**
   - Bargin (public): "I step inside boldly"
   - Bargin (private): "I'm actually terrified but don't want Willow to know"
   - Willow sees: "I step inside boldly"
   - Storyteller sees: Both parts

### Test Context-Aware Responses

1. Select both Bargin and Willow in storyteller dashboard
2. Click "Select All Pending"
3. Choose "Individual Responses"
4. Generate context-aware response
5. Verify each character receives their personalized response

### Test AI Suggestions

1. As storyteller, view Bargin's conversation
2. Click "✨ AI Suggest"
3. Review generated suggestion
4. Edit and send

---

## Development Benefits

This demo session eliminates the need to:

- Create a new session every time you restart the server
- Manually create character profiles
- Enter character descriptions and personalities
- Type in session IDs repeatedly
- Set up test scenarios

Just restart the server and click one button to test!

---

## Server Startup Output

When you start the server with `bash start.sh`, you'll see:

```
============================================================
🎲 DEMO SESSION CREATED!
============================================================
Session ID: demo-session-001
Session Name: The Cursed Tavern

Characters:
  1. Bargin Ironforge (ID: char-bargin-001)
     A stout dwarf warrior with a braided red beard and battle-scarred armor...

  2. Willow Moonwhisper (ID: char-willow-002)
     An elven ranger with silver hair and piercing green eyes...

Scenario: The Cursed Tavern
Scene: You stand outside the weathered doors of the Rusty Flagon tavern...

============================================================
To join as Storyteller: Use session ID 'demo-session-001'
To join as Bargin: Use session ID 'demo-session-001' + character ID 'char-bargin-001'
To join as Willow: Use session ID 'demo-session-001' + character ID 'char-willow-002'
============================================================
```

---

## Customization

Want to modify the demo session? Edit `create_demo_session()` in `main.py`:

### Change Characters

```python
# Modify character attributes
bargin = Character(
    name="Your Character Name",
    description="Your description",
    personality="Your personality",
    llm_model="gpt-4",  # Change model
    # ...
)
```

### Change Scenario

```python
demo_session = GameSession(
    name="Your Adventure Name",
    current_scene="Your starting scene...",
    scene_history=["Your backstory..."]
)
```

### Add More Characters

```python
# Create a third character
third_char = Character(...)
demo_session.characters[third_char.id] = third_char
```

### Change Session ID

```python
demo_session_id = "my-custom-id"
```

---

## Disabling Demo Session

If you want to disable auto-creation of the demo session, comment out this line in `main.py`:

```python
if __name__ == "__main__":
    import uvicorn
    
    # create_demo_session()  # Comment this out
    
    uvicorn.run(app, host="0.0.0.0", port=8000)
```

---

## Technical Details

### Implementation

The demo session is created in the `create_demo_session()` function in `main.py`, which:

1. Creates a `GameSession` object
2. Creates two `Character` objects
3. Adds an initial storyteller message to both character histories
4. Stores the session in the in-memory `sessions` dictionary
5. Prints session info to the console

### Frontend Integration

The home page (`SessionSetup.js`) includes three quick-access functions:

- `joinDemoStoryteller()` - Calls `onCreateSession("demo-session-001")`
- `joinDemoBargin()` - Calls `onJoinSession("demo-session-001", "char-bargin-001")`
- `joinDemoWillow()` - Calls `onJoinSession("demo-session-001", "char-willow-002")`

These bypass the normal session creation/joining flow.

---

## Why This Matters

During development and testing, you'll restart the server **dozens of times**. Without a demo session, each restart requires:

1. Click "Create Session"
2. Enter session name
3. Wait for creation
4. Copy session ID
5. Open new window
6. Paste session ID
7. Enter character name
8. Enter character description
9. Enter personality
10. Select model
11. Click join
12. Repeat for second character

With the demo session:

1. Click one button

**That's a huge time saver!**

---

## Future Enhancements

When database persistence is implemented, you could:

- Save demo session to database on first run
- Load multiple pre-configured adventures
- Create a "Quick Start Gallery" of scenarios
- Import/export demo sessions as JSON

---

## FAQ

**Q: Does the demo session persist across server restarts?**  
A: No, it's recreated fresh each time. This ensures a clean state for testing.

**Q: Can I have multiple demo sessions?**  
A: Yes! Just create additional sessions with different IDs in the startup function.

**Q: Will the demo session interfere with real sessions?**  
A: No, it's just another session in memory. You can create regular sessions alongside it.

**Q: Can I modify character stats mid-session?**  
A: Not yet, but you can edit the character objects directly in the code and restart.

---

**Happy Testing!** 🎲✨