175 lines
7.6 KiB
Markdown
175 lines
7.6 KiB
Markdown
# 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).
|