Mod-Skripte: Leitfaden für Fortgeschrittene

Der Skript-Editor

Um deine Spiel-Skripte zu bearbeiten, klick auf die „Mod-Skripte“-Verknüpfung auf der Spieldetails-Seite für dein Spiel (dort, wo sich auch Optionen wie „Chat-Protokoll“ und „Spiel kopieren/erweitern“ befinden). Du wirst ein paar Funktionen sehen:

• Eine Liste von Registerkarten oben. Dein Spiel kann mehrere Skripte haben, damit du es besser organisieren kannst. Beachte, dass alle Skripte weiterhin im selben Kontext ausgeführt werden. Das bedeutet, dass nicht mehrere Skripte gleichzeitig versuchen sollten, dieselben Werte zu überschreiben, da dies zu unbeabsichtigten Ergebnissen führen könnte.
• Ein Skriptcode-Editor. Du kannst diesen Editor benutzen oder deine Skripte in einem externen Editor deiner Wahl bearbeiten und sie dann hier einfügen.
• Eine Mod-Ausgabekonsole, die sich unten befindet (siehe unten).

Jedes Mal, wenn du auf den „Skripte speichern“-Knopf klickst, wird der Sandkasten für dein Spiel neu gestartet (dabei gehen alle Daten im Arbeitsspeicher verloren, die nicht im state-Objekt oder in Roll20-Objekten gespeichert wurden). Das gilt auch, wenn du ein neues Skript hinzufügst, ein Skript löschst oder ein Skript aktivierst/deaktivierst.

Die Mod-Ausgabekonsole

Die Mod-Ausgabekonsole ist das „Fenster“ zu deinen Skripten. Da Mod-Skripte in einem Sandkasten laufen, hast du während ihrer Ausführung keinen direkten Zugriff darauf, um Informationen zu den Ergebnissen oder Fehlern des Skripts einzusehen. Die Mod-Ausgabekonsole zeigt diese Informationen außerhalb des Sandkastens an, sodass du sie während der Bearbeitung deiner Skripte einsehen kannst. Hier werden alle log()-Befehle angezeigt, ebenso wie alle Fehler, die während der Ausführung deiner Skripte auftreten. Weitere Informationen findest du im Artikel zum Debuggen von Skripten.

Nur für Mod-Skript-Sandkasten v1.5. Wenn möglich, enthalten Fehlermeldungen ein Kontextobjekt, damit du sehen kannst, welches Roll20-Objekt betroffen war (type und id).

Reaktive Skripte: Auf Ereignisse reagieren, Objekte ändern

Die erste (und einfachste) Art, Mod-Skripte zu nutzen, besteht darin, auf Veränderungen auf dem Spieltisch zu reagieren und dann mit zusätzlichen Funktionen auf die veränderten Objekte zu reagieren. Diese Art von Skript besteht aus mehreren Funktionen, die auf Ereignisse im Spiel lauschen. Dann verändert es die Objekte, die bei diesen Ereignissen übergeben werden; das wirkt sich darauf aus, was auf dem Spieltisch passiert.

on("change:graphic", function(obj) {
  obj.set({
    left: obj.get("left") + 70
  });
});

Wie du sehen kannst, haben wir eine einfache on-Funktion erstellt, die immer dann ausgeführt wird, wenn das change:graphic-Ereignis ausgelöst wird. Der Funktion wird das Grafikobjekt obj übergeben. Um eine Änderung vorzunehmen, passen wir obj einfach mit der set-Funktion an – alle Eigenschaften, die wir ändern, werden erkannt und auf dem Spieltisch aktualisiert.

Du musst set und get verwenden, um aktuelle Werte bei Objekten festzulegen und abzurufen, sonst werden deine Änderungen nicht gespeichert. (Siehe die Objekte-Referenz für eine Auflistung der Objekttypen und ihrer Eigenschaften sowie eine Auflistung aller Ereignisse und der Argumente, die jedem Ereignis übergeben werden.)

Proaktive Skripte: Dinge ohne Benutzereingriff erledigen

Neben der Reaktion auf Benutzerereignisse kannst du mit Mod-Skripten auch automatisch Aktionen ausführen, die nicht an ein bestimmtes Ereignis der Spieler gebunden sind. Nehmen wir zum Beispiel einen Spielmarker, der auf der Karte hin und her patrouilliert.

Hinweis: Auch wenn diese Art von Skript nicht auf Benutzerinteraktion angewiesen ist, werden die Mod-Skripte für dein Spiel dennoch nur ausgeführt, wenn mindestens eine Person mit deinem Spiel verbunden ist.

on("ready", function() {
  //Warte, bis das Ready-Ereignis ausgelöst wird, damit wir wissen, dass das Spiel vollständig geladen ist.
  //Hol dir eine Referenz auf unseren patrouillierenden Spielmarker.
  var patroltoken = findObjs({_type: "graphic", name: "Guard A"})[0]; //Wir wissen, dass es im Spiel einen Spielmarker namens „Guard A“ gibt.
  var direction = -1*70; //70 Pixel nach links gehen.
  var stepstaken = 0; //Wie viele Schritte haben wir in der aktuellen Richtung gemacht?
  setInterval(function() {
    if(stepstaken > 3) {
      //Richtung wechseln!
      direction = direction * -1; //„dreht“ die Laufrichtung um
      stepstaken = 0; //setzt die Schritte wieder auf 0 zurück.
    }
    patroltoken.set("left", patroltoken.get("left") + direction); //laufen!
    stepstaken++;
  }, 5000); // alle 5 Sekunden eine Aktion ausführen
});

Eine Abhandlung über asynchrone Funktionen

Manche Werte sind nicht sofort verfügbar. Charakter- und Notizfelder wie bio, notes, gmnotes und _defaulttoken des Charakters erfordern einen Callback bei get():

character.get("bio", function(bio) {
  log(bio);
});

sendChat kann einen optionalen Callback entgegennehmen, sodass die Würfelergebnisse an dein Skript zurückgegeben werden, anstatt im Chat gepostet zu werden. onSheetWorkerCompleted wird ausgeführt, sobald der aktuelle Stapel von Charakterbogen-Entwicklern fertig ist.

Nur für Mod-Skript-Sandkasten v1.5. character.createToken läuft asynchron ab, da es _defaulttoken asynchron übernehmen muss. Die erstellte Grafik wird an einen Callback übergeben und nicht zurückgegeben.

Denk daran, dass prev bei change-Ereignissen nicht den Text dieser asynchronen Felder enthält. Wenn du den vorherigen Blob-Wert brauchst, speichere ihn einfach selbst im Cache.