dsa-ranger/README.md

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 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

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

Tests, Lint & Build

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.