Vorkenntnisse
Vor dem Beginn muss 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. auf dem Rechner eingerichtet sein, mit dem du arbeitest:
adaptor:ex einrichten
Installiere adaptor:ex auf deinem Laptop oder PC und erstelle dein erstes Game.
Hast du dich bisher noch nicht mit Mikrocontrollern beschäftigt, kannst du z.B. hier die Grundlagen kennenlernen:
Einen Magnetkontakt auslesen
Die Anleitung erklärt Schritt für Schritt, wie ein Magnetsensor per MikrocontrollerMikrocontroller Ein Mini-Computer ohne Bildschirm, Maus oder Tastatur. Wird zum Auslesen von Sensoren (wie Schaltern oder Entfernungsmessern) und Steuern von elektronischen Bauteilen (wie LEDs, Motoren oder Elektromagneten) eingesetzt. Häufig Bestandteil von Interaktiven Requisiten. Ein sehr bekannter Mikrocontroller, insbesondere unter Lernenden und Quereinsteigern, ist das Arduino. ausgelesen werden kann. Das ist die Vorbereitung, um mit dem Magnetkontakt andere Technologien wie Licht oder Sound zu steuern.
Anleitung
Mikrocontroller vorbereiten
Als erstes Anleitung musst du deinen Mikrocontroller so einrichten, dass er den Zustand eines Buttons oder eines vergleichbaren Bauteils über die Serielle Schnittstelle (SerialSerial Kurz für serielle Schnittstelle. Sie ist eine Kommunikationsmethode, bei der Daten bitweise nacheinander (seriell) über eine einzelne Leitung übertragen werden. Sie wird häufig verwendet, um Mikrocontroller wie Arduino per USB mit einem Computer oder anderen Geräten zu verbinden – etwa zum Übertragen von Sensordaten oder um den Mikrocontroller zu programmieren. In der Arduino-Welt dient die serielle Schnittstelle oft zur Fehlerbehebung (Debugging) oder zur Steuerung über den Seriellen Monitor in der Arduino-IDE.) an deinen Rechner sendet. Wenn du das zum ersten Mal machst, kannst du in dieser Anleitung nachlesen, wie es funktioniert.

adaptor:ex einrichten
Installiere adaptor:ex und erstelle ein neues Game wie in der Anleitung adaptor:ex einrichten beschrieben.
Das Sound-Plugin hinzufügen
Gehe im GAME Menü oben rechts (1.) auf settings (2.), um ein Plugin zu deinem Projekt hinzuzufügen.

Füge das Sound-Plugin hinzu, indem du in der Plugin-Übersicht unter AVAILABLE auf das Plus-Icon des SOUND-Plugins klickst.

Das Sound-Plugin sollte nun in der oberen Liste der aktiven Plugins auftauchen.
Ein Level erstellen
Wechsle jetzt in die Level-Übersicht mit GAME > overview.

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

Gib deinem Level einen beliebigen Namen. Der Name darf keine Leer- oder Sonderzeichen enthalten. Erstelle anschließend das neue Level mit Add new Level.

Eine Sound-Play-Action erstellen
Öffne dein Level, um es zu bearbeiten, indem du auf den Level-Namen klickst.

Du befindest dich jetzt im Level-Editor.
Ziehe per Drag-and-Drop eine SOUND-Play-Action aus der ACTIONS-Auswahl in der Toolbar (auf der linken Seite) auf die Stage (die große Freifläche daneben).
Hinweis
In der adaptor.ex-Dokumentation bekommst du weitere Infos zu den Elementen Toolbar, Stage, Action und State und der Funktionsweise des Level-Editors.

Benenne den State mit der Play-Action um, indem du doppelt auf den Titel (hier _state_vXvVoOMn) klickst.
Du kannst den Namen frei wählen, jedoch keine Leer- oder Sonderzeichen und auch keine Umlaute verwenden.

Öffne nun die Play-Action, indem du das blaue Kästchen sound play_1 auf der Stage anklickst.
Wechsle in der Toolbar oben links in den FILES-Tab (1.). Wähle die vorhandene .wav-Datei aus dem examples-Ordner an und ziehe sie in das track-Feld der geöffneten Play-Action (2.).

Das Level im Live Modus steuern
Bevor du das Serial-Device einbindest, solltest du nun zunächst testen, ob der Sound aus der hinzugefügten Play-Action korrekt abgespielt wird. Dazu wechselst du in den Live-Modus, indem du auf das Play-Icon oben rechts in der Ecke des Editors klickst (1.).

Starte dann eine neue Session mit Klick auf Create Session (2.) und anschließend auf Start Session (3.). Die beiden Felder Name und Player kannst du freilassen.
Hinweis
In der adaptor:ex-Dokumentation kannst du mehr über den Live-Modus und Sessions erfahren.
Dein Level hat jetzt eine aktive Session, in der du den Ablauf beobachten und manuell zwischen States wechseln kannst.
Eine Session beginnt immer mit dem START-State. Um den Sound abzuspielen, musst du manuell in den PlayExample-State aus unserer Play-Action wechseln. Klicke dafür auf den Play-Button neben dem State-Namen.

Dein Computer sollte nun den Sound abspielen, den du in der Play-Action angegeben hast.
Wenn du nichts hörst, wirf einen Blick in den Abschnitt Fehlersuche.
Ein Serial-Device verbinden
Beende den Live-Modus, indem du erneut auf das Play-Icon ganz oben rechts im Editor klickst.
Gehe im GAME-Menü in die SETTINGS, um ein weiteres PLUGIN hinzuzufügen.
Klicke in der Liste unter AVAILABLE auf das Plus-Icon in der Zeile DEVICES.

Wenn du deinen Mikrocontroller noch nicht angeschlossen hast, verbinde ihn jetzt über das USB-Kabel mit deinem Rechner.
Hinweis
Das DEVICES-Plugin erlaubt es dir, Geräte oder Software über gängige Schnittstellen mit adaptor:ex zu verbinden. In dieser Anleitung nutzen wir die Serielle Schnittstelle (Serial) deines Mikrocontrollers, über die Daten, Code und Anweisungen via USB-Kabel ausgetauscht werden können.
Öffne die Settings des DEVICES-Plugins, indem du auf den Plugin-Namen klickst, und füge ein neues SERIAL-Device hinzu, indem du auf das Plus-Icon unter dem Wort SERIAL klickst.

Die Einstellungen für das neue Device öffnen sich. Gib dem Serial-Device im name-Feld einen Namen, z.B. ExampleArduino (1.). Du kannst den Namen frei wählen, er darf aber keine Leer- oder Sonderzeichen enthalten.
Wähle dann den Serial Port aus, über den der Mikrocontroller angeschlossen ist (2.), und die BaudrateBaudrate Auch Übertragungsgeschwindigkeit. Sie gibt an, wie viele Symbole pro Sekunde über eine serielle Verbindung übertragen werden, etwa zwischen einem Arduino und einem Computer. Typische Baudraten sind 9600, 19200 oder 115200 Baud. Beide Geräte müssen dieselbe Baudrate verwenden, damit die Kommunikation fehlerfrei funktioniert., die der Mikrocontroller zum Kommunizieren über den Serial-USB-Anschluss verwendet (3.).

Wenn du deinen Mikrocontroller erst jetzt angesteckt hast, kannst du die Liste der Serial Ports aktualisieren, indem du auf den Neu-Laden-Icon oben rechts am Devices-Plugin klickst.

Erstelle das Serial-Device mit Klick auf Save (4.).
Hinweis
Überprüfe in der Software, mit der du deinen Mikrocontroller programmierst (z.B. die ArduinoArduino Eine Open-Source-Elektronikplattform, die aus einem Mikrocontroller und einer Entwicklungsumgebung besteht. Mit Arduino lassen sich leicht eigene Projekte umsetzen, etwa Sensoren ausgelesen, LEDs geschaltet oder Motoren angesteuert. Die Programmierung erfolgt in einer vereinfachten Version von C++ über die Arduino IDE. Ideal für Einsteiger:innen in die Welt der Elektronik und Programmierung. IDE), wie der Serial Port heißt.
Die Baudrate entspricht dem Wert, den du beim Initialisieren der Serial-Verbindung im Mikrocontroller-Code setzt – z.B. Serial.begin(9600).
adaptor:ex wird direkt versuchen, sich mit deinem Mikrocontroller zu verbinden. Oben rechts zeigt ein kleiner Kreis an, ob das Gerät erfolgreich verbunde wurde. Ist der Kreis grün, ist der Mikrocontroller verbunden. Ist der Kreis rot, ist die Verbindung gescheitert und du solltest einen neuen Versuch starten. Klicke dafür auf das Stecker-Icon.

Hinweis
Wenn du den Serial-Monitor in deiner Mikrocontroller-Software nutzt, kann adaptor:ex sich nicht zur selben Zeit mit dem Gerät verbinden. Schließe den Serial-Monitor und versuche dann erneut, die Verbindung in adaptor:ex herzustellen (mit einem Klick auf das Stecker-Icon).
Auch um Code auf deinen Arduino zu spielen, nutzt die Arduino IDE denselben seriellen Port wie adaptor:ex. Wenn du den Sketch modifizierst und deinen Arduino updatest, denk daran, dein Device vorher in adaptor:ex mit Klick auf das durchgestrichene Stecker-Icon zu trennen. Verbinde das Device nach dem Upload wieder neu, um es in adaptor:ex zu benutzen.
Eine On-Device-Message erstellen
Gehe im adaptor:ex-Menü auf GAME > Overview und klicke auf dein Level, um es weiter zu bearbeiten.
Wechsle zurück in den ACTIONS-Tab in der Toolbar und ziehe eine OnDeviceMessage-Action auf die Stage (1.). Platziere sie so, dass sie sich links von dem State mit der Play-Action befindet.
Gib dem State mit der OnDeviceMessage-Action einen sinnvollen Namen, z.B. WaitForButtonPush.
Öffne die OnDeviceMessage-Action, indem du auf das blaue Feld klickst.
Wähle das Device aus, das du zuvor eingerichtet hast und mit dem du den Sound triggern möchtest (2.).
Klicke unter if auf Add Condition, um die Nachricht festzulegen, auf die reagiert werden soll.
Gib im equals-Feld die Nachricht an, die den Sound triggern soll (3.). In diesem Beispiel fragen wir den Wert „1“ ab. Welchen Wert (also welche Zahl oder welches Wort) du hier eingibst, hängt davon ab, was dein Mikrocontroller über die Serielle Schnittstelle sendet, wenn du den Button (bzw. den Sensor, Schalter oder Kontakt) auslöst.
Wähle unter Next State den State aus, der die Play-Action enthält, hier PlayExample (4.).
Das Feld mit der Bezeichnung field kannst du leer lassen.

Öffne die Next-Action im START-State und wähle unter Next State den State mit der OnDeviceMessage-Action (hier WaitForButtonPush) aus.

Die drei States sollten jetzt miteinander verbunden sein. Es wird höchste Zeit, das Level zu testen und zu überprüfen, ob alles funktioniert!
Den Listener aktivieren
Aktiviere den Live-Modus mit einem Klick auf den Play-Button ganz oben rechts im Editor.
Starte deine Session von vorn, indem du auf das Play-Icon am START-State klickst.
Der START-State gibt direkt weiter an den WaitForButtonPress-State mit der OnDeviceMessage-Action.
Wenn du nun den Button an deinem Mikrocontroller drückst (bzw. auf andere Weise die Eingabe auslöst, die du über den Serial schickst), sollte adaptor:ex in den PlayExample-State wechseln und das ausgewählte Sound-File auf deinem Rechner abspielen.
Um erneut die Reaktion des Buttons zu testen, wechsle manuell zurück in den WaitForButtonPush-State, indem du auf das Play-Icon neben dem entsprechenden State-Namen oben links klickst.

Fehlersuche
In der Log-Konsole von adaptor:ex bekommst du detaillierte Infos darüber, was alles passiert – und ob irgendwo ein Fehler aufgetreten ist. Am Anfang kann die Liste etwas unübersichtlich wirken, aber mit den untenstehenden Tipps wirst du dich schnell zurechtfinden.
Öffne die Log-Konsole mit Klick auf das Konsolen-Icon rechts oben (links neben dem Live-Modus-Icon).

Kein Sound
Wenn adaptor:ex im Live-Modus in den PlayExample-State wechselt, aber kein Sound abgespielt wird, kann das verschiedene Gründe haben.
Um die Sound-Ausgabe unabhängig von deinem Mikrocontroller zu testen, klicke im Live-Modus in der laufenden Session auf das Play-Icon an deinem PlayExample-State.
Öffne die Konsole, um zu sehen, ob beim Versuch, den Sound abzuspielen, Fehler angezeigt werden. Fehler werden mit dem Begriff error markiert. Du kannst auch die Auswahl oben links verwenden, um nur error-Nachrichten anzuzeigen.
Wenn du keinen Fehler entdeckst, überprüfe zunächst die Sound-Einstellungen deines Rechners. Je nachdem welches Betriebssystem dein Laptop oder PC hat, kann es verschiedene Gründe haben, dass du nichts hörst.
Wirf einen Blick in die Dokumentation des Sound-Plugin:
Zusätzliches Material
Hier kannst du das oben erstellte Beispiel-Level herunterladen. Lade die Datei herunter und importiere sie in dein Game über Game > overview > New Level > Datei auswählen. Ggf. musst du das ausgewählte Device in der OnDeviceMessage-Action anpassen.
In der adaptor:ex-Dokumentation findest du ein ergänzendes TutorialTutorial Eine Einführung in die Regeln und die Steuerung eines Spiels. Sie kann als vorgelagerte Anleitung oder als In-Game-Tutorial erfolgen, bei dem die Spieler:innen die Regeln durch eigenes Ausprobieren kennenlernen. zur Verwendung der Seriellen Schnittstelle mit einem (Arduino)-Mikrocontroller.
Weitere Beispiele (in englischer Sprache) für die Verwendung der Seriellen Schnittstelle mit einem (Arduino-)Mikrocontroller findest du auf arduino.cc.

