# 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.*