# 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