# The Last Chronicle (TLC) — Vollständige Projektdokumentation

## Überblick
The Last Chronicle ist ein **Dark Fantasy Roguelite** als browserbasiertes Single-Page Game. Drei Helden — ein Söldner, eine Blutmagierin und eine Chronistin — ziehen durch eine düstere Welt, kämpfen rundenbasiert, treffen Entscheidungen in Story-Events und bauen ein Dorf auf. Das Spiel hat einen handschriftlich-literarischen Ton, inspiriert von Darkest Dungeon, Slay the Spire und Disco Elysium.

**Live:** https://thelastchronicle.com
**Server:** 157.180.43.9 (Hetzner VPS, Ubuntu 24.04, User: coob)

---

## Tech Stack

- **React 19** + Vite 6
- **Framer Motion** für Animationen
- **useReducer** + **localStorage** als State Management (kein Redux)
- Kein CSS-Framework — alle Styles in `.css`-Dateien
- Kein Backend — reines Client-Side Game
- Save: `localStorage` unter Key `tlc_save_v2`

### Source & Build
- **Source:** `/home/coob/chronicle-src/`
- **Dist:** `/home/coob/chronicle-src/dist/` → served via Caddy auf `thelastchronicle.com`
- **Build:** `cd /home/coob/chronicle-src && npm run build`
- **Node:** v18

---

## Architektur

### Kern-Dateien

```
src/
  engine/
    gameData.js     — Statische Daten: Heroes, Skills, Enemies, Locations, Events, Scars, Relics, Banter
    gameStore.js    — useReducer State Machine, alle Spiellogik, Persistence
  screens/
    TitleScreen.jsx   — Titelbildschirm mit New Game / Continue
    VillageScreen.jsx — Dorfansicht mit Buildings, Hero-Panels, Level-Up
    WorldScreen.jsx   — Weltkarte mit freigeschalteten Missionen
    StoryScreen.jsx   — Story-Events mit Branching Choices
    CombatScreen.jsx  — Rundenbasierter Kampf
    LootScreen.jsx    — Belohnungsansicht nach Sieg
    BanterScreen.jsx  — Dialog-Szenen zwischen den Helden
  styles/
    global.css        — Basisstyles, Fonts, Dark Theme
    title.css         — Titelbildschirm
    village.css       — Dorf, XP-Bars, Level-Up, Buildings
    world.css         — Weltkarte
    story.css         — Story-Events
    combat.css        — Kampf-UI
    loot.css          — Loot-Ansicht mit Relic-Drops
    banter.css        — Dialog-Szenen
  App.jsx             — Screen Router (switch auf state.screen)
  main.jsx            — React Entry Point
```

### State Flow

1. `App.jsx` nutzt `useGameStore()` Hook
2. Hook gibt `{ state, actions }` zurück
3. `state.screen` bestimmt welcher Screen gerendert wird
4. Screens dispatchen Actions über `actions.*`
5. Reducer in `gameStore.js` berechnet neuen State
6. State wird bei jeder Änderung in `localStorage` persistiert (außer auf Title Screen)

### Screen Flow

```
Title → Village → World Map → Story Event → Combat → Loot → [Banter] → Village
                                    ↑                           |
                                    └───────────────────────────┘
                               (bei Niederlage: direkt zurück zu Village)
```

---

## Die drei Helden

### The Mercenary (Söldner)
- **Titel:** Iron Convention Deserter
- **Zone:** `player_front` (Frontlinie)
- **Stats:** HP 90, Wucht 6, Finesse 3, Essenz 2
- **Rolle:** Tank / Melee DPS
- **Skills:**
  - **Iron Blow** (Cost 0) — Einzelangriff: `wucht * 2.2 + 4` Schaden, nur Front-Feinde
  - **Shield Wall** (Cost 1) — Buff: -4 Schadensreduktion für 1 Runde
  - **Brotherly Cover** (Cost 2) — Taunt: Leitet nächsten Angriff auf einen Verbündeten auf sich um
- **Lore:** "Steel and silence. He fights for coin and something he refuses to name."

### The Blood Mage (Blutmagierin)
- **Titel:** Sanguine Circle Exile
- **Zone:** `player_rear` (Hintere Reihe)
- **Stats:** HP 65, Wucht 2, Finesse 4, Essenz 7
- **Rolle:** Caster / Healer
- **Skills:**
  - **Blood Pact** (Cost 0) — Einzelangriff: `essenz * 2.0 + 2` Schaden auf beliebigen Feind, -3 eigene HP
  - **Coagulate** (Cost 1) — Einzelheilung: `essenz * 1.5 + 5` HP
  - **Tainted Heal** (Cost 2) — Gruppenheilung: `essenz * 1.2 + 3` HP für alle Verbündeten
- **Lore:** "She drinks the pain of others and makes it useful."

### The Chronicler (Chronistin)
- **Titel:** Silent Archivist Runaway
- **Zone:** `player_rear` (Hintere Reihe)
- **Stats:** HP 55, Wucht 2, Finesse 8, Essenz 3
- **Rolle:** Controller / Debuffer
- **Skills:**
  - **Marginalia** (Cost 1) — Kontrolle: Verschiebt einen Feind 2 Positionen in der Initiative zurück
  - **Scar Prophecy** (Cost 0) — Einzelangriff: `finesse * 1.8 + 2` Schaden + -2 Wucht auf Ziel
  - **Ink Trauma** (Cost 2) — Flächenangriff: `finesse * 1.2 + 1` Schaden auf alle Feinde
- **Lore:** "She writes futures that have not happened yet. Most of them are wrong. Most."

---

## Kampfsystem

### Initiative
- Alle Einheiten (Helden + Feinde) werden nach Finesse sortiert (höchste zuerst)
- Rundenbasiert: Wer dran ist, wählt einen Skill und ein Ziel
- Tote Einheiten werden übersprungen (`advanceInitiative` Helper)

### Zones
- `player_front` — Mercenary steht hier, kann von Front-Attacken getroffen werden
- `player_rear` — Blood Mage & Chronicler, nur von "any"-Attacken erreichbar
- `enemy_front` — Nahkämpfer-Feinde
- `enemy_rear` — Fernkämpfer-Feinde

### Mechaniken
- **Defending:** Shield Wall gibt `defending: N` — reduziert nächsten eingehenden Schaden um N, wird am Start des eigenen Zugs zurückgesetzt
- **Taunt (coveredBy):** Brotherly Cover setzt `coveredBy: actorId` auf den beschützten Verbündeten — nächster Angriff auf diesen wird zum Beschützer umgeleitet
- **Rally:** Bone Captain kann alle lebenden Feinde +1 Wucht geben
- **Weaken:** Scar Prophecy reduziert Wucht des Ziels um 2
- **Delay:** Marginalia verschiebt Feind in der Initiative-Reihenfolge nach hinten

### Schaden & Skalierung
- Jeder Skill hat eine `damage(stat)` Funktion
- Der verwendete Stat hängt vom Skill ab (Wucht für Melee, Essenz für Magie, Finesse für Chronicler)
- Feinde nutzen `ENEMY_SKILLS` mit AI-Typ-basierter Zielauswahl:
  - `aggressive` — Greift bevorzugt Front-Helden an
  - `ranged` / `caster` — Greift den Helden mit niedrigsten HP an
  - `leader` — Hat Chance auf Rally (30%), sonst Heavy Strike

### Blood Ink als Skill-Währung
- Skills kosten 0-2 Blood Ink
- Blood Ink wird im Kampf verbraucht und über Loot/Events nachgefüllt

### Scars & Tod
- Held auf 0 HP → erhält einen zufälligen **Scar** (permanenter Stat-Bonus!) und überlebt mit 1 HP
- 3. Scar → Held stirbt permanent (`dead: true`)
- Feinde auf 0 HP → einfach tot

### Sieg & Niederlage
- **Sieg:** Alle Feinde tot → `COMBAT_VICTORY` → Loot Screen
- **Niederlage:** Alle Helden tot → `COMBAT_DEFEAT` → Zurück ins Dorf mit 30% HP

---

## Feinde (8 Typen)

| ID | Name | Zone | HP | Wucht | Finesse | Essenz | AI | XP |
|---|---|---|---|---|---|---|---|---|
| skeleton_grunt | Skeleton Grunt | front | 22 | 4 | 2 | 0 | aggressive | 8 |
| skeleton_archer | Skeleton Archer | rear | 16 | 3 | 4 | 0 | ranged | 10 |
| bone_captain | Bone Captain | front | 45 | 6 | 3 | 0 | leader | 30 |
| iron_footman | Iron Footman | front | 30 | 5 | 3 | 1 | aggressive | 12 |
| blood_cultist | Blood Cultist | rear | 20 | 2 | 3 | 6 | caster | 15 |
| hollow_wraith | Hollow Wraith | rear | 18 | 2 | 6 | 4 | ranged | 14 |
| plague_hound | Plague Hound | front | 14 | 5 | 7 | 0 | aggressive | 6 |
| archive_golem | Archive Golem | front | 55 | 7 | 1 | 3 | leader | 25 |

### Enemy Skills (6)
- **Slash** (basic_attack) — `wucht * 1.5 + 2`, Front only
- **Arrow** (arrow_shot) — `wucht * 1.4 + 1`, Any
- **Heavy Strike** — `wucht * 2.2 + 4`, Front only
- **Rallying Cry** (rally) — Alle Feinde +1 Wucht
- **Blood Bolt** — `essenz * 1.8 + 3`, Any
- **Spectral Touch** — `essenz * 1.5 + 2`, Any

---

## Welt & Missionen (7 Locations)

### Progression
Locations werden freigeschaltet basierend auf `missionsCompleted`:

| Location | Region | Requires | Enemies |
|---|---|---|---|
| Ruined Chapel | The Pale Moors | 0 | 2x Skeleton Grunt |
| Sunken Village | The Drowned Roads | 0 | Skeleton Grunt + Archer |
| The Iron Crossing | Convention Frontier | 0 | 2x Iron Footman + Archer |
| The Bleeding Grotto | Sanguine Depths | 0 | 2x Blood Cultist + Wraith |
| The Bone Fortress | Northern Wastes | 2 | Grunt + Archer + Bone Captain |
| Archive of Whispers | The Quiet Reaches | 3 | 2x Wraith + Archive Golem |
| The Crimson Spire | Heart of the Wound | 5 | Cultist + 2x Plague Hound + Bone Captain |

### Jede Mission hat:
- 2 Story Events (zufällig eines beim Betreten)
- 1 Combat Encounter
- Ink + XP Rewards (ranges)

---

## Story Events (14 Events)

Jedes Event hat:
- **title** + **text** — Narrative Beschreibung mit Dialog
- **choices** (2-3) — Jede Choice hat:
  - `label` — Button-Text
  - `consequence` — Beschreibung des Ergebnisses
  - `effect` — Mechanischer Effekt (beliebige Kombination von):
    - `ink` — +/- Blood Ink
    - `xpAll` — XP für alle Helden
    - `faction` — Fraktions-Standing ändern
    - `worldTag` — Persistentes Flag für die Welt
    - `heroStat` — Permanenter Stat-Boost für bestimmten Helden
    - `heroDamage` — Schaden an bestimmten Helden
    - `allStats` — +N auf alle Stats aller Helden
    - `combat` — Leitet direkt in den Kampf über
    - `lostPage` — Sammelt eine verlorene Seite
    - `villager` — Rettet einen Dorfbewohner

### Fraktionen
- **Iron Convention** — Militärorden, der Söldner kommt von dort
- **Sanguine Circle** — Blutmagier-Kult, die Blutmagierin kommt von dort
- **Silent Archivists** — Wissenshüter, die Chronistin kommt von dort

Fraktions-Standing (0-100) beeinflusst Story-Optionen.

---

## Village (Dorf-System)

### The Chronicle's Hold
Das Dorf ist der Hub zwischen Missionen:

#### Buildings
- **Tavern** (Level 1+) — Heilt die gesamte Party. Kosten: 2 Blood Ink
- **Runeforge** — Zeigt gesammelte Relics an
- **Scriptorium** — Zeigt Scars aller Helden an
- **Blood Altar** — Zwei Funktionen:
  - **XP Ritual:** 5 Blood Ink → +30 XP für alle Helden
  - **Sacrifice Relic:** Opfert ein Relic → +3 Blood Ink

#### Hero Panels
- Zeigen HP-Bar, Level, XP-Fortschritt
- Bei verfügbaren Stat-Points: Level-Up Buttons (+1 Wucht, +1 Finesse, +1 Essenz, +5 HP)
- Tab-Notification wenn unausgegebene Punkte vorhanden

#### Resource Bar
- Blood Ink (Hauptressource)
- Relics (Anzahl)
- Bond (Gesamte Bond-Punkte)
- Lost Pages (gesammelt)

---

## Level-Up System

- Helden bekommen XP durch Kampf und Events
- XP-Schwelle: `xpToNext` startet bei 100, steigt um 25% pro Level
- Bei Level-Up: +1 Stat Point
- Stat Points können vergeben werden auf:
  - **Wucht** (+1)
  - **Finesse** (+1)
  - **Essenz** (+1)
  - **HP** (+5 Max HP, sofort geheilt)
- Max Level: 20

---

## Relics (12 Stück)

Relics droppen nach Kampf-Sieg (40% Chance, kein Duplikat):

| Relic | Stat | Bonus |
|---|---|---|
| Rusted Insignia | Wucht | +1 |
| Vial of Echoes | Essenz | +1 |
| Thief's Needle | Finesse | +1 |
| Bone Shield | Max HP | +8 |
| Crimson Quill | Essenz | +2 |
| Ironbark Gauntlet | Wucht | +2 |
| Shadow Cloak | Finesse | +2 |
| Heart of the Hold | Max HP | +15 |
| Blood Compass | Finesse | +1 |
| Shattered Halo | Essenz | +1 |
| Warhorn Shard | Wucht | +1 |
| Petrified Tear | Max HP | +5 |

**Relic-Bonuses werden im Kampf auf alle Helden angewendet** (additiv) und im Village-Hub als permanente Buffs betrachtet.

Relics können am Blood Altar geopfert werden für +3 Blood Ink.

---

## Scars (8 Stück)

Scars sind permanente Narben die ein Held erhält wenn er auf 0 HP fällt:

| Scar | Stat | Bonus |
|---|---|---|
| Abyssal Eye | Finesse | +2 |
| Iron Fist | Wucht | +2 |
| Ink Veins | Essenz | +1 |
| Hollow Chest | Max HP | +10 |
| Split Tongue | Finesse | +3 |
| Burned Hand | Wucht | +2 |
| Third Eye | Essenz | +2 |
| Stone Knee | Max HP | +8 |

- 1. und 2. Scar: Held überlebt mit 1 HP + bekommt den Stat-Bonus
- 3. Scar: Held stirbt permanent

---

## Banter System (8 Szenen)

Nach Kampf-Sieg wird zufällig eine ungesehene Banter-Szene gepickt:

| Scene | Title | Bond |
|---|---|---|
| banter_tactics | On Tactics | +1 |
| banter_names | What We Call Each Other | +1 |
| banter_hold | This Place We Built | +1 |
| banter_scars | On Scars | +1 |
| banter_trust | Trust | +2 |
| banter_fear | What We Fear | +2 |
| banter_cooking | Dinner | +1 |
| banter_factions | Old Allegiances | +2 |

- Banter-Szenen sind Dialoge zwischen den drei Helden (tap-to-advance)
- Jede Szene gibt Bond-Punkte
- Bond ist eine globale Ressource (kein aktueller mechanischer Effekt, prepared for future content)

---

## Save System

- **Auto-Save:** Bei jeder State-Änderung (außer Title Screen) in `localStorage`
- **Key:** `tlc_save_v2`
- **Transiente Daten** werden nicht gespeichert: `combat`, `currentEvent`, `toast`, `pendingBanter`
- **Continue** auf Title Screen: Lädt Save und geht direkt ins Village
- **New Game:** Setzt alles zurück auf Default State

---

## Visuelles Design

- **Theme:** Dark Fantasy, handschriftlich-literarisch
- **Farben:** Dunkler Hintergrund (#0a0a0f), Gold-Akzente, Blutrot
- **Fonts:** (über Google Fonts oder ähnlich)
- **Portraits:** Aktuell Placeholder-Bilder in `/public/assets/`
- **Stil:** Gothic, düster, text-heavy

### Assets (`/public/assets/`)
- `soeldner.jpg` — Mercenary Portrait
- `bloodmage.jpg` — Blood Mage Portrait
- `camp.jpg` — Chronicler Portrait / Fallback
- `skeleton.jpg` — Skeleton/Undead Enemy Portrait
- `tavern.jpg` — Tavern / Indoor Scenes
- `world.jpg` — World Map / Outdoor Scenes
- Weitere Placeholder-Assets für Locations

---

## Caddy-Konfiguration

```
thelastchronicle.com, www.thelastchronicle.com {
  root * /home/coob/chronicle-src/dist
  file_server
  try_files {path} /index.html
}
```

---

## Offene Aufgaben / Nächste Schritte

- [ ] Eigene Portraits für alle Helden und Feinde (AI-generiert)
- [ ] Eigene Location-Bilder für jede Region
- [ ] Sound Design (Kampf, UI, Ambient)
- [ ] Village visuell ausbauen (Gebäude-Illustrationen)
- [ ] Mehr Feindtypen und Boss-Encounters
- [ ] Season/Chapter System (narrativer Fortschritt)
- [ ] Bond-System mechanisch nutzen (z.B. Combo-Skills bei hohem Bond)
- [ ] Lost Pages als Meta-Progression
- [ ] Mobile-Optimierung
- [ ] PWA / Offline-Modus
- [ ] Achievements / Unlockables
