StoryQuest

• StoryQuest Grundlagen
• Erste Quest starten
• StoryQuest Multiplayer starten
• Quest-Editor

StoryQuest Grundlagen

StoryQuest Grundlagen

StoryQuest ist die interaktive Quest-Funktion von Chatlix. Du baust eine verzweigte Geschichte aus Szenen und Entscheidungen, und entweder spielst du sie allein durch oder nimmst deinen ganzen Chat als Mitspieler mit ins Boot.

Eine Quest besteht aus vier Bausteinen:

• Nodes sind einzelne Story-Szenen. Jeder Node hat einen Titel, einen Erzähltext (und optional Hintergrundbild oder Sound aus der Media Library) und eine Liste von Choices, die zu anderen Nodes führen.
• Choices sind die Optionen, die unter einem Node auswählbar sind. Eine Choice zeigt auf einen Ziel-Node und kann optional Variablen verändern oder Items vergeben.
• Variables sind dein State-Tracking. Du kannst z.B. mut als Zahl führen, hat_schluessel als Boolean, oder einen Namen als String. Choices können Variablen setzen/erhöhen, und Nodes können über Bedingungen auf Variablen reagieren (sichtbar nur wenn mut >= 3, dann eine bestimmte Choice einblenden).
• Items sind dein Inventar-System. Eine Choice kann ein Item geben oder entfernen; Folge-Choices können verlangen, dass ein bestimmtes Item im Inventar liegt.

Damit lassen sich klassische Text-Adventures, Quiz-Pfade, Rollenspiel-Demos, Onboarding-Touren oder Showcase-Storys bauen. Wichtig ist, dass StoryQuest keine Live-Performance-Anforderung an dich stellt: Du kannst die Quest komplett vorher zusammenklicken und im Stream einfach starten.

Solo vs. Multiplayer

Es gibt zwei Modi, in denen eine Quest läuft:

• Solo / Playtest: Du allein testest die Quest im Dashboard unter StoryQuestPlaytest. Choices klickst du selbst. Sinnvoll während des Bauens und vor jedem Live-Stream.
• Multiplayer / Live: Die Quest läuft in einer Live-Session, der Chat stimmt ab, und nach Ablauf eines Timers gewinnt die Mehrheit. Dazu siehe die Seite StoryQuest Multiplayer starten.

Wo bauen, wo spielen

Alles Inhaltliche passiert im Dashboard:

• /dashboard/storyquest zeigt deine Quests (Liste, Status, Letzte Bearbeitung).
• /dashboard/storyquest/<id> öffnet den StoryQuestBuilder mit dem StoryQuestFlowchart als Knoten-Editor.
• /dashboard/storyquest/<id>/playtest ist der Solo-Test.
• /dashboard/storyquest/<id>/live ist der Live-Controller.

Für Zuschauer gibt es öffentliche Pages:

• /storyquest/play.php für das aktuelle Live-Spiel deines Kanals.
• /storyquest/party.php für die gemeinsame Lobby (Mehrspieler).
• /storyquest/story.php?id=<id> als Standalone-Story-Reader.
• /storyquest/quickstart.php als kurzer Einstieg für Neulinge.
• /storyquest/creator.php ist der Hub für Quest-Autoren.
• /storyquest/recap.php?session=<id> zeigt nach einer Live-Session den genommenen Pfad zur Nachbesprechung.
• /storyquest/public.php listet öffentliche Quests anderer Streamer.

OBS-Overlay

Die Live-Session ist als Browser-Source einbindbar:

/overlay/storyquest.php?token=<dein_overlay_token>

Das Overlay zeigt den aktuellen Node-Text, die laufende Abstimmung, den Timer und das aktuelle Inventar. Es aktualisiert sich live und ist so designed, dass es entweder als Sidebar oder als Vollbild-Szene funktioniert.

API-Routen

Die wichtigsten Endpunkte unter /v1/storyquests/:

• GET /v1/storyquests/ und POST /v1/storyquests/ für Liste und Anlegen.
• GET|PUT|DELETE /v1/storyquests/<id> für die Quest selbst.
• /v1/storyquests/<id>/nodes, /choices, /items, /variables für die Inhalte.
• /v1/storyquests/<id>/playtest startet eine Solo-Session.
• /v1/storyquests/<id>/live startet/steuert die Multiplayer-Session.
• /v1/storyquests/<id>/analytics liefert Auswertungen (welcher Pfad wurde wie oft genommen).
• /v1/storyquests/<id>/export exportiert die Quest als JSON (Backup oder Sharing).

Der Service-Code liegt in Chatlix\Service\StoryQuest\ und ist in acht Komponenten geteilt: Builder, Playtest, LiveMode, Publishing, Analytics, Variables, Items.

Erste Quest starten

Erste Quest starten

Dieses Schritt-für-Schritt-Beispiel führt dich vom leeren Dashboard zur ersten lauffähigen Mini-Quest. Plane dafür ~15 Minuten ein.

1. Quest anlegen

Gehe ins Dashboard auf /dashboard/storyquest und klick « Neue Quest ». Vergib einen Titel (z.B. „Der Wald hinter dem Dorf“), wähle eine Sichtbarkeit (privat zum Bauen, öffentlich später) und klick « Anlegen ».

Du landest direkt im StoryQuestBuilder mit einem leeren Flowchart und einem automatisch angelegten Start-Node.

2. Start-Node befüllen

Klick den Start-Node an. Im rechten Panel siehst du:

• Titel: „Start“
• Erzähltext (Markdown unterstützt): z.B. „Du stehst am Waldrand. Die Sonne geht unter.“
• Hintergrund (optional, aus Media Library wählbar)
• Sound (optional, aus Media Library wählbar)

Speichern passiert automatisch beim Verlassen des Felds.

3. Zwei Choices anlegen

Unten am Node klick « + Choice ». Trag den Choice-Text ein, z.B. „In den Wald gehen“. Lege eine zweite Choice an: „Zurück ins Dorf gehen“.

Jede Choice braucht ein Ziel — entweder einen bestehenden Node oder einen neuen. Klick auf das Pfeil-Icon der Choice und wähle « Neuen Node anlegen ». Tu das für beide Choices, sodass du jetzt drei Nodes hast: Start, Wald, Dorf.

4. Folge-Nodes ausfüllen

Klick den Wald-Node und schreib einen Text, z.B. „Du gehst tiefer hinein. Es wird dunkel. Ein Knurren.“ Lege Choices an: „Lauschen“ und „Weglaufen“.

Das Dorf-Node bekommt z.B. „Du gehst nach Hause. Ende.“ und keine weiteren Choices. Damit ist es ein End-Node.

5. Solo testen

Oben rechts im Builder klick « Playtest ». Du landest auf /dashboard/storyquest/<id>/playtest. Die Quest startet von vorne, du siehst den Start-Text und die Choices als Buttons. Klick dich durch, prüf ob die Übergänge sitzen, ob keine Choice ins Leere zeigt und ob die Texte gut lesbar sind.

Falls du einen Fehler siehst: Zurück in den Builder, korrigieren, erneut testen.

6. Variable einbauen (optional)

Link im Builder « Variables ». Leg eine Variable an, z.B. mut als Integer mit Startwert 0.

Öffne die Wald-Choice „Lauschen“ und scroll zu den Effekten. Setze mut = mut + 1. Im Folge-Node kannst du jetzt eine Choice anlegen, die nur sichtbar ist, wenn mut >= 1.

Das reicht für den ersten Verzweigungs-Effekt. Tiefer geht das Conditions-System auf der Seite Quest-Editor.

7. Quest veröffentlichen

Wenn der Playtest sauber durchläuft, klick « Veröffentlichen ». Das setzt den Status auf published und macht die Quest für den Live-Modus auswählbar. Im privaten Modus bleibt sie nur für dich sichtbar; auf öffentlich gestellt erscheint sie auf /storyquest/public.php.

8. Erste Live-Session

Geh auf /dashboard/storyquest/<id>/live, wähl die Voting-Dauer (Standard 30 Sekunden), die Eingabe-Quelle (Chat-Kommandos oder Channel-Points) und klick « Live starten ». Wie genau die Multiplayer-Session läuft, steht auf StoryQuest Multiplayer starten.

Häufige Anfänger-Fehler

• Choice ohne Ziel: Eine Choice ohne Ziel-Node führt im Live zu einer toten Stelle. Der Builder warnt dich oben, prüf die Warnliste vor dem Veröffentlichen.
• Endlos-Schleifen ohne Ausgang: Wenn alle Choices zurück zum Start zeigen, kommt nie ein Ende. Setz mindestens einen End-Node (Node ohne Choices) pro erreichbarem Pfad.
• Zu langer Erzähltext pro Node: Im Overlay wird Text gescrollt, aber Zuschauer haben nur wenige Sekunden. Halte Nodes kurz (~2–4 Sätze).
• Variablen nicht initialisiert: Wenn du mut abfragst aber nie einen Startwert vergibst, kann die Bedingung unzuverlässig werden. Setz Variablen-Defaults explizit.

StoryQuest Multiplayer starten

StoryQuest Multiplayer starten

Im Multiplayer-Modus spielt der Chat die Quest gemeinsam. Pro Node läuft ein Voting-Timer, die Choice mit den meisten Stimmen gewinnt, und die Quest fährt fort.

Voraussetzungen

• Quest existiert und ist mindestens published (Solo-Playtest hat funktioniert).
• Du hast eine Plattform-Verknüpfung (Twitch/YouTube), damit Chat-Kommandos oder Channel-Points auslesbar sind.
• Falls du das Overlay nutzen willst: In OBS eine Browser-Source mit /overlay/storyquest.php?token=<dein_overlay_token> einrichten.

Session starten

Öffne /dashboard/storyquest/<id>/live. Du siehst den StoryQuestLive-Controller:

• Voting-Dauer (Sekunden, Standard 30): Wie lange die Abstimmung pro Node läuft.
• Eingabe-Quelle:
  • Chat-Kommandos: Zuschauer schreiben z.B. !1, !2, !3 in den Chat.
  • Channel-Points (nur Twitch): Pro Choice wird ein Channel-Points-Reward angelegt; das Einlösen zählt als Stimme.
  • Beides: Beide Quellen werden addiert.
• Stimmen pro Zuschauer: Standard 1.
• Tie-Breaker: Bei Gleichstand entweder zufällig oder Streamer entscheidet manuell.

Klick « Live starten ». Die Session bekommt eine session_id, das Overlay verbindet sich, und der Start-Node wird angezeigt.

Während der Session

Der Controller zeigt:

• Aktueller Node mit Erzähltext.
• Choices mit Live-Stimmen-Anzahl.
• Timer.
• Aktive Variablen und Inventar.
• Buttons « Voting verlängern », « Voting beenden », « Pausieren ».

Wenn der Timer abläuft (oder du « Voting beenden » klickst), wird die Choice mit den meisten Stimmen ausgeführt, Variablen werden angewandt, ein Item vergeben/entfernt, und der nächste Node erscheint.

Kommen keine Stimmen rein, kannst du entweder verlängern oder die Quest pausieren. Pausen halten den State; danach geht es nahtlos weiter.

End-Node und Recap

Erreicht die Session einen Node ohne Choices, ist die Quest zu Ende. Der Controller zeigt einen Zusammenfassungs-Screen mit:

• Genommenem Pfad (alle Nodes in Reihenfolge).
• Endgültigem Variablen-Stand.
• Inventar.
• Voting-Statistiken pro Node.

Gleichzeitig wird automatisch eine Recap-Page erzeugt unter /storyquest/recap.php?session=<id>. Die kannst du nach dem Stream teilen, sodass Zuschauer den Verlauf nachsehen oder Clips erstellen können.

Mehrere Sessions

Du kannst dieselbe Quest beliebig oft live spielen. Jede Session bekommt eine eigene session_id und eigenen Recap. Die Analytics zählen über alle Sessions, sodass du siehst, welche Choices in echten Streams dominieren und welche nie genommen werden — gut für Balancing.

Chat-Kommandos

Im Chat-Modus akzeptiert der Bot:

• !1, !2, ... für die Choices in Reihenfolge.
• Optional Aliase, wenn du sie in der Choice-Konfig einträgst (z.B. !wald zusätzlich zu !1).

Mehrfach-Stimmen pro User werden geblockt (eine Stimme pro user_id pro Voting), Bots werden ignoriert.

Channel-Points

Im Channel-Points-Modus legt Chatlix temporär einen Reward pro Choice an (z.B. „Choice 1 — In den Wald gehen“). Die Reward-Kosten setzt du in der Live-Konfig (Standard 1 Punkt). Nach Ende der Session werden die Rewards wieder entfernt, damit deine Channel-Points-Liste sauber bleibt.

Troubleshooting

• Overlay zeigt nichts: Token prüfen, Browser-Source neu laden, sicherstellen dass /overlay/storyquest.php aufgerufen wird (nicht eine andere Overlay-URL).
• Stimmen kommen nicht an: Im Chat-Modus den Bot-Status prüfen (Bot im Chat? Mod-Rechte falls erforderlich?). Im Channel-Points-Modus die Twitch-Verknüpfung erneuern.
• Voting endet nicht: Falls Timer hängen bleibt, klick manuell « Voting beenden ». Bei wiederholten Problemen: Session beenden, kurze Pause, neu starten.
• Falsche Choice gewonnen: Selten möglich bei knappem Tie. Du kannst die Session pausieren, manuell zum richtigen Node springen und weiterspielen. Im Recap wird der Eingriff vermerkt.

Quest-Editor

Quest-Editor

Der StoryQuestBuilder ist das Werkzeug, in dem du deine Quest zusammenbaust. Das Herzstück ist das StoryQuestFlowchart — der visuelle Knoten-Editor.

Layout

Der Builder hat drei Bereiche:

• Links: Übersichts-Liste aller Nodes, Items und Variables. Such-Feld oben. Klick öffnet das jeweilige Element rechts.
• Mitte: Flowchart mit Nodes als Boxen und Choices als Pfeile. Zoom mit Mausrad, Pan mit Mittelklick.
• Rechts: Detail-Panel für das gerade ausgewählte Element.

Oben hast du die Aktions-Buttons: « Playtest », « Veröffentlichen », « Export », « Speichern » (Auto-Save ist meist aktiv, der Button erzwingt einen Snapshot).

Nodes bearbeiten

Ein Node hat folgende Felder:

• Titel: Interner Name (nicht für Zuschauer sichtbar, hilft im Builder zur Orientierung).
• Erzähltext: Markdown-fähig. Zuschauer sehen das im Overlay.
• Hintergrund-Bild: Asset-Picker aus der Media Library (/dashboard/media). Optional.
• Sound: Audio aus der Media Library, der beim Erscheinen des Node abgespielt wird. Optional.
• Bedingte Sichtbarkeit für Choices: Pro Choice unter dem Node kannst du Conditions setzen, sodass sie nur erscheinen wenn Variablen/Items bestimmte Werte haben.

Choices bearbeiten

Eine Choice hat:

• Text: Was im Overlay/Chat als Option auftaucht.
• Alias (optional, Liste): Zusätzliche Chat-Kommandos (!wald, !w).
• Ziel-Node: Wohin die Choice führt.
• Effekte: Variablen verändern, Items geben/nehmen.
• Conditions: Wann die Choice angezeigt wird (mut >= 3, hat_schluessel == true).

Die Effekte laufen erst nach Voting-Ende, nicht beim Anzeigen — wichtig fürs Verständnis bei Variablen.

Variables

Unter « Variables » legst du benannte Variablen an. Typen:

• Integer: Zahl, z.B. mut, gold, wuerfel_summe.
• Boolean: Wahr/falsch, z.B. hat_schluessel, tuer_offen.
• String: Text, z.B. held_name, gewaehlter_pfad.

Jede Variable hat einen Startwert, mit dem jede neue Session beginnt.

Items

Unter « Items » definierst du Inventar-Gegenstände mit Name, Beschreibung und optional einem Icon (Media Library). Items haben Stack-Größe (1 = einmalig, oder n).

Effekte auf Choices: Item geben / Item entfernen. Conditions: Inventar enthält Item X.

Conditions-Builder

Der If/Then-Konditions-Builder erlaubt logische Verknüpfungen mit AND/OR und Klammern. Beispiel:

(mut >= 3) AND (Inventar enthält Schluessel)

Du klickst die Bedingungen zusammen, keine Code-Eingabe nötig. Bei komplexen Bedingungen prüf vorher im Playtest, dass das Verhalten stimmt.

Validierung

Vor « Veröffentlichen » läuft eine Validierung. Sie warnt bei:

• Choices ohne Ziel-Node.
• Nodes ohne eingehende Verbindung (außer Start-Node) — also unerreichbar.
• Endlos-Schleifen ohne End-Node.
• Referenzen auf gelöschte Variablen/Items.
• Conditions, die immer false sind (z.B. mut == 1 AND mut == 2).

Warnungen blocken nicht zwingend, Fehler schon. Lies die Liste durch, bevor du veröffentlichst.

Import/Export

« Export » lädt deine Quest als JSON herunter. Das ist ein vollständiges Backup inkl. Nodes/Choices/Items/Variables. Über POST /v1/storyquests/import kannst du eine exportierte Quest in einen anderen Account einspielen — gut für Showcase-Sharing oder Backup.

Die API-Routen für die Bearbeitung sind unter /v1/storyquests/<id>/nodes, /choices, /items, /variables. Wenn du Bulk-Operations brauchst (z.B. 50 Nodes auf einmal anlegen), lohnt sich ein Skript gegen die API statt manuelles Klicken.

Analytics

Unter /dashboard/storyquest/<id>/analytics siehst du nach Live-Sessions:

• Heatmap der genommenen Pfade.
• Stimm-Verteilung pro Choice.
• Drop-off (an welchem Node verlassen Zuschauer das Voting).
• Durchschnittliche Quest-Länge.

Das hilft beim Balancing: Wenn 95% der Sessions immer denselben Pfad nehmen, ist die alternative Choice unattraktiv formuliert.