From 260b7b05299e8dbf356a25a2b425c19b313d4e65 Mon Sep 17 00:00:00 2001 From: Falk Graepel Date: Sat, 16 May 2026 21:51:04 +0200 Subject: [PATCH] update readme --- README.md | 173 +++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 158 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 6517e9e..ca460cb 100644 --- a/README.md +++ b/README.md @@ -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).