269 lines
6.6 KiB
Markdown
269 lines
6.6 KiB
Markdown
# 🎯 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)
|
|
|
|
```bash
|
|
# 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
|
|
```json
|
|
{
|
|
"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
|
|
```python
|
|
# 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`:
|
|
```python
|
|
class Message(BaseModel):
|
|
visibility: str # "public", "private", "mixed"
|
|
public_content: Optional[str]
|
|
private_content: Optional[str]
|
|
```
|
|
|
|
2. Create message type selector in `CharacterView.js`:
|
|
```jsx
|
|
<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
|