Upload files to "/"

2025-07-24 11:32:28 +00:00
commit aaf807a757
2 changed files with 275 additions and 0 deletions
--- a/actions.md
+++ 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}    |
--- a/plan.md
+++ 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.*