# 🎮 Aether Chronicles — LLM-Powered Browser RPG

A browser-based RPG inspired by classic isometric MMORPGs, with a unique twist: an LLM acts as a "Dungeon Master" that generates dynamic events, NPC dialogues, and world variations — while core gameplay remains stable and never soft-locks the player.

## Concept

```
Browser (HTML5 Canvas + JS)  ←→  Python Backend (FastAPI)  ←→  Ollama LLM
```

- **Frontend:** HTML5 Canvas, JavaScript, isometric tilemap
- **Backend:** Python FastAPI, SQLite for game state
- **LLM:** Local Ollama (gemma4:12b) for dynamic content generation

## Design Pillars

1. **Fix Core, Dynamic Periphery** — Main cities, NPCs, and story quests are fixed. LLM only modifies optional content.
2. **Never Soft-Lock** — LLM events are validated by the backend. If invalid → silently discarded. Player always progresses.
3. **RO-Style Combat** — Click-to-move, click enemy to auto-attack, skill bar, HP/SP bars.
4. **Progression** — Base class → 1st class → 2nd class with branching skills.

## Class System

### Base Class
- **Wanderer** (Novice equivalent)

### 1st Class (Level 10+)
| Class | Role | Weapon |
|---|---|---|
| Klingenwächter | Tank/Melee | Sword+Shield |
| Pirschjäger | Ranged DPS | Bow/Crossbow |
| Runenweber | Magic DPS | Staff/Talisman |
| Lebensfaden | Healer/Support | Holy Symbol |
| Schattengänger | Assassin/Burst | Daggers |
| Handelsreisender | Utility/Merchant | All |

### 2nd Class (Level 40+)
| 1st → 2nd | New Abilities |
|---|---|
| Klingenwächter → Schildwache | AoE Tank, Taunt |
| Pirschjäger → Sturmpfeil | Multi-Shot, Pet |
| Runenweber → Elementarist | Chain Spells |
| Lebensfaden → Seelenbinde | AoE Heal, Revive |
| Schattengänger → Nachtzahn | Shadow Combo |
| Handelsreisender → Gildenmeister | Trade Posts, NPC Hire |

## World

### Fixed Cities (LLM cannot modify)
| City | Theme | Function |
|---|---|---|
| Eichenhafen | Harbor/Start | Tutorial, Base Classes |
| Sonnenfeld | Trade Hub (Central) | Market, Guild Master |
| Nebelgipfel | Mountain Fortress | Advanced Classes, Endgame |

### Dynamic Content (LLM-generated, validated)
- Weather effects (rain → fire magic -10%)
- Optional side quests ("Caravan under attack")
- NPC dialogue variations (personality-based)
- Monster variants ("Cursed Emerald Wolf" vs normal Wolf)
- Side-dungeon layouts
- Rare events (world boss, meteor, merchant caravan)

### LLM Safety Rules
```
1. NPC locations are NEVER moved
2. Main roads are NEVER blocked
3. Quest NPCs are ALWAYS accessible
4. Dynamic events are ALWAYS optional
5. Side-dungeon can change → main dungeon stays fixed
6. Monster spawns dynamic but minimum 3 normal monsters per map
7. If LLM output fails validation → silently discarded, map stays normal
```

## Milestones

| # | Milestone | Status |
|---|---|---|
| M1 | Project Setup + HTML5 Canvas + Tilemap | Pending |
| M2 | Click-to-Move Pathfinding (A*) | Pending |
| M3 | Player Stats + UI (HP/SP, Skill Bar) | Pending |
| M4 | Combat System (Click → Auto-Attack) | Pending |
| M5 | Monster Spawning + Basic AI | Pending |
| M6 | First City + NPCs + Merchant | Pending |
| M7 | LLM Integration (Ollama) | Pending |
| M8 | Quest System | Pending |
| M9 | Inventory + Equipment | Pending |
| M10 | Class System + Skills | Pending |

## Tech Stack

| Component | Technology |
|---|---|
| Frontend | HTML5 Canvas, vanilla JS, CSS |
| Backend | Python 3.11, FastAPI, uvicorn |
| Database | SQLite |
| LLM | Ollama (gemma4:12b local) |
| Assets | OpenGameArt, ComfyUI-generated sprites |

## Running

```bash
# Backend
cd backend
python3 -m venv venv
source venv/bin/activate
pip install fastapi uvicorn ollama
uvicorn main:app --reload --port 8000

# Frontend
# Open frontend/index.html in browser
```

## License

MIT