commit aaf807a757272c4ce492652773239f645e9b868f Author: aodhan Date: Thu Jul 24 11:32:28 2025 +0000 Upload files to "/" diff --git a/actions.md b/actions.md new file mode 100644 index 0000000..4af04de --- /dev/null +++ b/actions.md @@ -0,0 +1,14 @@ +# Game Actions + +| Action | Description | Effect | Command Format | +|-------------|-------------|--------|-----------------| +| Look | Look around the current room | Descriptive text | look | +| Search | Search the current room for items | Descriptive text | search | +| Take | Pick up an item from the current room | Item is added to inventory | take {item name} | +| Use | Use an item from the inventory | Item is used | use {item name} [on {target}] | +| Drop | Drop an item from the inventory | Item is removed from inventory | drop {item name} | +| Inventory | Display the player's inventory | List inventory | inventory | +| Examine | Examine an item in the inventory | Descriptive text | examine {item name / target} | +| Move | Move to a different room | Room change | move {direction} | +| Attack | Attack an enemy | Damage dealt | attack {target} | +| Hide | Hide from an enemy | Enemy is blinded | hide {target} | diff --git a/plan.md b/plan.md new file mode 100644 index 0000000..24075ef --- /dev/null +++ b/plan.md @@ -0,0 +1,261 @@ +# 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: Dictionary (investigation, strength, dexterity, etc.) +│ ├── 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] +├── 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: Dictionary +├── usable: bool +└── hidden: bool +``` + +### 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 + +- 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 + +**Deliverable**: Functional game world that can be saved and loaded + +### Phase 2: Game Logic (Tasks 6-9) +**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 + +**Deliverable**: Working game that can process simple commands + +### Phase 3: User Interface (Tasks 10-12) +**Goal**: Complete text-based interface + +- Text UI for game interaction +- Room description generation +- Inventory and item management +- Command history and help system + +**Deliverable**: Playable game with full text interface + +### Phase 4: Content & Polish (Tasks 13-16) +**Goal**: Rich gameplay experience + +- Action resolution with consequences +- Test scenarios and content +- Debugging and development tools +- LLM prompt optimization + +**Deliverable**: Polished MVP ready for testing + +### Phase 5: Package & Deploy (Task 17) +**Goal**: Distributable game build + +- Final testing and bug fixes +- Build packaging +- Documentation and setup guides + +**Deliverable**: Complete 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 + +### 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 + +### 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 + +## 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 +├── 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 Llama 3.1 or similar +- **Fallback**: Simple rule-based parser for development +- **Interface**: HTTP API calls to local 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 + +### 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 +``` + +## 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 + +### 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 + +## 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 + +## Development Notes + +### Testing Strategy +- Unit tests for core systems +- Integration tests for LLM responses +- Playtesting scenarios for game balance +- Save/load integrity testing + +### 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 + +--- + +*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