update readme

2026-05-16 21:51:04 +02:00
parent 97ba4bf478
commit 260b7b0529
1 changed files with 158 additions and 15 deletions
@@ -1,31 +1,174 @@
 # DSA 4.1 Helfer (PWA)

-Offline-fähiger Spielerhelfer für **Das Schwarze Auge 4.1**: Bogen, Fernkampf-Zielzahlen, Nahkampf, Zauberliste, lokaler Speicher (IndexedDB), Export/Import als JSON oder YAML.
+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 (optional ersetzen)
-npm run dev
+npm run icons   # Platzhalter-PNGs (für Produktion ersetzen)
+npm run dev     # Vite-Dev-Server
 ```

-## Tests & Build
+## Tests, Lint & Build

 ```bash
-npm test
-npm run build
-npm run preview
+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
 ```

-## Technik
+## Datenmodell (Kurz)

- SvelteKit (SPA, `adapter-static` + `fallback: 'index.html'`)
- TypeScript, Zod, Dexie, js-yaml
- `@vite-pwa/sveltekit` (Service Worker, Manifest)
+Der `Character` (siehe `src/lib/schema/character.ts`) enthält u. a.:

-## Hinweise
+- `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`).

- Regeln/Fernkampf-Tabellen aus dem früheren `rules.js` liegen unter `src/lib/rules/`.
- Helden-Software-Import: Platzhalter in `src/lib/import/helden.ts`.
- Icons: `npm run icons` erzeugt minimale PNGs; für Produktion eigene 192/512/maskable-Grafiken einsetzen.
+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).