aether-chronicles/README.md

🎮 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

# 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