Dungeon Duo
Full-Stack-KI-Spielleiter für zwei kooperative Spieler
Eine Full-Stack-Webanwendung, die Tabletop-Rollenspiele durch KI zum Leben erweckt. Vollautomatischer Spielleiter für zwei Spieler – dynamische Handlung, Szenenillustrationen, Weltkarte und Echtzeit-Text-to-Speech. Keine Vorbereitung, kein Spielleiter, keine physischen Materialien.
- —Der KI-Spielleiter bettet nach jeder Runde unsichtbare strukturierte Datenblöcke in die Handlung ein, um den Spielstand nahtlos zu synchronisieren
- —Zwei-Spieler-Charaktersystem mit KI-generierten Porträts und personalisierten Hintergrundgeschichten
- —Dynamische 100×100-Weltkarte mit automatischer Bewegungsverfolgung nach jeder KI-Antwort
- —KI-generierte Szenenillustrationen werden inline im Spielprotokoll eingeblendet, während das Abenteuer sich entfaltet
- —Gestreamte TTS-Erzählung – PCM-Audio wird aus Base64 dekodiert und via Web Audio API abgespielt, sobald Chunks ankommen
- —Vollständige Sitzungspersistenz via IndexedDB mit JSON-Export/-Wiederherstellung und Abenteuerprotokoll-Rückspulung
- —Admin-Panel mit live umschaltbaren Spielprofilen: D&D, Lovecraftianischer Horror, Conan 2d20, Das Schwarze Auge 5, Märchen
Dungeon Duo AI ist eine Full-Stack-Webanwendung, die Tabletop-Rollenspiele durch künstliche Intelligenz zum Leben erweckt. Die Anwendung fungiert als vollautomatischer Spielleiter für zwei kooperative Spieler und generiert dynamische Handlung, verfolgt den Spielstand, erstellt Szenenillustrationen und erzählt Geschichten laut – alles in Echtzeit. Spieler können in ein D&D-ähnliches Abenteuer einsteigen, ohne Vorbereitung, Spielleiter oder physische Materialien.
Das Projekt entstand aus dem Wunsch, kollaboratives Geschichtenerzählen zugänglich zu machen: Zwei Personen, ein Browser und ein API-Schlüssel – mehr braucht es nicht für eine vollständige Rollenspielsitzung.
Technischer Stack
Das Frontend ist mit React 19 und TypeScript gebaut, gebündelt mit Vite und gestylt mit Tailwind CSS 4. Das Routing übernimmt React Router 7, die lokale Persistenz nutzt IndexedDB via idb-keyval. Die Anwendung ist vollständig clientseitig – es gibt keinen dedizierten Backend-Server. Alle KI-Funktionen werden direkt über das Google GenAI SDK genutzt, mit Gemini 2.5 Flash als primärem Modell für Erzählung, Bildgenerierung und Text-to-Speech.
Das Projekt wird kontinuierlich über eine GitLab CI/CD-Pipeline deployt, die automatisierte Tests ausführt, die Version erhöht, einen Changelog erstellt und auf einen Produktionsserver per SFTP deployt.
Kernfunktionen
KI-Spielleiter — Jede Spieleraktion wird an Gemini 2.5 Flash gesendet, das mit narrativem Prosatext antwortet. In jede Antwort ist ein versteckter strukturierter Datenblock (||DATA|{...}||) eingebettet, der Spielstandsaktualisierungen enthält: Trefferpunkte, Inventaränderungen, aktuelle Kartenkoordinaten, aktive Effekte und mehr. Dieses Design hält die Handlung sauber und ermöglicht eine nahtlose, unsichtbare Zustandssynchronisation nach jeder Runde.
Zwei-Spieler-Charaktersystem — Beide Spieler erstellen Charaktere mit Namen, Klassen, Völkern und D&D-5e-Attributwerten. Die KI generiert bei der Einrichtung personalisierte Hintergrundgeschichten, und Charakterporträts werden vom Bildgenerierungsmodell erstellt. Jeder Charakter hat unabhängig verfolgtes HP, Zaubersprüche und Inventar während der gesamten Sitzung.
Dynamische Weltkarte — Spielerbewegungen werden automatisch auf einem 100×100-Raster verfolgt. Die Karte visualisiert erkannte Orte, aktuelle Position und besuchte Pfade und aktualisiert sich nach jeder KI-Antwort ohne manuellen Eingriff der Spieler.
KI-generierte Szenenillustrationen — Nach jeder narrativen Antwort fordert die Anwendung eine Szenenillustration vom Bildmodell von Gemini an. Bilder werden inline im Spielprotokoll angezeigt und schaffen eine visuelle Aufzeichnung des Abenteuers.
Gestreamtes Text-to-Speech — Die Erzählung des Spielleiters wird laut vorgelesen über die TTS-API von Gemini. Audiochunks streamen in Echtzeit, werden aus Base64-PCM dekodiert, gepuffert und abgespielt, sobald sie ankommen. Jeder Spieler und der Spielleiter haben eigene Stimmeneinstellungen aus über 30 verfügbaren Stimmen.
Spielpersistenz — Sitzungen werden automatisch zwischen Runden in IndexedDB gespeichert. Vollständige Spielzustände – einschließlich eingebetteter Bilder – können als JSON exportiert und später wiederhergestellt werden. Eine Abenteuerprotokoll-Ansicht ermöglicht Admins das Durchblättern und Zurückspulen zu jedem früheren Spielzustand.
Admin-Interface — Ein passwortgeschütztes Admin-Panel stellt Systemprompt-Vorlagen, Modellauswahl, API-Schlüsselverwaltung und Token-Verbrauchsüberwachung bereit. Mehrere Spielprofile sind sofort verfügbar: klassisches D&D, Lovecraftianischer Horror, Conan 2d20, Das Schwarze Auge 5 und ein Märchen-Setting. Profile können ohne Neuladen live bearbeitet und gewechselt werden.
Engineering-Highlights
Eine der interessanteren technischen Herausforderungen war, KI-Antworten strukturierte Daten transportieren zu lassen, ohne die narrative Immersion zu brechen. Statt den Modellaufruf in einen "Erzähl-Aufruf" und einen "Daten-Aufruf" aufzuteilen, weist der Systemprompt das Modell an, am Ende jeder Antwort einen JSON-Block mit einem benutzerdefinierten Trennzeichen einzubetten. Der Parser entfernt diesen Block stillschweigend, aktualisiert den Zustand und zeigt den Spielern nur den Erzähltext.
Eine weitere Herausforderung war Audio-Streaming. Die TTS-API liefert Audio inkrementell, und die Anwendung musste die Wiedergabe beginnen, bevor die vollständige Antwort ankam. Dies wurde durch einen geordneten Chunk-Puffer gelöst, PCM-Audio aus Base64 in einem Web Audio API-Kontext zu dekodieren und Chunks zur Wiedergabe zu planen, sobald sie fertig waren – während gleichzeitig ein Abbruch korrekt gehandhabt wird, wenn der Nutzer die Erzählung unterbricht.
Retry-Logik mit exponentiellem Backoff (2 s, 4 s, 8 s) handhabt Google-API-Ratenlimits zuverlässig, und eine Fallback-Modellstrategie wechselt automatisch zu einem leichteren Gemini-Modell, wenn das primäre Modellkontingent erschöpft ist.
Version 1.21.0, aktiv gepflegt. Auf Deutsch lokalisiert und für ein deutschsprachiges Publikum konzipiert.