🚀 Quick Start Guide

Installation (5 minutes)

1. Backend Setup

# 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

cd frontend
npm install
cd ..

Running the App

Terminal 1 - Backend

python main.py
# Server runs on http://localhost:8000

Terminal 2 - Frontend

cd frontend
npm start
# Opens browser at http://localhost:3000

First Session

As Storyteller:

Open http://localhost:3000
Enter session name → "My Adventure"
Click "Create New Session"
Copy the session ID (shows at top of dashboard)
Share session ID with players

As Player:

Open http://localhost:3000 (in different browser/tab)
Paste the session ID
Enter character details:
- Name: "Aragorn"
- Description: "A ranger from the north"
- Personality: "Brave and noble"
Click "Join Session"
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

2.4 KiB Raw Blame History