Direkt zum Hauptinhalt

StoryQuest Grundlagen

StoryQuest ist die interaktive Quest-Engine von Chatlix. Du baust eine verzweigte Geschichte aus Szenen (Nodes) und Entscheidungen (Choices), spielst sie entweder solo als Text-Adventure durch oder lässt deinen Chat live mitentscheiden — bis hin zu einer vollen Mehrspieler-Party mit Rollen, HP, Kämpfen, Loot und Händler.

Status: Beta. Im Dashboard-Menü findest du StoryQuest unter „Abenteuer & Story" → StoryQuest Builder, mit einem BETA-Badge. Das Backend ist stabil und live nutzbar (rund 80 REST-Routen, Auth/CSRF/Rate-Limit sauber verdrahtet), aber es gibt noch keine Route-/Integrationstests und kein In-App-Onboarding — d.h. wenn du zum ersten Mal in den Builder gehst, wirst du ohne Erklärtext auf ein leeres Flowchart geworfen. Diese Wiki-Seiten sind aktuell dein Onboarding.

Eine Quest besteht aus vier Bausteinen

  • Nodes sind einzelne Story-Szenen. Jeder Node hat einen Titel, einen Erzähltext, optional Hintergrundbild/Sound aus der Media Library, einen Node-Typ und eine Liste von Choices. Es gibt drei Node-Typen:
    • normal — reine Erzählszene mit Choices.
    • combat — hat zusätzlich einen Gegner (enemy_name, enemy_hp, enemy_attack, enemy_defense). Hier läuft die eingebaute Würfel-Kampflogik (siehe unten).
    • ending — Schlussszene ohne Fortsetzung.
  • Choices zeigen auf einen Ziel-Node. Eine Choice kann simpel sein (führt direkt zu einem Ziel-Node) oder eine Würfelprobe sein (roll_required): dann führt Erfolg zu success_node_id und Misserfolg zu failure_node_id, geprüft gegen roll_target + roll_modifier auf einem W16 (16-seitiger Würfel, nicht W20 oder W6 — StoryQuest nutzt konsequent 1–16 als Zufallsbereich, auch im Party-Kampf).
  • Variables sind dein State-Tracking: Integer (mut, gold), Boolean (hat_schluessel) oder String (held_name). Jede Variable hat einen Startwert.
  • Items sind dein Inventar-System — Choices können Items geben/entfernen, Conditions können ein Item verlangen.

Zusätzlich hat jede Quest einen Charakter-Grundstand: initial_hp, initial_attack, initial_defense (Standard 20/5/5). Das ist relevant, sobald du combat-Nodes einbaust — ohne Kampf-Nodes spielt HP keine Rolle.

Solo, Chat-Voting und Party — drei Betriebsarten

Anders als man beim ersten Blick vermuten könnte, gibt es nicht nur „Solo" und „Multiplayer", sondern drei klar unterschiedene Modi:

  • Solo / Playtest: Du allein testest die Quest im Dashboard unter /dashboard/storyquests/<id>/playtest. Du klickst Choices selbst, inkl. Würfelproben. Für den Bau und vor jedem Live-Stream Pflicht.
  • Live-Session mit Twitch-Chat-Voting: Eine einzelne Story-Session läuft, dein Chat stimmt per !1/!2/!3 im Twitch-Chat ab, die Mehrheits-Choice wird angewendet. Das ist die „einfache" Multiplayer-Form — ein gemeinsamer Pfad, kein individueller Charakter pro Zuschauer.
  • Party-Modus (echtes Multiplayer-RPG): Bis zu 8 Spieler joinen über einen 6-stelligen Code mit eigener Rolle (Warrior/Mage/Rogue/Healer/Spectator), eigenem HP, gemeinsamem Gold/Inventar. Es gibt Kampfrunden, Loot, Händler, Statuseffekte, Zufallsereignisse und Panic-Controls für dich als Game Master. Das ist der eigentlich interessante Teil von StoryQuest und deutlich mächtiger, als die reine Voting-Beschreibung vermuten lässt — siehe StoryQuest Multiplayer starten für den vollen Ablauf.

Chat-Voting und Party-Modus lassen sich sogar gleichzeitig an dieselbe Live-Session anhängen: Die Session liefert den Story-Fortschritt (linked_session_id), die Party hat ihre eigene Voting-Schicht obendrauf.

Wo bauen, wo spielen

Alles Inhaltliche passiert im Dashboard. Wichtig: Die Pfade sind Plural (storyquests), nicht Singular:

  • /dashboard/storyquests — Liste deiner Quests, Status, Vorlagen-Auswahl.
  • /dashboard/storyquests/<id>/builder — der Editor (Nodes, Choices, Items, Variablen, KI-Tools, Export).
  • /dashboard/storyquests/<id>/flowchart — reine Graph-Ansicht der Story als eigene Route (getrennt vom Builder).
  • /dashboard/storyquests/<id>/playtest — Solo-Test.
  • /dashboard/storyquests/<id>/live — Live-Controller (Chat-Voting-Bindung + Party-Start).

Es gibt keine eigenständige Detailseite unter /dashboard/storyquests/<id> ohne Suffix — der Link von der Liste führt direkt in /builder.

Für Zuschauer/Spieler gibt es öffentliche Seiten unter /storyquest/:

  • /storyquest/play.php?slug=<slug> — aktuelles Live-Spiel eines Kanals.
  • /storyquest/party.php?code=<JOIN_CODE> — Beitritt zur Party-Lobby mit dem 6-stelligen Code.
  • /storyquest/story.php?slug=<slug> — Standalone-Story-Reader (nicht ?id=, sondern ?slug=).
  • /storyquest/quickstart.php — kurzer Einstieg für Neulinge.
  • /storyquest/creator.php?name=<name> — Autoren-Hub.
  • /storyquest/recap.php?key=<32-hex-key> — Recap/Telemetrie nach einer Party-Session. Der Key ist der public_key der Party, nicht die Session-ID — ?session=<id> existiert nicht.
  • /storyquest/public.php — öffentliche Quests anderer Streamer.

OBS-Overlay

Die Live-Session lässt sich als Browser-Source einbinden:

/overlay/storyquest.php?key=<session_public_key>

Läuft zusätzlich eine Party, hängst du den Party-Key an:

/overlay/storyquest.php?key=<session_public_key>&party_key=<party_public_key>&theme=fantasy

Der Parameter heißt key, nicht token — ältere Beschreibungen mit ?token= sind falsch. theme akzeptiert fantasy (Standard), horror oder scifi und färbt/stilisiert das Overlay passend zur Story. Mit &demo=1 läuft das Overlay im Demo-Modus ohne echten Party-Key — praktisch, um das Layout in OBS zu testen, bevor eine echte Session läuft. Das Overlay zeigt Node-Text, laufende Abstimmung/Timer, Party-HP-Balken, Kampf-Banner und Highlight-Banner (z.B. bei kritischem Treffer oder Rare-Loot). Es reconnected selbständig per WebSocket mit Backoff bis 20 Sekunden; ein Dashboard-Polling-Fallback greift, falls die WS-Verbindung länger ausfällt.

API-Routen

Die wichtigsten Endpunkte unter /v1/storyquests/ (Auth per Session-Cookie, außer explizit als „public" markiert):

  • GET /v1/storyquests / POST /v1/storyquests — Liste und Anlegen.
  • GET|PATCH|DELETE /v1/storyquests/<id> — die Quest selbst (PATCH, nicht PUT).
  • /v1/storyquests/<id>/nodes, /choices, /items, /variables — Inhalte, mit den üblichen CRUD-Verben.
  • /v1/storyquests/<id>/playtest/start und /playtest/choice — Solo-Session.
  • /v1/storyquests/<id>/roll — Combat-Round (W16 gegen W16) im Solo-Modus.
  • /v1/storyquests/<id>/live/start, /live/voting, /live/vote (public, kein Auth — Dedupe über voter_key), /live/state.
  • Party-Routen sind uneinheitlich verteilt: party/start und party/join liegen unter /v1/storyquests/<id>/party/..., alle übrigen (leave/state/vote/combat/loot/merchant/panic) unter der eigenständigen /v1/storyquests/party/<party_id>/... — siehe StoryQuest Multiplayer starten.
  • /v1/storyquests/<id>/export und generischer POST /v1/storyquests/import für JSON-Backup/-Sharing (Round-Trip-fähig).

Der Service-Code liegt in Chatlix\Service\StoryQuest\ in klar getrennten Klassen: Stories, Nodes, Sessions, Engine (reine Spiellogik ohne DB — Würfel, Conditions, Effects, Combat), Parties (das komplette Multiplayer-RPG), Templates (Vorlagen + Import), AiHooks/AiAuditLogger (KI-Assistenz im Builder).

Was noch fehlt (Beta-Realität)

Damit du nicht überrascht wirst: Es gibt aktuell (Stand Juli 2026) noch keine Integrationstests oberhalb der reinen Engine-Logik und kein In-App-Onboarding im Builder selbst. Die KI-Tools im Builder sind im UI zwar noch mit „Stub-Modus" beschriftet, das ist aber veraltet: Ist ein OPENAI_API_KEY gesetzt, ruft AiHooks tatsächlich echte OpenAI-Requests auf (Modell gpt-4o-mini per Default) — nur wenn diese fehlschlagen oder ein ungültiges Ergebnis liefern, greift als Fallback die deterministische Heuristik (Details dazu im Abschnitt KI-Tools auf der Seite Quest-Editor). Das UI-Label ist also der eigentlich veraltete Teil, nicht das Backend-Verhalten.