simple-adventure/plan.md

# 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: Stats
│   ├── 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] # Keys: "north", "south", "east", "west"
├── 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: Stats
├── usable: bool
└── hidden: bool

Stats (Resource)
├── investigation: int
├── strength: int
├── dexterity: int
└── charisma: int
```

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

- **Task 1**: Set up Godot project, initialize git repository.
- **Task 2**: Create `Stats`, `Player`, `Item`, `Room`, and `GameState` resource classes.
- **Task 3**: Implement `MapGenerator` to create a 3x3 grid of `Room` resources.
- **Task 4**: Build `StateManager` to handle saving and loading `GameState` to/from a file.
- **Task 5**: Create JSON definitions for room templates and items, and a `ContentManager` to load them.

**Deliverable**: A functional game world that can be procedurally generated, saved, and loaded.

### Phase 2: Game Logic (Tasks 6-9)
**Goal**: Core gameplay mechanics and LLM integration.

- **Task 6**: Implement `ActionResolver` with a dice rolling system based on player `Stats`.
- **Task 7**: Set up Ollama and the `LLMInterface` to communicate with a local model (e.g., Llama 3.1 8B).
- **Task 8**: Develop the `CommandParser` to extract player intent from text input using the LLM.
- **Task 9**: Implement the main `GameManager` loop to process turns and handle player input.

**Deliverable**: A working game that can process simple commands (e.g., "go north", "look around") and resolve actions.

### Phase 3: User Interface (Tasks 10-12)
**Goal**: A complete text-based interface for interaction.

- **Task 10**: Build the main `GameUI` scene for displaying text and capturing player input.
- **Task 11**: Implement logic to generate and display room descriptions and action outcomes.
- **Task 12**: Create UI elements for inventory management, command history, and a help system.

**Deliverable**: A playable game with a full text-based interface.

### Phase 4: Content & Polish (Tasks 13-16)
**Goal**: A rich and engaging gameplay experience.

- **Task 13**: Flesh out the `ActionResolver` to handle a wider variety of actions and their consequences.
- **Task 14**: Create test scenarios and add more content (items, rooms, descriptions).
- **Task 15**: Develop a `DebugPanel` for inspecting game state and testing features.
- **Task 16**: Optimize LLM prompts and responses for clarity and consistency.

**Deliverable**: A polished MVP ready for user testing.

### Phase 5: Package & Deploy (Task 17)
**Goal**: A distributable game build.

- **Task 17**: Perform final testing, fix bugs, and package the game for distribution with setup instructions.

**Deliverable**: A complete and distributable MVP build.

## Technical Decisions

### Database Choice: Godot Resources
- **Pros**: Built-in serialization, no external dependencies, easy debugging.
- **Cons**: Limited querying, no concurrent access.
- **Rationale**: Ideal for a single-player MVP. Can be migrated to a more robust database if the project scales.

### LLM Integration: Local First
- **MVP**: Use a local LLM (Ollama with Llama 3.1 8B) for offline play, fast responses, and privacy.
- **Future**: Explore a hybrid approach, using cloud APIs for more complex narrative generation while keeping core command parsing local.

### Map Size: 3x3 Grid
- **Rationale**: A manageable size for the MVP that is sufficient to test all systems.
- **Expansion**: The architecture will allow for easy scaling to larger maps in the future.

## 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
│       └── Stats.gd          # Stats 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 a fast, capable model like Llama 3.1 8B.
- **Fallback**: A simple, rule-based parser for development and testing without the LLM.
- **Interface**: Use Godot's `HTTPRequest` node to communicate with the local Ollama server.

### Prompt Engineering
- **System Prompt**: Clearly define the game's rules, the player's goal, and the expected JSON output format for commands.
- **Context Window**: Provide the LLM with the current room description, player inventory, and recent actions to maintain context.
- **Response Format**: Expect a structured JSON object from the LLM that identifies the player's intent and any relevant entities (e.g., items, directions).
- **Validation**: The `CommandParser` will validate the LLM's JSON output against the current game state to ensure commands are valid.

### Example Interaction Flow
```
1. Player Input: "Search the room for any items"
2. Context Building: The `CommandParser` gathers the current room state, player stats, and inventory.
3. LLM Prompt: A system prompt is combined with the context and the player's command.
4. LLM Response: {"intent": "search_room", "target": "room"}
5. Action Resolution: The `ActionResolver` receives the intent, determines the difficulty (e.g., based on room properties), and performs a dice roll against the player's `investigation` stat.
6. State Update: The game state is updated based on the outcome (e.g., items are revealed).
7. Narrative Generation: A description of the outcome is generated and displayed to the player.
```

## Success Metrics

### MVP Completion Criteria
- [ ] The 3x3 map generates consistently with varied rooms.
- [ ] The player can navigate between all rooms.
- [ ] Items can be discovered, collected, and used.
- [ ] Core commands (look, search, take, use, move) are correctly parsed and executed.
- [ ] The game state is successfully saved and loaded between sessions.
- [ ] The LLM provides coherent and contextually appropriate command interpretations.
- [ ] The dice rolling system influences the outcomes of actions.

### Quality Targets
- Command response time should be under 2 seconds.
- The core gameplay loop must be stable and free of crashes.
- The narrative voice and world logic should remain consistent.
- The UI must provide clear feedback for all player actions.

## Future Enhancements (Post-MVP)

- **Hybrid LLM Approach**: Integrate cloud APIs for more complex narrative generation.
- **Expanded Features**: Introduce larger maps, a combat system, character progression, and multiple scenarios.
- **Technical Improvements**: Migrate to a more advanced database, optimize performance, and refine prompt engineering techniques.
- **Visuals and Sound**: Add visual elements and sound effects to enhance the player experience.

## Development Notes

### Version Control
- All code and assets will be managed using Git.
- Commits should be atomic and linked to specific tasks or features.

### Testing Strategy
- Unit tests for core systems like `ActionResolver` and `StateManager`.
- Integration tests for the full LLM command parsing pipeline.
- Extensive playtesting to ensure game balance and a positive user experience.
- Rigorous testing of the save/load functionality to ensure data integrity.

### Risk Mitigation
- **LLM Reliability**: Implement a fallback to a rule-based parser if the LLM fails.
- **Performance**: Profile and optimize code, especially the LLM interface and map generation.
- **Scope Creep**: Adhere strictly to the MVP features defined in this plan.
- **Complexity**: Maintain a modular and well-documented codebase to manage complexity.

---

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