Upload files to "/"

plan.md

@@ -19,7 +19,7 @@ A text-based adventure game built in Godot with LLM-powered command parsing and
 ```
 GameState (Resource)
 ├── Player (Resource)
-│   ├── stats: Dictionary (investigation, strength, dexterity, etc.)
+│   ├── stats: Stats
 │   ├── inventory: Array[Item]
 │   ├── current_room: Vector2
 │   └── health: int
@@ -33,7 +33,7 @@ Room (Resource)
 ├── position: Vector2
 ├── description: String
 ├── items: Array[Item]
-├── exits: Dictionary[String, Vector2]
+├── exits: Dictionary[String, Vector2] # Keys: "north", "south", "east", "west"
 ├── visited: bool
 ├── room_type: String (bedroom, corridor, dungeon, etc.)
 └── special_features: Array[String]
@@ -42,9 +42,15 @@ Item (Resource)
 ├── name: String
 ├── description: String
 ├── item_type: String (key, weapon, consumable, etc.)
-├── stats_modifier: Dictionary
+├── stats_modifier: Stats
 ├── usable: bool
 └── hidden: bool
+
+Stats (Resource)
+├── investigation: int
+├── strength: int
+├── dexterity: int
+└── charisma: int
 ```
 
 ### System Architecture
@@ -80,71 +86,66 @@ Item (Resource)
 ## Implementation Phases
 
 ### Phase 1: Foundation (Tasks 1-5)
-**Goal**: Basic Godot project with core data structures
+**Goal**: Basic Godot project with core data structures.
 
-- Set up Godot project structure
+- **Task 1**: Set up Godot project, initialize git repository.
-- Create Resource classes for game objects
+- **Task 2**: Create `Stats`, `Player`, `Item`, `Room`, and `GameState` resource classes.
-- Implement basic map generation
+- **Task 3**: Implement `MapGenerator` to create a 3x3 grid of `Room` resources.
-- Build save/load functionality
+- **Task 4**: Build `StateManager` to handle saving and loading `GameState` to/from a file.
-- Create room templates and item placement
+- **Task 5**: Create JSON definitions for room templates and items, and a `ContentManager` to load them.
 
-**Deliverable**: Functional game world that can be saved and loaded
+**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
+**Goal**: Core gameplay mechanics and LLM integration.
 
-- Player stats and dice rolling system
+- **Task 6**: Implement `ActionResolver` with a dice rolling system based on player `Stats`.
-- Local LLM setup (Ollama integration)
+- **Task 7**: Set up Ollama and the `LLMInterface` to communicate with a local model (e.g., Llama 3.1 8B).
-- Command parsing pipeline
+- **Task 8**: Develop the `CommandParser` to extract player intent from text input using the LLM.
-- Basic game loop implementation
+- **Task 9**: Implement the main `GameManager` loop to process turns and handle player input.
 
-**Deliverable**: Working game that can process simple commands
+**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**: Complete text-based interface
+**Goal**: A complete text-based interface for interaction.
 
-- Text UI for game interaction
+- **Task 10**: Build the main `GameUI` scene for displaying text and capturing player input.
-- Room description generation
+- **Task 11**: Implement logic to generate and display room descriptions and action outcomes.
-- Inventory and item management
+- **Task 12**: Create UI elements for inventory management, command history, and a help system.
-- Command history and help system
 
-**Deliverable**: Playable game with full text interface
+**Deliverable**: A playable game with a full text-based interface.
 
 ### Phase 4: Content & Polish (Tasks 13-16)
-**Goal**: Rich gameplay experience
+**Goal**: A rich and engaging gameplay experience.
 
-- Action resolution with consequences
+- **Task 13**: Flesh out the `ActionResolver` to handle a wider variety of actions and their consequences.
-- Test scenarios and content
+- **Task 14**: Create test scenarios and add more content (items, rooms, descriptions).
-- Debugging and development tools
+- **Task 15**: Develop a `DebugPanel` for inspecting game state and testing features.
-- LLM prompt optimization
+- **Task 16**: Optimize LLM prompts and responses for clarity and consistency.
 
-**Deliverable**: Polished MVP ready for testing
+**Deliverable**: A polished MVP ready for user testing.
 
 ### Phase 5: Package & Deploy (Task 17)
-**Goal**: Distributable game build
+**Goal**: A distributable game build.
 
-- Final testing and bug fixes
+- **Task 17**: Perform final testing, fix bugs, and package the game for distribution with setup instructions.
-- Build packaging
-- Documentation and setup guides
 
-**Deliverable**: Complete MVP build
+**Deliverable**: A complete and distributable MVP build.
 
 ## Technical Decisions
 
 ### Database Choice: Godot Resources
-- **Pros**: Built-in serialization, no external dependencies, easy debugging
+- **Pros**: Built-in serialization, no external dependencies, easy debugging.
-- **Cons**: Limited querying, no concurrent access
+- **Cons**: Limited querying, no concurrent access.
-- **Rationale**: Perfect for single-player MVP, can migrate later if needed
+- **Rationale**: Ideal for a single-player MVP. Can be migrated to a more robust database if the project scales.
 
 ### LLM Integration: Local First
-- **MVP**: Local LLM (Ollama) for offline play and fast responses
+- **MVP**: Use a local LLM (Ollama with Llama 3.1 8B) for offline play, fast responses, and privacy.
-- **Future**: Hybrid approach with cloud APIs for advanced features
+- **Future**: Explore a hybrid approach, using cloud APIs for more complex narrative generation while keeping core command parsing local.
-- **Benefits**: Privacy, reliability, cost control
 
 ### Map Size: 3x3 Grid
-- **Rationale**: Small enough for MVP testing, large enough to demonstrate systems
+- **Rationale**: A manageable size for the MVP that is sufficient to test all systems.
-- **Expansion**: Easy to scale to larger maps later
+- **Expansion**: The architecture will allow for easy scaling to larger maps in the future.
-- **Layout**: Predetermined room types with procedural item placement
 
 ## File Structure
 
@@ -171,7 +172,8 @@ simple-adventure/
 │       ├── GameState.gd      # Game state resource
 │       ├── Room.gd           # Room resource
 │       ├── Item.gd           # Item resource
-│       └── Player.gd         # Player resource
+│       ├── Player.gd         # Player resource
+│       └── Stats.gd          # Stats resource
 ├── data/
 │   ├── room_templates.json   # Room layout definitions
 │   ├── item_database.json    # Item definitions
@@ -184,78 +186,69 @@ simple-adventure/
 ## LLM Integration Strategy
 
 ### Local LLM Setup
-- **Recommended**: Ollama with Llama 3.1 or similar
+- **Recommended**: Ollama with a fast, capable model like Llama 3.1 8B.
-- **Fallback**: Simple rule-based parser for development
+- **Fallback**: A simple, rule-based parser for development and testing without the LLM.
-- **Interface**: HTTP API calls to local server
+- **Interface**: Use Godot's `HTTPRequest` node to communicate with the local Ollama server.
 
 ### Prompt Engineering
-- **System Prompt**: Define game rules and response format
+- **System Prompt**: Clearly define the game's rules, the player's goal, and the expected JSON output format for commands.
-- **Context Window**: Include current room, inventory, recent actions
+- **Context Window**: Provide the LLM with the current room description, player inventory, and recent actions to maintain context.
-- **Response Format**: Structured JSON with action type and description
+- **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**: Check responses against game state
+- **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: Current room state + player stats + inventory
+2. Context Building: The `CommandParser` gathers the current room state, player stats, and inventory.
-3. LLM Prompt: System prompt + context + player command
+3. LLM Prompt: A system prompt is combined with the context and the player's command.
-4. LLM Response: {"action": "search", "difficulty": 10, "description": "..."}
+4. LLM Response: {"intent": "search_room", "target": "room"}
-5. Dice Roll: Player investigation vs difficulty
+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. Result Processing: Update game state based on success/failure
+6. State Update: The game state is updated based on the outcome (e.g., items are revealed).
-7. Response Generation: Narrative description of outcome
+7. Narrative Generation: A description of the outcome is generated and displayed to the player.
 ```
 
 ## Success Metrics
 
 ### MVP Completion Criteria
-- [ ] 3x3 map generates consistently
+- [ ] The 3x3 map generates consistently with varied rooms.
-- [ ] Player can move between rooms
+- [ ] The player can navigate between all rooms.
-- [ ] Items can be found and collected
+- [ ] Items can be discovered, collected, and used.
-- [ ] Basic commands work (look, search, take, use)
+- [ ] Core commands (look, search, take, use, move) are correctly parsed and executed.
-- [ ] Game state persists between sessions
+- [ ] The game state is successfully saved and loaded between sessions.
-- [ ] LLM provides coherent responses
+- [ ] The LLM provides coherent and contextually appropriate command interpretations.
-- [ ] Dice rolling affects outcomes
+- [ ] The dice rolling system influences the outcomes of actions.
 
 ### Quality Targets
-- Response time < 2 seconds for most commands
+- Command response time should be under 2 seconds.
-- No game-breaking bugs in core functionality
+- The core gameplay loop must be stable and free of crashes.
-- Consistent narrative voice and world logic
+- The narrative voice and world logic should remain consistent.
-- Clear feedback for all player actions
+- The UI must provide clear feedback for all player actions.
 
 ## Future Enhancements (Post-MVP)
 
-### Hybrid LLM Approach
+- **Hybrid LLM Approach**: Integrate cloud APIs for more complex narrative generation.
-- Cloud API for complex narrative generation
+- **Expanded Features**: Introduce larger maps, a combat system, character progression, and multiple scenarios.
-- Local LLM for fast command parsing
+- **Technical Improvements**: Migrate to a more advanced database, optimize performance, and refine prompt engineering techniques.
-- Fallback systems for offline play
+- **Visuals and Sound**: Add visual elements and sound effects to enhance the player experience.
-
-### 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
 
+### 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
+- Unit tests for core systems like `ActionResolver` and `StateManager`.
-- Integration tests for LLM responses
+- Integration tests for the full LLM command parsing pipeline.
-- Playtesting scenarios for game balance
+- Extensive playtesting to ensure game balance and a positive user experience.
-- Save/load integrity testing
+- Rigorous testing of the save/load functionality to ensure data integrity.
 
 ### Risk Mitigation
-- **LLM Reliability**: Fallback to rule-based parsing
+- **LLM Reliability**: Implement a fallback to a rule-based parser if the LLM fails.
-- **Performance**: Local processing with optimization
+- **Performance**: Profile and optimize code, especially the LLM interface and map generation.
-- **Complexity**: Modular design for incremental development
+- **Scope Creep**: Adhere strictly to the MVP features defined in this plan.
-- **Scope Creep**: Strict MVP focus with clear future roadmap
+- **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.*
+*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.*