aodhan/simple-adventure
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Upload files to "/"

Browse Source
This commit is contained in:
aodhan
2025-07-24 12:05:25 +00:00
parent aaf807a757
commit 90bb3b771b
1 changed files with 86 additions and 93 deletions
Download Patch File Download Diff File Expand all files Collapse all files

177
plan.md
View File

@@ -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,77 +186,68 @@ 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.
---