storyteller/docs/planning/MVP_ROADMAP.md

🎯 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

{
  "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

{
  "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:

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:

<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:

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:

<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:

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

# requirements.txt additions
sqlalchemy==2.0.23
alembic==1.13.0
pillow==10.1.0  # For PNG metadata handling

Frontend

// 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