Initial commit
This commit is contained in:
Aodhan Collins
583
docs/planning/MVP_ROADMAP.md
Normal file
583
docs/planning/MVP_ROADMAP.md
Normal file
@@ -0,0 +1,583 @@
|
||||
# 🎯 Storyteller RPG - MVP Roadmap
|
||||
|
||||
**Goal:** Create a functional multi-user RPG system with human and AI players/storytellers, character profiles, and basic game management.
|
||||
|
||||
---
|
||||
|
||||
## 📊 Current Status
|
||||
|
||||
**✅ Completed:**
|
||||
- Basic storyteller-player communication
|
||||
- WebSocket real-time messaging
|
||||
- Multiple LLM support (OpenAI + OpenRouter)
|
||||
- Character-specific AI models
|
||||
- Private character-storyteller conversations
|
||||
|
||||
**🔄 In Progress:**
|
||||
- Enhanced user modes and permissions
|
||||
|
||||
---
|
||||
|
||||
## 🎯 MVP Feature Set
|
||||
|
||||
### Core User Modes
|
||||
|
||||
#### 1. **Player Mode** (Human & AI)
|
||||
**Capabilities:**
|
||||
- ✅ Create character with profile (race, class, gender, personality)
|
||||
- ✅ Send messages to storyteller (public & private actions)
|
||||
- ✅ Generate AI-assisted responses with custom prompts
|
||||
- ✅ Edit/write custom messages before sending
|
||||
- ✅ View storyteller responses and scene narrations
|
||||
- ❌ Cannot edit storyteller responses
|
||||
- ✅ Import/export character profiles (JSON & PNG with metadata)
|
||||
|
||||
**Message Types:**
|
||||
1. **Public Action** - Visible to all players and storyteller
|
||||
- Example: "I shake hands with the merchant"
|
||||
2. **Private Action** - Only visible to storyteller
|
||||
- Example: "I attempt to pickpocket him while shaking hands"
|
||||
3. **Mixed Message** - Contains both public and private components
|
||||
|
||||
#### 2. **Storyteller Mode** (Human & AI)
|
||||
**Capabilities:**
|
||||
- ✅ View all player messages (public + private)
|
||||
- ✅ Generate/edit responses to individual players
|
||||
- ✅ Broadcast scene narrations to all players
|
||||
- ✅ Control AI player responses
|
||||
- ❌ Cannot edit human player messages
|
||||
- ✅ Choose storytelling style (Narrator/DM/Internal)
|
||||
- ✅ Set storyteller personality
|
||||
|
||||
**AI Storyteller:**
|
||||
- Automatically generates responses to player actions
|
||||
- Uses scenario/plot context to drive story
|
||||
- Responds to all players based on their actions
|
||||
- Can be overridden by Gamemaster
|
||||
|
||||
#### 3. **Gamemaster Mode** (Human Only)
|
||||
**Capabilities:**
|
||||
- ✅ Create and configure games
|
||||
- ✅ Set player slots (human or AI)
|
||||
- ✅ Assign storyteller (human or AI)
|
||||
- ✅ View all game messages and state
|
||||
- ✅ Send messages to any player/storyteller
|
||||
- ✅ Edit AI responses (players and storyteller)
|
||||
- ❌ Cannot edit human responses
|
||||
- ✅ Direct commands to AI storyteller (via special channel)
|
||||
- ✅ Save/load game progress
|
||||
|
||||
#### 4. **Admin Mode** (Development Only)
|
||||
**Capabilities:**
|
||||
- ✅ Full access to all games
|
||||
- ✅ Edit any message or setting
|
||||
- ✅ Manage LLM configuration
|
||||
- ✅ View cost/usage analytics
|
||||
- ✅ Debug mode features
|
||||
|
||||
---
|
||||
|
||||
## 🎭 Character Profile System (MVP)
|
||||
|
||||
### Character Creation Fields
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "string",
|
||||
"gender": "Male|Female|Non-binary|Custom",
|
||||
"race": "Human|Elf|Dwarf|Orc|Halfling",
|
||||
"class": "Warrior|Wizard|Cleric|Archer|Rogue",
|
||||
"personality": "Friendly|Serious|Doubtful|Measured",
|
||||
"llm_model": "string",
|
||||
"custom_prompts": {
|
||||
"character_background": "string",
|
||||
"response_style": "string",
|
||||
"special_traits": "string"
|
||||
},
|
||||
"appearance": {
|
||||
"avatar": "base64_image_data",
|
||||
"description": "string"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Race Profiles (MVP)
|
||||
|
||||
#### **Human**
|
||||
- **Traits:** Versatile, adaptable
|
||||
- **LLM Prompt:** "You are a human character, balanced and adaptable to any situation."
|
||||
|
||||
#### **Elf**
|
||||
- **Traits:** Graceful, perceptive, long-lived
|
||||
- **LLM Prompt:** "You are an elf, graceful and wise with centuries of experience and keen senses."
|
||||
|
||||
#### **Dwarf**
|
||||
- **Traits:** Sturdy, loyal, craftsman
|
||||
- **LLM Prompt:** "You are a dwarf, stout and honorable with deep knowledge of stone and metal."
|
||||
|
||||
#### **Orc**
|
||||
- **Traits:** Strong, fierce, honorable
|
||||
- **LLM Prompt:** "You are an orc, powerful and direct with a strong sense of honor and combat."
|
||||
|
||||
#### **Halfling**
|
||||
- **Traits:** Nimble, lucky, cheerful
|
||||
- **LLM Prompt:** "You are a halfling, small but brave with natural luck and a cheerful disposition."
|
||||
|
||||
### Class Profiles (MVP)
|
||||
|
||||
#### **Warrior**
|
||||
- **Focus:** Physical combat, leadership
|
||||
- **Prompt:** "You excel in combat and tactics, preferring direct action and protecting your allies."
|
||||
|
||||
#### **Wizard**
|
||||
- **Focus:** Arcane knowledge, spellcasting
|
||||
- **Prompt:** "You are a master of arcane arts, solving problems with magic and knowledge."
|
||||
|
||||
#### **Cleric**
|
||||
- **Focus:** Divine magic, healing, support
|
||||
- **Prompt:** "You channel divine power to heal and protect, guided by faith and compassion."
|
||||
|
||||
#### **Archer**
|
||||
- **Focus:** Ranged combat, precision, scouting
|
||||
- **Prompt:** "You are a skilled marksman, preferring distance and precision in combat."
|
||||
|
||||
#### **Rogue**
|
||||
- **Focus:** Stealth, cunning, skills
|
||||
- **Prompt:** "You rely on stealth and cunning, using tricks and skills to overcome obstacles."
|
||||
|
||||
### Personality Profiles (MVP)
|
||||
|
||||
#### **Friendly**
|
||||
- **Behavior:** Optimistic, trusting, cooperative
|
||||
- **Prompt Modifier:** "You are friendly and approachable, always looking for the good in others."
|
||||
|
||||
#### **Serious**
|
||||
- **Behavior:** Focused, pragmatic, disciplined
|
||||
- **Prompt Modifier:** "You are serious and focused, prioritizing efficiency and practical solutions."
|
||||
|
||||
#### **Doubtful**
|
||||
- **Behavior:** Cautious, questioning, analytical
|
||||
- **Prompt Modifier:** "You are cautious and skeptical, questioning motives and analyzing situations carefully."
|
||||
|
||||
#### **Measured**
|
||||
- **Behavior:** Balanced, thoughtful, diplomatic
|
||||
- **Prompt Modifier:** "You are measured and thoughtful, weighing options carefully before acting."
|
||||
|
||||
### Character Import/Export
|
||||
|
||||
#### **JSON Export**
|
||||
```json
|
||||
{
|
||||
"version": "1.0",
|
||||
"character": { /* full character data */ },
|
||||
"created_at": "2025-01-11T00:00:00Z",
|
||||
"game_history": [ /* optional */ ]
|
||||
}
|
||||
```
|
||||
|
||||
#### **PNG Export with Metadata**
|
||||
- Character avatar/portrait as PNG image
|
||||
- Character data embedded in PNG metadata (EXIF/custom chunks)
|
||||
- Allows sharing characters visually
|
||||
- Import by uploading PNG file
|
||||
|
||||
**Libraries Needed:**
|
||||
- Frontend: `exif-js`, `png-metadata`
|
||||
- Backend: `Pillow` (Python) for PNG metadata
|
||||
|
||||
---
|
||||
|
||||
## 📜 Storyteller System (MVP)
|
||||
|
||||
### Storyteller Styles
|
||||
|
||||
#### **Narrator (3rd Person)**
|
||||
```
|
||||
Example: "The warrior steps forward, hand extended toward the merchant.
|
||||
The shopkeeper's eyes gleam with suspicion as something feels amiss..."
|
||||
```
|
||||
**Prompt:** "Narrate the scene in third person, describing actions and atmosphere objectively."
|
||||
|
||||
#### **DM/Game Master (2nd Person)**
|
||||
```
|
||||
Example: "You step forward and shake the merchant's hand. As you do,
|
||||
you notice his purse hanging loosely from his belt..."
|
||||
```
|
||||
**Prompt:** "Address players directly in second person, as a dungeon master guiding their experience."
|
||||
|
||||
#### **Internal Thoughts (1st Person)**
|
||||
```
|
||||
Example: "I watch as the warrior approaches. Something about his
|
||||
movements seems off... Is he trying to distract me?"
|
||||
```
|
||||
**Prompt:** "Describe scenes from the perspective of NPCs or environment, revealing inner thoughts."
|
||||
|
||||
### Storyteller Personalities (MVP)
|
||||
|
||||
#### **Neutral**
|
||||
- **Behavior:** Unbiased, balanced narration
|
||||
- **Prompt:** "Narrate events fairly without favoring players or NPCs. Be descriptive but neutral."
|
||||
|
||||
*(Future: Add Challenging, Supportive, Mysterious personalities)*
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ MVP Implementation Plan
|
||||
|
||||
### Phase 1: Enhanced Message System (Week 1-2)
|
||||
|
||||
**Tasks:**
|
||||
1. **Public/Private Message Types**
|
||||
- [ ] Update `Message` model to include `visibility` field (public/private/mixed)
|
||||
- [ ] Frontend UI for selecting message visibility
|
||||
- [ ] Filter messages based on user role/permissions
|
||||
- [ ] WebSocket handling for different message types
|
||||
|
||||
2. **Message Composer Enhancement**
|
||||
- [ ] Tabbed interface: Public Action | Private Action | Mixed
|
||||
- [ ] Visual indicators for message type
|
||||
- [ ] Preview of what each role sees
|
||||
- [ ] AI generation respects visibility settings
|
||||
|
||||
**Backend Changes:**
|
||||
```python
|
||||
class Message(BaseModel):
|
||||
id: str
|
||||
sender_id: str
|
||||
content: str
|
||||
visibility: str # "public", "private", "mixed"
|
||||
public_content: Optional[str] # for mixed messages
|
||||
private_content: Optional[str] # for mixed messages
|
||||
timestamp: datetime
|
||||
```
|
||||
|
||||
**Frontend Components:**
|
||||
```jsx
|
||||
<MessageComposer
|
||||
onSend={handleSend}
|
||||
visibilityOptions={['public', 'private', 'mixed']}
|
||||
aiAssist={true}
|
||||
/>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Character Profile System (Week 3-4)
|
||||
|
||||
**Tasks:**
|
||||
1. **Character Profile Data Structure**
|
||||
- [ ] Extend `Character` model with profile fields
|
||||
- [ ] Profile creation wizard UI
|
||||
- [ ] Dropdown selectors for race/class/personality/gender
|
||||
- [ ] Custom prompt input fields
|
||||
- [ ] Avatar upload/selection
|
||||
|
||||
2. **Profile-Based LLM Prompts**
|
||||
- [ ] Build system prompt from character profile
|
||||
- [ ] Combine race + class + personality traits
|
||||
- [ ] Inject custom prompts into LLM requests
|
||||
- [ ] Store prompt templates in database
|
||||
|
||||
3. **Import/Export System**
|
||||
- [ ] Export character to JSON
|
||||
- [ ] Export character to PNG with embedded metadata
|
||||
- [ ] Import from JSON file
|
||||
- [ ] Import from PNG file (extract metadata)
|
||||
- [ ] Profile validation on import
|
||||
|
||||
**Backend Implementation:**
|
||||
```python
|
||||
class CharacterProfile(BaseModel):
|
||||
gender: str
|
||||
race: str # Human, Elf, Dwarf, Orc, Halfling
|
||||
character_class: str # Warrior, Wizard, Cleric, Archer, Rogue
|
||||
personality: str # Friendly, Serious, Doubtful, Measured
|
||||
background: Optional[str]
|
||||
custom_prompts: Dict[str, str]
|
||||
avatar_data: Optional[str] # base64 encoded
|
||||
|
||||
def build_character_prompt(profile: CharacterProfile) -> str:
|
||||
"""Builds LLM system prompt from character profile"""
|
||||
race_prompt = RACE_PROMPTS[profile.race]
|
||||
class_prompt = CLASS_PROMPTS[profile.character_class]
|
||||
personality_prompt = PERSONALITY_PROMPTS[profile.personality]
|
||||
|
||||
return f"{race_prompt} {class_prompt} {personality_prompt} {profile.custom_prompts.get('response_style', '')}"
|
||||
```
|
||||
|
||||
**Frontend Components:**
|
||||
```jsx
|
||||
<CharacterCreationWizard>
|
||||
<Step1_BasicInfo />
|
||||
<Step2_RaceSelection />
|
||||
<Step3_ClassSelection />
|
||||
<Step4_Personality />
|
||||
<Step5_CustomPrompts />
|
||||
<Step6_Avatar />
|
||||
<Step7_Review />
|
||||
</CharacterCreationWizard>
|
||||
|
||||
<CharacterImportExport
|
||||
onExportJSON={handleJSONExport}
|
||||
onExportPNG={handlePNGExport}
|
||||
onImport={handleImport}
|
||||
/>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: User Mode Interfaces (Week 5-7)
|
||||
|
||||
**Tasks:**
|
||||
1. **Player Interface Refinement**
|
||||
- [ ] Character sheet display
|
||||
- [ ] Public/private message controls
|
||||
- [ ] AI generation with character context
|
||||
- [ ] Cannot edit storyteller responses (UI enforcement)
|
||||
|
||||
2. **Storyteller Dashboard**
|
||||
- [ ] View all messages (public + private)
|
||||
- [ ] Response composer per player
|
||||
- [ ] AI player management
|
||||
- [ ] Style selector (Narrator/DM/Internal)
|
||||
- [ ] Cannot edit human player messages
|
||||
|
||||
3. **Gamemaster Control Panel**
|
||||
- [ ] Game creation wizard
|
||||
- [ ] Player slot assignment (human/AI)
|
||||
- [ ] Storyteller assignment (human/AI)
|
||||
- [ ] View all game state
|
||||
- [ ] Direct AI storyteller commands
|
||||
- [ ] Edit AI responses only
|
||||
|
||||
4. **Permission Enforcement**
|
||||
- [ ] Backend permission decorators
|
||||
- [ ] Frontend UI disabled states
|
||||
- [ ] WebSocket message filtering
|
||||
- [ ] API endpoint protection
|
||||
|
||||
**Permission Matrix:**
|
||||
|
||||
| Action | Player | Storyteller | Gamemaster | Admin |
|
||||
|--------|--------|-------------|------------|-------|
|
||||
| Read own messages | ✅ | ✅ | ✅ | ✅ |
|
||||
| Read other players (public) | ✅ | ✅ | ✅ | ✅ |
|
||||
| Read other players (private) | ❌ | ✅ | ✅ | ✅ |
|
||||
| Edit own messages | ✅ | ✅ | ✅ | ✅ |
|
||||
| Edit storyteller responses | ❌ | ✅ | ❌ | ✅ |
|
||||
| Edit human player messages | ❌ | ❌ | ❌ | ✅ |
|
||||
| Edit AI responses | ❌ | ✅ | ✅ | ✅ |
|
||||
| Create game | ❌ | ❌ | ✅ | ✅ |
|
||||
| Assign roles | ❌ | ❌ | ✅ | ✅ |
|
||||
| Direct AI commands | ❌ | ❌ | ✅ | ✅ |
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: AI Automation (Week 8-9)
|
||||
|
||||
**Tasks:**
|
||||
1. **AI Player System**
|
||||
- [ ] Automated response generation
|
||||
- [ ] Use character profile in prompts
|
||||
- [ ] Respond to storyteller automatically
|
||||
- [ ] Configurable response delay
|
||||
- [ ] Generate public AND private actions
|
||||
|
||||
2. **AI Storyteller System**
|
||||
- [ ] Respond to all player actions
|
||||
- [ ] Generate scene narrations
|
||||
- [ ] Track plot progression
|
||||
- [ ] Use storyteller style in responses
|
||||
- [ ] Gamemaster command channel
|
||||
|
||||
3. **Automation Controls**
|
||||
- [ ] Enable/disable AI automation per role
|
||||
- [ ] Manual trigger for AI responses
|
||||
- [ ] Review mode (generate but don't send)
|
||||
- [ ] Override AI decisions
|
||||
|
||||
**AI Player Prompt Structure:**
|
||||
```
|
||||
System: You are {name}, a {gender} {race} {class} with a {personality} personality.
|
||||
|
||||
{race_traits}
|
||||
{class_abilities}
|
||||
{personality_traits}
|
||||
{custom_background}
|
||||
|
||||
Current scene: {scene_description}
|
||||
Recent events: {recent_context}
|
||||
|
||||
Respond to the storyteller's latest message. Consider:
|
||||
- What would your character do publicly (visible to all)?
|
||||
- What secret actions might you take (only storyteller sees)?
|
||||
- Stay in character based on your race, class, and personality.
|
||||
|
||||
Format your response as:
|
||||
PUBLIC: [what everyone sees]
|
||||
PRIVATE: [secret actions only storyteller knows]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 5: Game Management & Save System (Week 10-11)
|
||||
|
||||
**Tasks:**
|
||||
1. **Game Creation**
|
||||
- [ ] Game setup wizard
|
||||
- [ ] Scenario/setting description
|
||||
- [ ] Player slot configuration
|
||||
- [ ] Storyteller assignment
|
||||
- [ ] Game lobby/waiting room
|
||||
|
||||
2. **Save/Load System**
|
||||
- [ ] Export game state to JSON
|
||||
- [ ] Import saved game
|
||||
- [ ] Auto-save every N minutes
|
||||
- [ ] Game checkpoints
|
||||
- [ ] Game history log
|
||||
|
||||
3. **Database Implementation**
|
||||
- [ ] Replace in-memory storage
|
||||
- [ ] SQLite for development
|
||||
- [ ] PostgreSQL for production
|
||||
- [ ] Migration system (Alembic)
|
||||
|
||||
**Game State Schema:**
|
||||
```python
|
||||
class Game(Base):
|
||||
__tablename__ = "games"
|
||||
|
||||
id: str (PK)
|
||||
name: str
|
||||
scenario: str
|
||||
created_by: str (FK to User)
|
||||
created_at: datetime
|
||||
status: str # lobby, active, paused, completed
|
||||
|
||||
# Configuration
|
||||
max_players: int
|
||||
storyteller_id: Optional[str]
|
||||
storyteller_is_ai: bool
|
||||
|
||||
# Relations
|
||||
players: List[Player]
|
||||
messages: List[Message]
|
||||
checkpoints: List[GameCheckpoint]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 6: Polish & Testing (Week 12)
|
||||
|
||||
**Tasks:**
|
||||
1. **UI/UX Polish**
|
||||
- [ ] Consistent styling across all modes
|
||||
- [ ] Loading states and animations
|
||||
- [ ] Error handling and user feedback
|
||||
- [ ] Responsive design
|
||||
|
||||
2. **Testing**
|
||||
- [ ] Unit tests for character profiles
|
||||
- [ ] Permission enforcement tests
|
||||
- [ ] AI automation tests
|
||||
- [ ] End-to-end game flow tests
|
||||
|
||||
3. **Documentation**
|
||||
- [ ] User guide for each mode
|
||||
- [ ] Character creation guide
|
||||
- [ ] Game setup tutorial
|
||||
- [ ] API documentation
|
||||
|
||||
4. **Performance**
|
||||
- [ ] Optimize LLM calls
|
||||
- [ ] WebSocket performance
|
||||
- [ ] Database query optimization
|
||||
- [ ] Caching strategy
|
||||
|
||||
---
|
||||
|
||||
## 📦 Dependencies to Add
|
||||
|
||||
### Backend
|
||||
```txt
|
||||
# requirements.txt additions
|
||||
sqlalchemy==2.0.23
|
||||
alembic==1.13.0
|
||||
pillow==10.1.0 # For PNG metadata handling
|
||||
```
|
||||
|
||||
### Frontend
|
||||
```json
|
||||
// package.json additions
|
||||
"react-hook-form": "^7.48.0",
|
||||
"zod": "^3.22.0",
|
||||
"file-saver": "^2.0.5",
|
||||
"png-metadata": "^1.0.0"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 MVP Success Criteria
|
||||
|
||||
**The MVP is complete when:**
|
||||
|
||||
✅ **Players can:**
|
||||
- Create characters with full profiles (race/class/personality)
|
||||
- Send public and private messages
|
||||
- Use AI to generate in-character responses
|
||||
- Export/import character profiles (JSON & PNG)
|
||||
|
||||
✅ **Storytellers can:**
|
||||
- View all player actions (public and private)
|
||||
- Respond to players with chosen style
|
||||
- Control AI players
|
||||
- Generate scene narrations
|
||||
|
||||
✅ **AI Players can:**
|
||||
- Automatically generate responses with character personality
|
||||
- Create both public and private actions
|
||||
- Respond contextually to storyteller
|
||||
|
||||
✅ **AI Storytellers can:**
|
||||
- Run entire games automatically
|
||||
- Respond to all player actions
|
||||
- Generate appropriate scene narrations
|
||||
- Accept Gamemaster override
|
||||
|
||||
✅ **Gamemasters can:**
|
||||
- Create and configure games
|
||||
- Assign human/AI to roles
|
||||
- View entire game state
|
||||
- Command AI storyteller
|
||||
- Save/load games
|
||||
|
||||
✅ **System can:**
|
||||
- Enforce all permissions correctly
|
||||
- Save and load game progress
|
||||
- Handle multiple concurrent games
|
||||
- Track LLM usage and costs
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Next Immediate Steps
|
||||
|
||||
### Week 1 - Day 1-3: Message System
|
||||
1. Update `Message` model with visibility fields
|
||||
2. Create message type selector UI
|
||||
3. Implement message filtering logic
|
||||
4. Test public/private message flow
|
||||
|
||||
### Week 1 - Day 4-7: Character Profiles
|
||||
1. Design character profile schema
|
||||
2. Create race/class/personality prompt templates
|
||||
3. Build character creation wizard
|
||||
4. Implement profile-based LLM prompts
|
||||
|
||||
**Ready to begin?** Let's start with Phase 1 - Enhanced Message System!
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** 2025-01-11
|
||||
**Target MVP Completion:** 12 weeks
|
||||
**Current Phase:** Planning → Implementation
|
||||
Reference in New Issue
Block a user