# DSA 4.1 Helfer (PWA)

Offline-fähiger Spielerhelfer für **Das Schwarze Auge 4.1**. Verwaltet Helden lokal
im Browser (IndexedDB), berechnet abgeleitete Werte und unterstützt am Tisch beim
Fern- und Nahkampf sowie bei Zauberproben. Alles läuft als installierbare PWA
ohne Server – die Daten verlassen den Rechner nicht.

> Schwerpunkt liegt aktuell auf **Fernkampf mit dem Bogen**: die komplette
> Modifikatoren-Tabelle (Distanz, Sicht, Bewegung, Trefferzonen,
> Schussart/Nachladen, Wind, Steilschuss, Zielen, Scharf-/Meisterschütze) ist
> implementiert.

## Funktionen

### Heldenverwaltung
- Mehrere Helden parallel, lokal in IndexedDB gespeichert (`dsa-ranger`-DB via Dexie).
- Anlegen, Öffnen, Löschen direkt aus der Übersicht (`/`).
- **Export & Import** als JSON oder YAML (z. B. für Backup oder Austausch zwischen Geräten).
- Eingaben werden über [Zod](https://zod.dev) validiert; mitgelieferte
  `migrateCharacter`-Funktion hält Altdateien beim Import auf dem aktuellen
  Schema (`schemaVersion: 1`).

### Charakterbogen (`/characters/:id/sheet`)
- Stammdaten (Name, Rasse, Kultur, Profession).
- Eigenschaften MU/KL/IN/CH/FF/GE/KO/KK mit Startwert und Mod.
- Energien LeP/AsP/AuP/MR mit individuellem Mod-Feld; AsP optional aktivierbar.
- Talente und **Kampftalente** mit TaW sowie eigenen AT/PA-Werten; ein Helfer
  setzt AT/PA aus Basis + TaW neu.
- **Vorteile / Nachteile / Sonderfertigkeiten** aus typisierten Regeltabellen
  (mit Stufenwahl, wo vorgesehen).
- Inventarliste, Notizen (Freitext) und **Nahkampfwaffen-Instanzen** mit
  Talentbindung und AT-/PA-Modifikator.

### Übersicht (`/characters/:id`)
- Zeigt automatisch berechnete Basiswerte: **AT-, PA-, FK-, INI- und MR-Basis**
  sowie **LeP-, AsP- und AuP-Maximum**. Formeln nach DSA 4.1 inkl.
  Rassen-Modifikatoren (Mittelländer, Auelf, Zwerg, Ork, Achaz, …).

### Fernkampf-Rechner (`/characters/:id/combat/ranged`)
- Aktuell sechs Bögen modelliert: Elfen-, Komposit-, Krieg-, Kurz-, Lang-,
  Ork. Reiterbogen – inkl. Reichweiten, Bonusschaden je Distanz, Nachladezeit
  und KK-Anforderung.
- Berechnet die Zielzahl für 1W20 aus **FK-Basis + (wirksamem) TaW** und allen
  ausgewählten Erschwernissen:
  - Entfernung (sehr nah … extrem weit),
  - Zielgröße, Sichtverhältnisse, Bewegung des Ziels,
  - Trefferzone (Zwei- oder Vierbeiner),
  - Schussart / Nachladezustand (Pfeil auf Sehne, Bogen gespannt, gezielter Schuss, Schuss mit Ansage, Schnellschuss, Schnellladen),
  - Zielen über mehrere Kampfrunden,
  - Wind, Steilschuss nach oben/unten,
  - aktive Vorteile/Nachteile/SF (z. B. *Entfernungssinn*, *Talentspezialisierung Bogen*),
  - **Scharf-/Meisterschütze** modifiziert automatisch viele Werte (z. B. Trefferzonen, Schnellschuss, Schuss mit Ansage).
- Liefert pro Berechnung eine Aufschlüsselung aller Modifikatoren und einen
  Schadenshinweis inkl. Entfernungs-Bonus.

### Nahkampf-Rechner (`/characters/:id/combat/melee`)
- Liest AT/PA aus den Kampftalenten und addiert die Waffen-Modifikatoren der
  gewählten Nahkampfwaffe.
- Erschwernisse als kommaseparierte Liste plus eigene AT-/PA-Zusätze.
- Optional vereinfachte Ansagen-Verteilung (AT-Anteil auf PA).
- Manöver-Details (Wuchtschlag, Finte, Ausweichen …) bleiben bewusst generisch
  – am Tisch beziffern und eintragen.

### Magie (`/characters/:id/spells`)
- Liste eigener Zauber (Name, Stufe, ZfP-Notiz, Notiz) wird im Charakter
  gespeichert.
- Generische 3W20-Zielzahlen-Anzeige für eine wählbare Eigenschafts-Triade
  (Default MU/KL/CH) + ZfW.
- Optionale Liturgien-Freitextliste.

### Einstellungen & Hilfen
- `/settings`: Status des Helden-Software-Imports (noch nicht implementiert)
  und ein kleiner 1W20/3W20-Würfelhelfer.
- Online-/Offline-Anzeige in der Topbar, optionaler „Installieren“-Button im
  Browser, Service-Worker-Update über `@vite-pwa/sveltekit`.

## Technik

- **SvelteKit 2** + **Svelte 5** als SPA (`@sveltejs/adapter-static`,
  `fallback: 'index.html'`).
- **TypeScript** (strict).
- **Vite 6** + **`@vite-pwa/sveltekit`** (Service Worker, Web App Manifest).
- **Dexie** für IndexedDB (Charaktere und Meta-Tabelle für aktiven Helden).
- **Zod** für Schema-Definition & -Validierung.
- **js-yaml** für YAML-Export/-Import.
- **Vitest** + **fake-indexeddb** für Tests.

## Projektstruktur

```
src/
  routes/                      # SvelteKit-Routen (SPA)
    +layout.svelte             # Topbar, PWA-Registrierung, Online-Status
    +page.svelte               # Heldenübersicht (Anlegen/Import/Export)
    settings/+page.svelte      # Einstellungen + Würfelhelfer
    characters/[id]/
      +page.svelte             # Übersicht mit Basiswerten + Subnavigation
      sheet/+page.svelte       # Charakterbogen (Editor)
      combat/ranged/+page.svelte
      combat/melee/+page.svelte
      spells/+page.svelte
  lib/
    characters/                # Default-Charakter-Factory
    components/                # Shared Svelte-Komponenten (DiceRoller)
    engine/                    # Reine Berechnungen (derived, ranged, melee, spell, …)
    rules/                     # DSA-4.1-Regeltabellen (Rassen, Talente, Waffen, SF, …)
    schema/                    # Zod-Schemata + Schema-Versionierung
    storage/                   # Dexie-DB, Repository, JSON-/YAML-IO
    import/                    # Reservierter Helden-Software-Importer
tests/engine/                  # Unit-Tests (Vitest)
static/                        # Favicon, Manifest-Icons
scripts/                       # Hilfsskripte (Placeholder-Icons)
```

## Entwicklung

```bash
npm install
npm run icons   # Platzhalter-PNGs (für Produktion ersetzen)
npm run dev     # Vite-Dev-Server
```

## Tests, Lint & Build

```bash
npm test           # Vitest (einmalig)
npm run test:watch # Vitest im Watch-Mode
npm run check      # svelte-check + TypeScript
npm run lint       # ESLint
npm run format     # Prettier
npm run build      # Produktions-Build (statisch)
npm run preview    # Build lokal servieren
```

## Datenmodell (Kurz)

Der `Character` (siehe `src/lib/schema/character.ts`) enthält u. a.:

- `meta` (Name, Rasse, Kultur, Profession, optional Geschlecht/GP),
- `eigenschaften` (alle 8 Werte mit `startwert` + `mod`),
- `energien` (`lep`, `aup`, `mr`, optional `asp`, `kap`),
- `advantages`, `disadvantages`, `abilities` (jeweils mit `defId` auf den
  Regeleintrag),
- `talente` / `kampftalente`,
- `zauber`, `liturgien` (optional),
- `waffen.fernkampf` + `waffen.nahkampf` als Instanzen,
- `inventar`, `notizen`,
- `schemaVersion` (aktuell `1`).

Persistenz läuft ausschließlich über `src/lib/storage/repo.ts` – Komponenten
greifen nicht direkt auf die Dexie-Datenbank zu.

## Stand & bekannte Einschränkungen

- **Helden-Software-Import** ist noch ein Platzhalter
  (`src/lib/import/helden.ts`). JSON-/YAML-Import funktioniert.
- **Spell-Engine** ist bewusst minimal: 3W20-Zielzahlen für eine generische
  Eigenschafts-Triade. Verteilungen, Modifikatoren, Reichweite/Dauer-Berechnung
  noch nicht modelliert.
- **Nahkampf** liefert AT-/PA-Zielzahlen, kennt aber keine konkreten Manöver –
  Wuchtschlag, Finte usw. als Zahlen eingeben.
- Regeltabellen sind erweiterbar, aber nicht vollständig (z. B. Vorteile,
  SF, Nahkampfwaffen).
- Nur eine Schema-Version (`1`); zukünftige Migrationen über
  `migrateCharacter` in `src/lib/schema/version.ts`.
- Symbole unter `static/icons/` sind Platzhalter (`npm run icons`). Für eine
  Produktivversion eigene 192/512/maskable-PNGs hinterlegen.

## Hinweise für Mitwirkende

- Domain-Vokabular ist deutsch (`Eigenschaften`, `Talente`, `Sonderfertigkeiten`,
  `Vorteile`, `Nachteile`, `MU/KL/IN/CH/FF/GE/KO/KK`) und sollte so bleiben –
  bestehende Daten und Tests hängen daran.
- Architekturhinweise und Konventionen stehen in [`AGENTS.md`](./AGENTS.md).