From 90bb3b771b04f5673834c955f65f8c16aef878a1 Mon Sep 17 00:00:00 2001 From: aodhan Date: Thu, 24 Jul 2025 12:05:25 +0000 Subject: [PATCH] Upload files to "/" --- plan.md | 179 +++++++++++++++++++++++++++----------------------------- 1 file changed, 86 insertions(+), 93 deletions(-) diff --git a/plan.md b/plan.md index 24075ef..7b73101 100644 --- a/plan.md +++ b/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 -- Create Resource classes for game objects -- Implement basic map generation -- Build save/load functionality -- Create room templates and item placement +- **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**: 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 -- Local LLM setup (Ollama integration) -- Command parsing pipeline -- Basic game loop implementation +- **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**: 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 -- Room description generation -- Inventory and item management -- Command history and help system +- **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**: 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 -- Test scenarios and content -- Debugging and development tools -- LLM prompt optimization +- **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**: 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 -- Build packaging -- Documentation and setup guides +- **Task 17**: Perform final testing, fix bugs, and package the game for distribution with setup instructions. -**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 -- **Cons**: Limited querying, no concurrent access -- **Rationale**: Perfect for single-player MVP, can migrate later if needed +- **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**: Local LLM (Ollama) for offline play and fast responses -- **Future**: Hybrid approach with cloud APIs for advanced features -- **Benefits**: Privacy, reliability, cost control +- **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**: 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 +- **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 @@ -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 -- **Fallback**: Simple rule-based parser for development -- **Interface**: HTTP API calls to local server +- **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**: 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 +- **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: 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 +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 -- [ ] 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 +- [ ] 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 -- 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 +- 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 -- 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 +- **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 -- Integration tests for LLM responses -- Playtesting scenarios for game balance -- Save/load integrity testing +- 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**: 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 +- **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.* \ No newline at end of file +*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.*