Initial commit
This commit is contained in:
Aodhan Collins
96
docs/setup/QUICKSTART.md
Normal file
96
docs/setup/QUICKSTART.md
Normal file
@@ -0,0 +1,96 @@
|
||||
# 🚀 Quick Start Guide
|
||||
|
||||
## Installation (5 minutes)
|
||||
|
||||
### 1. Backend Setup
|
||||
```bash
|
||||
# Install Python dependencies
|
||||
pip install -r requirements.txt
|
||||
|
||||
# Create environment file (optional - only for AI suggestions)
|
||||
cp .env.example .env
|
||||
# Edit .env and add your OpenAI API key if desired
|
||||
```
|
||||
|
||||
### 2. Frontend Setup
|
||||
```bash
|
||||
cd frontend
|
||||
npm install
|
||||
cd ..
|
||||
```
|
||||
|
||||
## Running the App
|
||||
|
||||
### Terminal 1 - Backend
|
||||
```bash
|
||||
python main.py
|
||||
# Server runs on http://localhost:8000
|
||||
```
|
||||
|
||||
### Terminal 2 - Frontend
|
||||
```bash
|
||||
cd frontend
|
||||
npm start
|
||||
# Opens browser at http://localhost:3000
|
||||
```
|
||||
|
||||
## First Session
|
||||
|
||||
### As Storyteller:
|
||||
1. Open http://localhost:3000
|
||||
2. Enter session name → "My Adventure"
|
||||
3. Click "Create New Session"
|
||||
4. **Copy the session ID** (shows at top of dashboard)
|
||||
5. Share session ID with players
|
||||
|
||||
### As Player:
|
||||
1. Open http://localhost:3000 (in different browser/tab)
|
||||
2. Paste the session ID
|
||||
3. Enter character details:
|
||||
- Name: "Aragorn"
|
||||
- Description: "A ranger from the north"
|
||||
- Personality: "Brave and noble"
|
||||
4. Click "Join Session"
|
||||
5. Send private message to storyteller
|
||||
|
||||
### Storyteller Dashboard:
|
||||
- See new character appear in left panel
|
||||
- Click character name to view their private message
|
||||
- Type response in bottom text area
|
||||
- Click "Send Private Response"
|
||||
- Use scene narration to broadcast to all characters
|
||||
|
||||
## Key Features
|
||||
|
||||
✅ **Private Messaging**: Each character's conversation is completely isolated
|
||||
✅ **Real-time Updates**: WebSocket communication for instant delivery
|
||||
✅ **Scene Narration**: Broadcast story updates to all characters
|
||||
✅ **Pending Indicators**: Red badges show which characters need responses
|
||||
✅ **Conversation History**: Full chat history preserved per character
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Backend won't start?**
|
||||
- Check Python version: `python --version` (needs 3.8+)
|
||||
- Install dependencies: `pip install -r requirements.txt`
|
||||
|
||||
**Frontend won't start?**
|
||||
- Check Node version: `node --version` (needs 16+)
|
||||
- Install dependencies: `cd frontend && npm install`
|
||||
|
||||
**WebSocket not connecting?**
|
||||
- Ensure backend is running on port 8000
|
||||
- Check browser console for errors
|
||||
- Try refreshing the page
|
||||
|
||||
**Characters can't join?**
|
||||
- Verify session ID is correct
|
||||
- Ensure storyteller session is active
|
||||
- Check that backend is running
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Invite multiple players to test isolated conversations
|
||||
- Try narrating scenes visible to all characters
|
||||
- Experiment with rich character descriptions
|
||||
- Optionally add OpenAI API key for AI-assisted storyteller suggestions
|
||||
268
docs/setup/QUICK_REFERENCE.md
Normal file
268
docs/setup/QUICK_REFERENCE.md
Normal file
@@ -0,0 +1,268 @@
|
||||
# 🎯 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
|
||||
Reference in New Issue
Block a user