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.