9.8 KiB
9.8 KiB
Simple Adventure Game - MVP Plan
Project Overview
A text-based adventure game built in Godot with LLM-powered command parsing and narrative generation. The game features procedural map generation, persistent state management, and stat-based action resolution.
Core Features
- Procedurally generated 3x3 map with predetermined room layouts and item placements
- Local LLM integration for command parsing and dungeon master functionality
- Database persistence using Godot's resource system to prevent hallucinations
- Player stats system with dice-based action resolution
- Text-based interface with rich narrative descriptions
Technical Architecture
Data Models
GameState (Resource)
├── Player (Resource)
│ ├── stats: Dictionary (investigation, strength, dexterity, etc.)
│ ├── inventory: Array[Item]
│ ├── current_room: Vector2
│ └── health: int
├── WorldMap (Resource)
│ ├── rooms: Dictionary[Vector2, Room]
│ ├── size: Vector2 (3x3 for MVP)
│ └── seed: int
└── game_history: Array[String]
Room (Resource)
├── position: Vector2
├── description: String
├── items: Array[Item]
├── exits: Dictionary[String, Vector2]
├── visited: bool
├── room_type: String (bedroom, corridor, dungeon, etc.)
└── special_features: Array[String]
Item (Resource)
├── name: String
├── description: String
├── item_type: String (key, weapon, consumable, etc.)
├── stats_modifier: Dictionary
├── usable: bool
└── hidden: bool
System Architecture
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ Text UI │◄──►│ Game Manager │◄──►│ State Manager │
│ │ │ │ │ │
│ - Input capture │ │ - Game loop │ │ - Save/Load │
│ - Text display │ │ - Turn processing│ │ - State queries │
│ - History │ │ - Event handling │ │ - Validation │
└─────────────────┘ └──────────────────┘ └─────────────────┘
│
▼
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ LLM Interface │◄──►│ Command Parser │◄──►│ Action Resolver │
│ │ │ │ │ │
│ - Local LLM │ │ - Intent extract │ │ - Dice rolling │
│ - Prompt mgmt │ │ - Context build │ │ - Stat checks │
│ - Response proc │ │ - Validation │ │ - Consequences │
└─────────────────┘ └──────────────────┘ └─────────────────┘
│
▼
┌─────────────────┐ ┌──────────────────┐
│ Map Generator │ │ Content Manager │
│ │ │ │
│ - Room creation │ │ - Item placement │
│ - Layout design │ │ - Description │
│ - Connections │ │ - Scenarios │
└─────────────────┘ └──────────────────┘
Implementation Phases
Phase 1: Foundation (Tasks 1-5)
Goal: Basic Godot project with core data structures
- Set up Godot project structure
- Create Resource classes for game objects
- Implement basic map generation
- Build save/load functionality
- Create room templates and item placement
Deliverable: Functional game world that can be saved and loaded
Phase 2: Game Logic (Tasks 6-9)
Goal: Core gameplay mechanics and LLM integration
- Player stats and dice rolling system
- Local LLM setup (Ollama integration)
- Command parsing pipeline
- Basic game loop implementation
Deliverable: Working game that can process simple commands
Phase 3: User Interface (Tasks 10-12)
Goal: Complete text-based interface
- Text UI for game interaction
- Room description generation
- Inventory and item management
- Command history and help system
Deliverable: Playable game with full text interface
Phase 4: Content & Polish (Tasks 13-16)
Goal: Rich gameplay experience
- Action resolution with consequences
- Test scenarios and content
- Debugging and development tools
- LLM prompt optimization
Deliverable: Polished MVP ready for testing
Phase 5: Package & Deploy (Task 17)
Goal: Distributable game build
- Final testing and bug fixes
- Build packaging
- Documentation and setup guides
Deliverable: Complete MVP build
Technical Decisions
Database Choice: Godot Resources
- Pros: Built-in serialization, no external dependencies, easy debugging
- Cons: Limited querying, no concurrent access
- Rationale: Perfect for single-player MVP, can migrate later if needed
LLM Integration: Local First
- MVP: Local LLM (Ollama) for offline play and fast responses
- Future: Hybrid approach with cloud APIs for advanced features
- Benefits: Privacy, reliability, cost control
Map Size: 3x3 Grid
- Rationale: Small enough for MVP testing, large enough to demonstrate systems
- Expansion: Easy to scale to larger maps later
- Layout: Predetermined room types with procedural item placement
File Structure
simple-adventure/
├── plan.md # This file
├── project.godot # Godot project file
├── scenes/
│ ├── Main.tscn # Main game scene
│ ├── UI/
│ │ ├── GameUI.tscn # Text-based interface
│ │ └── DebugPanel.tscn # Development tools
│ └── rooms/
│ ├── RoomTemplate.tscn # Base room scene
│ └── room_types/ # Specific room layouts
├── scripts/
│ ├── GameManager.gd # Main game controller
│ ├── StateManager.gd # Save/load and state queries
│ ├── LLMInterface.gd # Local LLM communication
│ ├── CommandParser.gd # Command interpretation
│ ├── ActionResolver.gd # Dice rolls and consequences
│ ├── MapGenerator.gd # Procedural map creation
│ └── resources/
│ ├── GameState.gd # Game state resource
│ ├── Room.gd # Room resource
│ ├── Item.gd # Item resource
│ └── Player.gd # Player resource
├── data/
│ ├── room_templates.json # Room layout definitions
│ ├── item_database.json # Item definitions
│ └── prompts/
│ ├── system_prompt.txt # LLM system instructions
│ └── templates/ # Response templates
└── saves/ # Game save files
LLM Integration Strategy
Local LLM Setup
- Recommended: Ollama with Llama 3.1 or similar
- Fallback: Simple rule-based parser for development
- Interface: HTTP API calls to local server
Prompt Engineering
- System Prompt: Define game rules and response format
- Context Window: Include current room, inventory, recent actions
- Response Format: Structured JSON with action type and description
- Validation: Check responses against game state
Example Interaction Flow
1. Player Input: "Search the room for any items"
2. Context Building: Current room state + player stats + inventory
3. LLM Prompt: System prompt + context + player command
4. LLM Response: {"action": "search", "difficulty": 10, "description": "..."}
5. Dice Roll: Player investigation vs difficulty
6. Result Processing: Update game state based on success/failure
7. Response Generation: Narrative description of outcome
Success Metrics
MVP Completion Criteria
- 3x3 map generates consistently
- Player can move between rooms
- Items can be found and collected
- Basic commands work (look, search, take, use)
- Game state persists between sessions
- LLM provides coherent responses
- Dice rolling affects outcomes
Quality Targets
- Response time < 2 seconds for most commands
- No game-breaking bugs in core functionality
- Consistent narrative voice and world logic
- Clear feedback for all player actions
Future Enhancements (Post-MVP)
Hybrid LLM Approach
- Cloud API for complex narrative generation
- Local LLM for fast command parsing
- Fallback systems for offline play
Expanded Features
- Larger procedural maps
- Combat system
- Character progression
- Multiple game scenarios
- Multiplayer support
Technical Improvements
- Database migration for complex queries
- Performance optimization
- Advanced AI prompt engineering
- Visual elements and sound
Development Notes
Testing Strategy
- Unit tests for core systems
- Integration tests for LLM responses
- Playtesting scenarios for game balance
- Save/load integrity testing
Risk Mitigation
- LLM Reliability: Fallback to rule-based parsing
- Performance: Local processing with optimization
- Complexity: Modular design for incremental development
- Scope Creep: Strict MVP focus with clear future roadmap
This plan serves as the technical specification and roadmap for the Simple Adventure Game MVP. It will be updated as development progresses and requirements evolve.