Vorkenntnisse
adaptor:exadaptor:ex Eine Live-Game-Engine, die von machina eX speziell für die Entwicklung interaktiver Live-Erlebnisse wie Game Theater, Escape Rooms, interaktiven Installationen oder Chatbot-Adventures entwickelt wurde. Sie ermöglicht es, Dramaturgie und Spielmechanik in einer übersichtlichen, grafischen Programmieroberfläche zu verbinden. Während Proben und Live-Aufführungen lassen sich Anpassungen in Echtzeit vornehmen und Abläufe überwachen. Die Software ist Open Source und kostenlos verfügbar. Mehr unter https://docs.adaptorex.org. einrichten
Installiere adaptor:ex auf deinem Laptop oder PC und erstelle dein erstes Game.
Anleitung
Die folgenden Schritte zeigen dir, wie du mit adaptor:ex eine Chat-App einrichten und einen einfachen Chatbot programmieren kannst. Einmal eingerichtet, kannst du das Setup beliebig erweitern. Du kannst den Chat in das Setting eines Theater-Games einbauen oder auf deinem eigenen Smartphone anderen Spieler:innen zur Verfügung stellen.

adaptor:ex einrichten
Installiere adaptor:ex und erstelle ein neues Game wie in der Anleitung adaptor:ex einrichten beschrieben.
Das Messenger-Plugin hinzufügen
Öffne dein Game-Projekt und gehe im GAME-Menü oben rechts auf settings, um ein Plugin zu deinem Projekt hinzuzufügen.

Füge das Messenger-Plugin hinzu, indem du in der Plugin-Übersicht unter AVAILABLE auf das Plus-Icon hinter dem MESSENGER-Plugin klickst.

Das Messenger-Plugin sollte nun in der oberen Liste der aktiven Plugins auftauchen.
Öffne die Einstellungen des Messenger-Plugins, indem du auf den Plugin-Namen klickst, und füge eine neue App hinzu, indem du auf das Plus-Icon unter APPS klickst.

Die Einstellungen für die neue App öffnen sich. Gib der App im name-Feld einen Namen, z.B. ExampleApp (1.). Du kannst den Namen frei wählen, er darf aber keine Leer- oder Sonderzeichen enthalten.
Erstelle die Chat-App mit Klick auf Save (2.).

Überprüfe, ob du die App in deinem Browser öffnen kannst. Klicke dafür auf die neu entstandene App. Unter URL sind alle Web-Adressen aufgelistet, unter denen die Messenger-App erreichbar ist.
Hinweis
Welche Adressen in der URL-Liste auftauchen, ist von deinem Rechner und dem Netzwerk (also dem WLAN), mit dem du verbunden bist, abhängig. Manche Adressen können nur auf deinem Rechner, andere auch über ein lokales Netzwerk geöffnet werden.
Kopiere die oberste URL (http://localhost…) mit einem Klick auf copy und öffne anschließend ein neues Browser-Fenster oder einen neuen Tab.

Füge die kopierte URL in der Addresszeile des neuen Fensters oder Tabs ein und drücke die Enter-Taste.

Der Login-Bereich der Chat-App öffnet sich.

Nun ist der erste Schritt getan: Du hast die vorbereitete Chat-App erfolgreich installiert!
Bevor du in der App über den Login einen User anmelden kannst, musst du aber zunächst noch einen Chatbot und ein erstes Level in adaptor:ex einrichten. Dieses Level wird später gestartet, wenn sich ein User auf dieser Chat-Seite anmeldet.
Einen Chatbot einrichten
Wechsle zurück in das adaptor:ex-Fenster, ohne das andere Fenster zu schließen, und öffne, sofern nicht schon geschehen, das Messenger-Plugin.
Klicke auf das Plus-Icon unter BOTS (1.), um einen neuen Bot-User zu erstellen
Wähle einen Namen für deinen Chat Bot (2.) (in diesem Beispiel ist es Sonali). Das name-Feld darf keine Leer- oder Sonderzeichen enthalten.
Wenn du möchtest, kannst du unter display name (3.) einen alternativen Namen angeben (wie hier im Beispiel Sonali Kadam), unter dem der Bot für andere User im Chat angezeigt wird. Hier kannst du Leer- und Sonderzeichen verwenden.

Klicke auf Save (4.), um den Chatbot zu erstellen.
Ein Level erstellen
Nur wird ein erstes Level gebaut, auf das der Chatbot zurückgreift, wenn die Chat-App gestartet wird.
Wechsle dazu mit GAME > overview in die Level-Übersicht.

In der Level-Übersicht erstelle ein neues Level mit Klick auf NEW LEVEL.

Gib deinem Level einen beliebigen Namen (1.). Der Name darf keine Leer- oder Sonderzeichen enthalten. Erstelle anschließend das neue Level mit einem Klick auf Add new Level (2.).

Das Level bearbeiten
Um das Level zu bearbeiten, klicke in der Level-Übersicht auf den Namen des Levels, den du eben festgelegt hast (hier: chatbot-example).

Du befindest dich jetzt im Level-Editor. Links siehst du die Toolbar. Rechts ist die Stage, wo du die Abläufe deines Levels festlegst.
Hinweis
In der adaptor.ex-Dokumentation bekommst du weitere Infos zu den Elementen Toolbar, Stage, Action und State und der Funktionsweise des Level-Editors.
Suche unter ACTIONS in der Toolbar unter der Überschrift MESSENGER die SendChatMessage-Action heraus und ziehe sie per Drag-and-Drop auf die Stage.

Es wird automatisch ein neuer State erstellt, der die SendChatMessage-Action enthält.
Benenne den State mit der SendChatMessage-Action um, indem du doppelt auf den Titel (hier _state_DVL4EVoz) klickst.
Du kannst den Namen frei wählen, jedoch keine Leer- oder Sonderzeichen und auch keine Umlaute verwenden.

Öffne dann die Action, um sie zu bearbeiten, indem du auf das blaue Feld klickst.
Unter Chat App sollte der Name der Chat-App angegeben sein, den du vorhin vergeben hast (1.), hier ExampleChat. Wahrscheinlich ist auch dein Chatbot (2.), der hier Sonali heißt, bereits unter from user ausgewählt. Klicke andernfalls einmal auf das Auswahlmenü, um deinen Chatbot auszuwählen.
Unter to chat ist das Wort Player als Standard Wert eingetragen (3.). Dies solltest du nicht verändern.
Playerist eine VariableVariable Ein Platzhalter oder Behälter für einen Wert, der sich verändern kann. Variablen können verschiedene Datenarten speichern, wie ganze Zahlen (int), Text/Zeichenketten (string) oder Wahrheitswerte (boolean)., also ein Platzhalter, der automatisch gefüllt wird. Hier steht die Variable für den jeweiligen Spieler oder die jeweilige Spielerin, die später mit deinem Chatbot interagiert.
Gib unter text die Nachricht an, die von deinem Chatbot zur Begrüßung an die spielende Person gesendet werden soll (4.).

Speichere die Eingaben mit Klick auf Save oder Save & Close (5.).
Das Level als Spielbeginn einrichten
Wechsle zurück in die Einstellungen des Messenger-Plugins unter GAME > settings. Öffne dort deine App unter dem Namen, den du vergeben hast (hier ExampleChat).
Klicke auf das Neu-Laden-Icon (1.), um sicherzugehen, dass dein neues Level von der App erkannt wird.
Klicke unter settings auf den Settings-Button (2.) und aktiviere in dem sich öffnenden Menü die Option default level (3.), indem du den Haken in das leere Kästchen setzt.

In der neu entstandenen Option default level kannst du nun dein Level (hier chatbot-example) auswählen. Klicke anschließend auf den Save-Button, um deine Einstellungen zu speichern.
Dein Level mit einem neuen User testen
Du hast jetzt alle Einstellungen vorgenommen, um die erste Chat-Nachricht an eine potentielle Spielerin zu senden. Bleib dran!
Gehe über GAME > overview zurück in den Level-Editor deines Levels. Wechsle nun in den Live-Modus. Klicke dazu auf den Play-Button ganz oben rechts in der Ecke.

Die Menüzeile färbt sich nach dem Kick pink und die Toolbar verschwindet. Dafür taucht rechts die Session-Ansicht auf.
Hinweis
In der adaptor.ex-Dokumentation kannst du mehr über den Live-Modus und Sessions erfahren.
Öffne nun das Browser-Fenster mit der Chat-App.
Um die Abläufe gut nachvollziehen zu können, versuche beide Fenster oder Tabs nebeneinander anzuzeigen.
Klicke in der Chat-App auf den Button New User. Gib anschließend einen Namen für deinen ersten Test-User ein (hier Markus) und klicke auf das Pfeil-Icon, um den User zu erstellen.

Eine Willkommensnachricht erscheint zusammen mit einem Login-Code, mit dem du dich später wieder für denselben User einloggen kannst. Bei Bedarf kannst du ihn notieren.
Wenn die Einrichtung geklappt hat, erscheint gleichzeitig im adaptor:ex-Editor (hier auf der linken Seite des Bildschirms) eine neue Session, also ein aktives Abbild deines Levels. Die Session ist automatisch ausgewählt; der START-State wurde automatisch ausgelöst und ist deshalb rosa eingefärbt. Da der START-State keine relevante Action enthält, passiert aber zunächst nichts.

Klicke nun in der Chat-App auf den START-Button, um den Chat zu öffnen.
Teste nun deine SendChatMessage-Action, indem du in adaptor:ex auf das pinkfarbene Play-Icon oben links im entsprechenden State (hier VersuchStarten) klickst. Der State wird ausgelöst und ein neuer Chat-Kontakt erscheint in der Chat-App. Nach kurzer Zeit, in der drei „Es wird getippt“-Punkte zu sehen sind, erscheint deine programmierte Begrüßungsnachricht im Chat-Fenster.

Wenn du das Play-Icon des States erneut anklickst, wird die Nachricht ein zweites Mal gesendet.
Auf Nachrichten reagieren
Wechsle in adaptor:ex zurück in den Bearbeitungsmodus. Klicke dazu wieder auf den Play-Button ganz oben rechts in der Ecke.
Das Menü färbt sich wieder violett und die Toolbar erscheint auf der linken Seite.
Suche aus der Toolbar unter MESSENGER die OnChatMessage-Action heraus und ziehe sie auf die Stage (1.).
Gib dem State mit der OnChatMessage-Action einen neuen Namen (2.; hier VersuchAntwort).
Öffne die Action, indem du auf das blaue Feld klickst.
Wähle unter Chat App deine App aus (3.), wähle unter to user deinen Chatbot aus (4.) und gib unter in chat das Wort Player an (5.) – also die Variable für den User, der später mit deinem Bot im Gespräch sein wird.
Klicke dann unter if auf Add Condition (6.), um eine Abfrage hinzuzufügen, die angibt, was passiert, wenn eine Nachricht von Player (also vom User) ankommt.

Nun öffnet sich ein neues Unterfenster. Wähle in dem Dropdown-Menü neben der Überschrift condition1 die Option Contains (1.) aus. Damit erstellst du eine Bedingung, die abfragt, ob eine eingehende Nachricht des Users einen oder mehrere bestimmte Begriffe enthält, die du nun festlegen wirst.
Gib unter contains einen Begriff ein, den die Nachricht des Users zwingend enthalten muss, damit dein Chatbot darauf reagiert (2.; hier ja). Klicke auf Add Contains (3.), wenn du weitere Begriffe hinzufügen willst, die die Bedingungen erfüllen würden (hier bereit).
Gib unter Next State den Namen eines neuen States an, der ausgelöst werden soll, wenn die Nachricht einen der festgelegten Begriffe enthält (4.; hier LosGehts). Klicke anschließend auf das Plus-Icon hinter Next State, um den neuen State automatisch zu erstellen (5.).

Hinweis
Next State verwendest du immer an den Punkten im Spiel (oder in diesem Fall: im Chat), wo der Spielablauf von einem in den anderen State wechseln und die darin enthaltenen Actions auslösen soll. Der nächste State wird immer durch ein bestimmtes Ereignis ausgelöst (z.B. eine eintreffende Nachricht) und kann zusätzlich von einer Bedingung (condition) abhängen (so wie hier, wo nur in den nächsten State gewechselt wird, wenn die eintreffende Nachricht vom User einen bestimmten Begriff enthält).
Eine Ausnahme ist die Next-Action, mit der du sofort und ohne Bedingung in den nächsten State wechseln kannst. Mit ihr kannst du z.B. zwei direkt aufeinanderfolgende Chat-Nachrichten versenden.
Nun solltest du noch eine Antwort hinzufügen, die gesendet wird, wenn keine der Bedingungen (conditions) für die eingegangene Nachricht zutrifft. In diesem Beispiel wäre das der Fall, wenn die Nachricht des Users weder da Wort ja noch das Wort bereit enthält.
Klicke dafür unter else auf Settings (1.) und wähle die Option respond (2.) an.

Gib dann im Feld response text einen Text ein, der vom Chatbot gesendet wird, wenn keine der if-Bedingungen zutrifft (1.). Also zum Beispiel Okay. Gib mir Bescheid, wenn du soweit bist.
Über „Add response text“ kannst du weitere Antwortmöglichkeiten hinzufügen, die gesendet werden sollen, wenn die Bedingung bei weiteren eingehenden Nachrichten wieder nicht zutrifft.
Klicke abschließend auf Save & Close (2.).

Nun braucht es noch eine Chatnachricht in dem State, der ausgelöst wird, wenn die Bedingung zutrifft (hier LosGehts) und den du eben über die Funktion Next State bereits angelegt hast.
Ziehe eine SendChatMessage-Action von der Toolbar in den betreffenden State (hier LosGehts). Lasse das blaue Icon erst dann los, wenn der State farblich hervorgehoben ist, nachdem du die Action daraufgezogen hast.

Öffne die SendChatMessage-Action und bearbeite sie wie die erste Nachricht. Gib einen Text für deine Chat-Nachricht an (z.B. Super, dann lass uns loslegen!) und schließe die Action wieder.
Du kannst in if-Bedingungen auch die einfache response verwenden, auch in Kombination mit Next State. Da es sich aber um einen wichtigen Schritt in unserem Game handelt, bietet es sich an, die Nachricht als eigene Action einzupflegen, um besser nachvollziehen zu können, was wann passiert.
States miteinander verbinden
Der LosGehts-State ist durch die if-Bedingung in VersuchAntwort bereits mit diesem State verbunden. Die Abfrage VersuchAntwort sollte vom Chatbot direkt nach der Begrüßungsnachricht in VersuchStarten aktiviert werden. Dafür müssen die beiden States verbunden werden. Füge also dem VersuchStarten-State eine Next-Action hinzu, indem du sie aus der Toolbar unter ACTIONS im Abschnitt CONTROL heraussuchst und in den VersuchStarten-State ziehst.
Öffne die neuentstandene lila Next-Action und wähle unter Next State den State mit der OnChatMessage-Action (hier VersuchAntwort) aus.

Sobald du auf Save klickst oder die Action schließt, wird nun die Verbindung zwischen den beiden States angezeigt.
Die Chat-Konversation testen
Wechsle mit einem Klick auf den Play-Button ganz oben rechts wieder in den Live-Modus.
Sende noch einmal die Begrüßungsnachricht an deine Chat-App, indem du auf das Play-Icon am VersuchStarten-State klickst (1.). Sobald die Nachricht versendet ist, wechselt die Session nun in den VersuchAntwort-State. Der Chatbot wartet jetzt auf eine Nachricht des Players.
Gehe nun wieder zurück in die Chat-App und schreibe eine Nachricht an deinen Chatbot, um zu überprüfen, ob die OnChatMessage-Abfrage funktioniert (2.).

Persönliche Ansprache mit Variablen
Du kannst fast überall in adaptor:ex Variablen verwenden. Variablen sind Platzhalter, die erst dann durch den „echten“ Wert ersetzt werden, wenn sie in einer Session zur Anwendung kommen.
Hinweis
In der adaptor:ex-Dokumentation kannst du mehr über Variablen herausfinden.
Mit der Player -Variable hast du bereits einen Platzhalter verwendet, den adaptor:ex automatisch erstellt, wenn eine Session durch einen neuen User in der Chat-App gestartet wird.
Player kann Informationen über den jeweiligen Chat-User enthalten, wenn du sie abfragst und speicherst.
Du kannst die Player-Variable ausprobieren, indem du die SendChatMessage-Action im VersuchStarten-State öffnest. Füge hinter der Ansprache (Hallo) im Text die Variable [[Player.name]] ein. Im ganzen also z.B.:
Hallo [[Player.name]]! Können wir den Versuch starten oder brauchst du noch einen Moment?Code-Sprache: CSS (css)
Wird die Nachricht innerhalb einer Session versendet, wird [[Player.name]] durch den Wert ersetzt, der unter name im Player hinterlegt ist. Das ist in diesem Fall der Name, der beim Login eines Users in der Chat-App angegeben wurde (in unserem Beispiel also Markus).
Teste die Änderung, indem du die Begrüßungsnachricht, in der nun die Variable enthalten ist, erneut über den Chatbot verschickst.
Hinweis
Wenn statt des User-Namens ein Text mit der Original-Variable auftaucht, überprüfe, ob du die Klammern bei [[Player.name]] exakt wie hier angegeben gesetzt hast und keine Tippfehler enthalten sind. Auch Groß- und Kleinschreibung muss beachtet werden!
Wenn statt des Namens das Wort undefined erscheint, konnte der Wert hinter der Variable nicht gefunden werden. Um dem Fehler auf die Spur zu kommen, wirf einen Blick in das Variablen-Kapitel in der adaptor:ex-Dokumentation.
Den Chat automatisch starten
Damit Spieler:innen den Chat über die Chat-App später automatisch beginnen können, musst du deine Actions noch an den START-State anbinden.
Um dem Spieler einen Moment zur Orientierung in der App zu geben, bietet es sich an, die Nachricht nicht sofort zu senden, sondern mit einer kleinen Zeitverzögerung.
Gehe in den Bearbeitungsmodus und ziehe eine Timeout-Action in den START-State. Du findest sie in der TOOLBAR unter TIME.
Der START-State enthält standardmäßig bereits eine Next-Action. Wenn du die Timeout-Action einfügst, wird die Next-Action entfernt, da sie den Timeout ansonsten überspringen würde.
Öffne die Timeout-Action und gib unter timeout die Länge, die gewartet werden soll, in Sekunden an (hier 5). Wähle unter Next State den State mit deiner Begrüßungsnachricht (hier VersuchStarten) aus.

Schließe die Timeout-Action und wechsle in den Live-Modus.
Um den automatischen Start zu testen, müssen wir einen neuen User erstellen, damit eine neue Session des Levels gestartet wird.
Klicke in der Chat-App auf das Settings-Icon (das kleine Zahnrad) unten links (1.).
Klicke dann auf den roten Logout-Button, um den aktuellen Nutzer abzumelden (2.).

Du bist jetzt wieder im Login-Fenster und kannst einen neuen User mit einem anderen Namen erstellen. Sobald du den User-Namen mit Klick auf den Pfeil bestätigst, wird in adaptor:ex eine neue Session von deinem Level gestartet.
Die Session wird im Live-Modus auf der rechten Seitenleiste angezeigt. Klicke auf das neu entstandene Element (du erkennst es am Player-Namen), um die Session auszuwählen und den Verlauf zu beobachten.
Die Session beginnt mit dem Timeout im START-State, wechselt nach 5 Sekunden in den VersuchStarten-State, verschickt die Begrüßungsnachricht und wechselt anschließend in den VersuchAntwort-State, in dem auf eine Antwort des Players gewartet wird.
Dein Chat-Game ausarbeiten
Nun hast du alle Grundlagen gelernt, um ein ganzes Chat-Game zu programmieren! Mit den beiden Actions SendChatMessage (für das Versenden von Nachrichten) und OnChatMessage (um die Antworten der Spieler:innen abzufragen) kannst du lange Dialoge entwickeln. Du kannst auch RätselRätsel Eine ungelöste Problemstellung, für die Spieler:innen durch Nachdenken, Kombinieren und Ausprobieren eine Lösung finden müssen. Im Game Theater ist ein Rätsel eine Aufgabe innerhalb einer Taskscene. Der Begriff wird häufig synonym zu „Mini-Game“ oder „Task“ verwendet., Quizfragen oder Aufgaben einbauen, die die Spieler:innen lösen müssen – oder sie auffordern, dir ihren Lieblingsfilm, ihre Schuhgröße oder ein Geheimnis zu verraten.
Mit der if-Condition ist es auch möglich, mit unterschiedlichen Texten auf die eingehende Nachricht eines Spielers zu reagieren. Antwortet jemand z.B. mit Nein auf deine Begrüßungsnachricht, könntest du den Chatbot antworten lassen: Was, warum denn nicht?? Bist du etwa krank? Dazu fügst du im VersuchAntwort-State eine zweite if-Condition mit einem eigenen Next-State ein, der zu einem eigenen State mit einer SendChatMessage-Action führt.
Achte aber darauf, dass sich dein Chat-Game nicht zu weit verzweigt und keine unabgeschlossenen Enden entstehen. Am Anfang ist es etwas schwierig, die Struktur zu durchschauen, aber wenn du die Logik einmal verstanden hast, fällt es dir bestimmt leichter!
Dein Chat-Game mit anderen teilen
Schaue in die Messenger-Plugin-Settings unter GAME > settings und öffne die Einstellungen für deine Chat-App. Wenn du per WLAN oder Ethernet-Kabel mit einem Router verbunden bist, wird dort unter URL neben der lokalen Adresse (http://localhost…) mindestens eine weitere angegeben sein.
Statt localhost sollte dort eine Nummernfolge stehen, z.B. 192.168.123.456. Diese Nummernfolge ist die IP deines Rechners im aktuellen Netzwerk. Alle Geräte, die mit demselben Netzwerk/WLAN verbunden sind, können über die dort angegebene Adresse auf die Chat-App zugreifen.

Um das zu testen, kopiere und öffne diese „Intranet“-Adresse zunächst im Browser auf deinem Rechner. Als nächstes kannst du versuchen, die Adresse auf einem anderen Gerät (z.B. deinem Smartphone) zu öffnen.
Hinweis
Es kann sein, dass das Netzwerk, mit dem du verbunden bist, nicht zulässt, dass andere im selben Netzwerk auf diese Adresse zugreifen können. Frage dazu ggf. die Person, die das Netzwerk betreut. Wenn du die Möglichkeit hast, kannst du auch ein eigenes Netzwerk einrichten und für das Game verwenden.
Teile diese Adresse mit anderen und bitte sie, sich mit dem selben Netzwerk zu verbinden, damit sie dein Chat-Adventure spielen können.
Es ist natürlich auch möglich dein Chat-Adventure über das Internet zugänglich zu machen. Wenn du einen eigenen Server aufsetzen möchtest, wirf einen Blick in das Server-Setup-Tutorial. Es gibt auch verschiedene Wege, deinen eigenen Rechner zu verwenden und über das Internet zugänglich zu machen. Das ist mitunter keine leichte Aufgabe. Alternativ gibt es (meist kostenpflichtige) Services, die dir dabei helfen. Egal, wie du dich entscheidest: Achte immer darauf, dass du nur die Chat-App-Webseite und ggf. adaptor:ex und nichts anderes auf deinem Rechner öffentlich zugänglich machst!

