Initial MVP

docs/vibecoding/Architecture.md

@@ -0,0 +1,112 @@
+# Storyteller - Technical Architecture
+
+## 1. System Overview
+
+The game follows a **Client-Server** model where the Godot game client acts as the frontend and state manager, while the LLM (via OpenRouter) acts as the narrative engine and intent parser.
+
+```mermaid
+graph TD
+    User[User Input] -->|Text| UI[UI Layer]
+    UI -->|Signal| GM[GameManager]
+    GM -->|Context + Input| LLM[LLM Service]
+    LLM -->|OpenRouter API| Cloud[AI Model]
+    Cloud -->|JSON Response| LLM
+    LLM -->|Parsed Action| GM
+    GM -->|Update| State[GameState]
+    State -->|Signal| UI
+    State -->|Signal| Visuals[Visual/Audio System]
+```
+
+## 2. Core Components
+
+### 2.1 LLM Service (`LLMService.gd`)
+*   **Responsibility:** Handles HTTP requests to OpenRouter.
+*   **Pattern:** Adapter pattern to allow future swapping to local LLM (Ollama).
+*   **Key Functions:**
+    *   `send_prompt(system_prompt: String, user_input: String) -> Dictionary`
+    *   `_parse_json(response: String) -> Dictionary`
+*   **Configuration:** API Key stored in `user://secrets.cfg` (not in version control).
+
+### 2.2 Game Manager (`GameManager.gd`)
+*   **Responsibility:** Central coordinator.
+*   **Logic:**
+    1.  Receives user text.
+    2.  Constructs a prompt including:
+        *   Current Room Description.
+        *   Visible Items/Enemies.
+        *   Player Inventory.
+        *   Valid Actions (Rules).
+    3.  Sends to `LLMService`.
+    4.  Executes the returned Action (e.g., `move_player`, `pickup_item`, `start_combat`).
+
+### 2.3 State Manager
+*   **Responsibility:** Single source of truth.
+*   **Implementation:** Godot `Resource` based system for easy saving/loading.
+
+## 3. Data Architecture
+
+### 3.1 Game State (`GameState.gd` - Resource)
+```gdscript
+class_name GameState extends Resource
+
+@export var current_room_id: String
+@export var player_hp: int
+@export var player_max_hp: int
+@export var inventory: Array[ItemData] # List of Item Resources
+@export var world_flags: Dictionary # For tracking puzzle states
+```
+
+### 3.2 Room Data (`RoomData.gd` - Resource)
+```gdscript
+class_name RoomData extends Resource
+
+@export var id: String
+@export var name: String
+@export var description: String # Base description for LLM context
+@export var image_path: String # Path to static background
+@export var exits: Dictionary # { "north": "room_id_2", ... }
+@export var items: Array[ItemData]
+@export var enemies: Array[EnemyData]
+```
+
+### 3.3 LLM Protocol (JSON Structure)
+The LLM will be instructed to return JSON in this format:
+```json
+{
+  "narrative": "You step into the dark cave. The air is damp...",
+  "action": {
+    "type": "MOVE",
+    "target": "north"
+  },
+  "state_changes": {
+    "player_hp": -5
+  }
+}
+```
+
+## 4. Core Systems
+
+### 4.1 Navigation (The 4x4 Grid)
+*   **Map:** A 4x4 grid of `RoomData` resources.
+*   **Minimap:** A UI GridContainer that highlights the `current_room_id`.
+*   **Movement:** Validated against `RoomData.exits`.
+
+### 4.2 Combat System (Dragon Quest Style)
+*   **Trigger:** When `action.type == "COMBAT"` or player encounters an enemy.
+*   **View:** Switches Main Display to "Combat Mode" (Enemy sprite front & center).
+*   **Flow:**
+    1.  **Player Turn:** Choose Attack/Item/Flee.
+    2.  **Resolution:** Calculate damage (Simple: `Atk - Def`).
+    3.  **Enemy Turn:** Enemy attacks player.
+    4.  **Loop:** Until HP <= 0.
+*   **LLM Role:** Describes the combat moves ("You swing your sword...", "The slime wobbles aggressively..."), but the *math* is handled by Godot.
+
+### 4.3 Inventory
+*   **Data:** Array of `ItemData` resources.
+*   **UI:** List of items. Clicking an item adds "Use [Item Name]" to the input field or triggers a context menu.
+
+## 5. Tech Stack
+*   **Engine:** Godot 4.2+
+*   **Language:** GDScript
+*   **AI Provider:** OpenRouter (Model: `google/gemini-2.0-flash-exp` or `meta-llama/llama-3-8b-instruct` for speed/cost).
+*   **Version Control:** Git

docs/vibecoding/NOTES.txt

@@ -0,0 +1 @@
+Place all your vibe coding docs in here, that includes sample data, TODOs, and other notes. README.md and other user tailored docs go in the root docs folder.

docs/vibecoding/ProjectPlan.md

@@ -0,0 +1,71 @@
+# Storyteller - Project Plan
+
+## Phase 1: Foundation (The Grid & State)
+**Goal:** A walkable 4x4 grid with state persistence, without AI or fancy graphics.
+
+*   [ ] **Setup:** Initialize Git, Godot Project (Done).
+*   [ ] **Data Structures:** Create `RoomData`, `ItemData`, `GameState` resources.
+*   [ ] **Map Creation:** Create 16 `RoomData` assets representing the 4x4 grid. Link them via exits.
+*   [ ] **Game Manager:** Implement `GameManager` to handle `move(direction)` logic.
+*   [ ] **Debug UI:** Simple text label showing "Current Room: [Name]" and buttons for N/S/E/W.
+*   [ ] **State Management:** Implement Save/Load functionality for `GameState`.
+
+**Testing:**
+*   Verify player can navigate all 16 rooms correctly.
+*   Verify walls (invalid exits) block movement.
+*   Verify state persists after restarting the game.
+
+## Phase 2: The Brain (AI Integration)
+**Goal:** Replace hardcoded text with LLM-generated narrative and parsing.
+
+*   [ ] **LLM Service:** Implement `LLMService.gd` with HTTPRequest node.
+*   [ ] **API Integration:** Connect to OpenRouter (test with `curl` first, then Godot).
+*   [ ] **Prompt Engineering:** Design the System Prompt to enforce JSON output.
+*   [ ] **Input Parsing:** Connect User Input Field -> `GameManager` -> `LLMService`.
+*   [ ] **Action Handling:** Parse returned JSON to trigger `move_player` or `get_item`.
+
+**Testing:**
+*   Verify LLM returns valid JSON.
+*   Verify "Go North" results in `{"type": "MOVE", "target": "north"}`.
+*   Verify narrative text is displayed in the UI.
+
+## Phase 3: The Body (Visuals & UI)
+**Goal:** Implement the "Myst-style" visuals and proper UI layout.
+
+*   [ ] **Layout:** Create the Main Scene with `TextureRect` (Background), `RichTextLabel` (Log), `LineEdit` (Input), and `GridContainer` (Minimap).
+*   [ ] **Minimap:** Implement a dynamic 4x4 grid that highlights the current room.
+*   [ ] **Asset Import:** Import placeholder images for rooms.
+*   [ ] **Dynamic Backgrounds:** Update `TextureRect` when changing rooms based on `RoomData.image_path`.
+
+**Testing:**
+*   Verify background changes on room entry.
+*   Verify minimap updates correctly.
+*   Verify text log scrolls properly.
+
+## Phase 4: The Conflict (Combat & Items)
+**Goal:** Add gameplay depth with Inventory and Combat.
+
+*   [ ] **Inventory System:** Implement `pickup_item` and `use_item`. Update UI to show inventory.
+*   [ ] **Combat UI:** Create a separate Control node for Combat (Enemy Sprite, HP Bars, Action Buttons).
+*   [ ] **Combat Logic:** Implement turn-based logic (Player Attack -> Calc Dmg -> Enemy Attack -> Calc Dmg).
+*   [ ] **LLM Combat:** Update System Prompt to handle combat narration ("You strike the goblin!").
+
+**Testing:**
+*   Verify items can be picked up and removed from the room.
+*   Verify combat loop ends correctly (Win/Loss).
+*   Verify HP updates correctly.
+
+## Phase 5: Polish & Juice
+**Goal:** Audio, effects, and refinement.
+
+*   [ ] **Audio Manager:** Add background music and SFX (footsteps, hits).
+*   [ ] **Feedback:** Add screen shake on damage, text typing effect.
+*   [ ] **Bug Fixing:** Edge case handling (LLM hallucinations, invalid JSON).
+
+## MVP Checklist
+*   [ ] 4x4 Navigable Grid
+*   [ ] LLM Narrative Generation
+*   [ ] JSON Action Parsing
+*   [ ] Basic Inventory (Pickup/Use)
+*   [ ] Turn-based Combat (1 Enemy Type)
+*   [ ] Save/Load System

docs/vibecoding/The-Big-Idea.md

@@ -0,0 +1,32 @@
+# Storyteller - Brain Storming Session
+
+## What I Want You To Do
+
+Hello my helpful assistant. Please follow these rules and guidelines during this brain storming session.
+
+Your role:
+ - You are a senior software engineer with 15 years of experience.
+ - You are a senior game designer with 10 years of experience.
+ - You are a senior AI engineer with 5 years of experience.
+ - Assume the reader is a coder but new to Godot and game development more broadly.
+ - Ask questions frequently.
+ - Do not make assumptions.
+ - Do not make decisions without asking for clarification.
+
+The Goal:
+ - A comprehensive project plan with detailed architecture and solid reasoning for all decisions made.
+ - The plan is for a solid MVP that demonstrates the core functionality of the game as laid out in the initial concept.
+ - A comprehensive testing plan for each phase of the project.
+
+## The Big Idea
+
+A text adventure that uses an AI language model to generate the action. The user is still bound by rules of the game, such as a combat system and inventory etc, but the actions described are handles by the LLM. The same system is also used to turn user dialog into actions the game can take. A graphical component is used to display the game state and allow the user to interact with the game. An audio component is used to provide sound effects and music. The use of a game state should allow for consistent descriptions of items and locations.
+
+What should the MVP demonstrate?
+ - A core gameplay loop.
+ - Text parsing and generation.
+ - A 4X4 room grid that the user can navigate.
+ - Items that can be picked up and used.
+ - Graphical and audio feedback for actions.
+ - Inventory system.
+ - Basic combat system.