113 lines
3.8 KiB
Markdown
113 lines
3.8 KiB
Markdown
# 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
|