storyteller/docs/setup/QUICK_REFERENCE.md

🎯 Quick Reference - Storyteller RPG

📍 Where We Are Now

✅ Current Features (Working)

• Basic storyteller-character private messaging
• Real-time WebSocket communication
• Multiple LLM support (GPT-4, Claude, Llama, Gemini, etc.)
• Each character can use different AI model
• Session creation and joining
• Message history per character
• Scene narrations broadcast to all

📁 Current File Structure

windsurf-project/
├── main.py                 # Backend API (FastAPI + WebSockets)
├── requirements.txt        # Python dependencies
├── .env                    # API keys configuration
├── start.sh               # Startup script (Linux/Mac)
├── start.bat              # Startup script (Windows)
├── frontend/
│   ├── src/
│   │   ├── App.js
│   │   ├── components/
│   │   │   ├── SessionSetup.js
│   │   │   ├── CharacterView.js
│   │   │   └── StorytellerView.js
│   │   └── App.css
│   ├── public/
│   │   └── index.html
│   └── package.json
├── README.md
├── LLM_GUIDE.md           # Guide to available LLMs
├── PROJECT_PLAN.md        # Full project roadmap
└── MVP_ROADMAP.md         # MVP-specific plan

---

🎯 MVP Goals Summary

Core User Modes

1. Player (Human/AI) - Play a character with profile
2. Storyteller (Human/AI) - Run the game, respond to players
3. Gamemaster (Human only) - Create/manage games, control AI
4. Admin (Dev only) - Full system access

Key Features for MVP

1. Public/Private Messages - Players can have secret actions
2. Character Profiles - Race, class, gender, personality
3. Import/Export - Save characters as JSON or PNG with metadata
4. AI Automation - AI players and storytellers run automatically
5. Game Management - Create games, assign roles, save progress
6. Permission System - Each role has specific capabilities

---

🎭 Character Profile System (MVP)

Races

• Human (Versatile)
• Elf (Graceful, perceptive)
• Dwarf (Sturdy, loyal)
• Orc (Strong, fierce)
• Halfling (Nimble, lucky)

Classes

• Warrior (Combat)
• Wizard (Magic)
• Cleric (Healing)
• Archer (Ranged)
• Rogue (Stealth)

Personalities

• Friendly (Optimistic)
• Serious (Focused)
• Doubtful (Cautious)
• Measured (Balanced)

Storyteller Styles

• Narrator (3rd person)
• DM (2nd person)
• Internal Thoughts (1st person)

---

📋 Permission Matrix

Action	Player	Storyteller	GM	Admin
View own messages	✅	✅	✅	✅
View public messages	✅	✅	✅	✅
View private messages	❌	✅	✅	✅
Edit own messages	✅	✅	✅	✅
Edit storyteller	❌	✅	❌	✅
Edit human players	❌	❌	❌	✅
Edit AI responses	❌	✅	✅	✅
Create games	❌	❌	✅	✅
Control AI	❌	✅	✅	✅

---

🗺️ 12-Week Implementation Plan

Weeks 1-2: Message System

• Public/private/mixed message types
• Enhanced message composer
• Visibility controls

Weeks 3-4: Character Profiles

• Profile creation wizard
• Race/class/personality templates
• Import/export (JSON & PNG)
• Profile-based LLM prompts

Weeks 5-7: User Modes

• Player interface
• Storyteller dashboard
• Gamemaster control panel
• Permission enforcement

Weeks 8-9: AI Automation

• AI player system
• AI storyteller system
• Automation controls
• Override mechanisms

Weeks 10-11: Game Management

• Game creation wizard
• Save/load system
• Database implementation
• Game checkpoints

Week 12: Polish & Testing

• UI/UX refinement
• Testing suite
• Documentation
• Performance optimization

---

🔧 Technology Stack

Current

• Backend: FastAPI, WebSockets, OpenAI/OpenRouter APIs
• Frontend: React, WebSocket client
• Storage: In-memory (temporary)

Needed for MVP

• Database: SQLAlchemy + PostgreSQL/SQLite
• Auth: JWT tokens (python-jose)
• Image: Pillow (PNG metadata)
• Frontend: react-hook-form, zod, file-saver

---

🚀 How to Run (Current)

# Quick start (kills old instances, starts both servers)
./start.sh

# Manual start
# Terminal 1 - Backend
python main.py

# Terminal 2 - Frontend
cd frontend
npm start

Access: http://localhost:3000

---

📝 Development Notes

Message Types (New Feature)

PUBLIC: "I shake the merchant's hand"
PRIVATE: "I attempt to pickpocket him"
MIXED: Both public and private actions in one message

Character Profile Structure

{
  "name": "Thorin",
  "gender": "Male",
  "race": "Dwarf",
  "class": "Warrior",
  "personality": "Serious",
  "llm_model": "anthropic/claude-3.5-sonnet",
  "custom_prompts": {
    "background": "A grizzled veteran...",
    "response_style": "Speak gruffly and with honor"
  }
}

LLM Prompt Building

# System prompt = Race + Class + Personality + Custom
"You are a Dwarf Warrior with a Serious personality. 
You are stout and honorable. You excel in combat. 
You are focused and pragmatic. Speak gruffly..."

---

🎯 Phase 1 Starting Point

First Task: Implement Public/Private Message System

Steps:

1. Update Message model in main.py:

   class Message(BaseModel):
       visibility: str  # "public", "private", "mixed"
       public_content: Optional[str]
       private_content: Optional[str]
   

2. Create message type selector in CharacterView.js:

   <select onChange={handleVisibilityChange}>
     <option value="public">Public Action</option>
     <option value="private">Private Action</option>
     <option value="mixed">Both</option>
   </select>
   

3. Update WebSocket message handling:

   • Filter messages based on user role
   • Storyteller sees all
   • Players see only public messages from others

4. Update UI to show message type indicators

Estimated Time: 3-5 days

---

📚 Documentation Links

• Full Roadmap: PROJECT_PLAN.md (15 weeks, all phases)
• MVP Plan: MVP_ROADMAP.md (12 weeks, core features)
• LLM Guide: LLM_GUIDE.md (Available AI models)
• README: README.md (Setup and usage)

---

❓ Key Questions to Answer During Development

1. Authentication: JWT vs Session-based?
2. Database: PostgreSQL or MongoDB?
3. Deployment: Docker, cloud provider?
4. AI Costs: Budget limits per game/user?
5. Scaling: How many concurrent games?
6. Context: How to handle long game histories with LLM limits?

---

Next Steps: Review MVP_ROADMAP.md and begin Phase 1 implementation!

Last Updated: 2025-01-11
Status: Planning Complete → Ready for Development