Mod-Skripte: Ereignisse

Es gibt verschiedene Arten von Ereignissen, auf die du mit on(event, callback) reagieren kannst. Es gibt fünf Ereignistypen: ready, change, add, destroy und chat. Abgesehen von ready enthält der Name einen Objekttyp (oder message für Chat), und change kann eine Eigenschaft enthalten. Jedes Ereignis wird einmal pro Objekt ausgelöst, das sich ändert. Wenn sich mehrere Eigenschaften des Objekts gleichzeitig ändern, wird nur ein „globales“ Ereignis (zum Beispiel change:graphic) ausgelöst, zusätzlich zu allen eigenschaftsspezifischen Ereignissen, die du gebunden hast.

Callback-Parameter

Wenn du ein Ereignis abhörst, erstellst du eine Funktion, die als Callback bezeichnet wird und jedes Mal ausgeführt wird, wenn das Ereignis eintritt. Die Callback-Funktion erhält Parameter, die dir mitteilen, was sich geändert hat, damit du entscheiden kannst, was zu tun ist.

obj

Das geänderte Objekt. Alle Änderungen, die du an diesem Objekt vornimmst, werden auch im Spiel gespeichert. Wenn du also ein Grafikobjekt nach links verschieben möchtest, änderst du die Eigenschaft left von obj mit set.

• obj.get("property") gibt den aktuellen Wert der Eigenschaft zurück.
• obj.set("property", "newvalue") setzt einen neuen Wert für die Eigenschaft. Wenn du mehrere Eigenschaften auf einmal ändern möchtest, kannst du ein Objekt übergeben: obj.set({left: 10, top: 20}).

prev

Dies ist ein Objekt der Eigenschaften von obj, wie sie waren, bevor aufgrund dieses Ereignisses Änderungen vorgenommen wurden. Nützlich, um festzustellen, „wie stark“ sich eine Eigenschaft geändert hat.

HINWEIS: prev ist kein Roll20-Objekt. Auf Eigenschaften mit Klammer- oder Punktnotation zugreifen: prev["bar1_value"] oder prev._id. Du kannst get / set darauf nicht aufrufen, und du kannst den Unterstrich bei schreibgeschützten Schlüsseln nicht weglassen (prev.id ist nicht prev._id).

Bei Charakteren und Notizen sind die Blob-Felder bio, notes und gmnotes in prev interne Kennungen, nicht der Text. Charakter _defaulttoken ist ebenfalls ein Blob. Grafik-gmnotes ist eine gewöhnliche Zeichenfolge. Speichere frühere Blob-Werte selbst im Cache, falls du sie brauchst.

Ereignisanordnung

Ereignisse werden synchron ausgelöst (jede Funktion startet erst, wenn die vorherige beendet ist), und zwar in der Reihenfolge von der ersten Bindung zur letzten sowie von der spezifischen Eigenschaft zum allgemeinen Objekt. Also Folgendes gegeben:

on("change:graphic", function1);
on("change:graphic", function2);
on("change:graphic:left", function3);

Wenn sich die Eigenschaft left des Objekts geändert hätte, wäre die Reihenfolge function3, dann function1, dann function2.

Wenn deine Kampagne mehrere Skripte enthält, werden diese in derselben Reihenfolge geladen, in der sie auf der Einstellungsseite „Mod-Skripte“ von links nach rechts angezeigt werden.

Hinweis: Das set() eines Skripts löst kein change-Ereignis für diese Eigenschaft aus. Wenn ein Spieler einen Spielmarker bewegt, bekommst du change:graphic. Wenn ein Skript dann left mit set() ändert, löst diese Änderung kein change:graphic aus. Das Erstellen einer Grafik über ein Skript löst change:graphic aus. sendChat() löst chat:message aus, einschließlich Nachrichten, die mit ! beginnen.. Virtuelle status_*-Eigenschaften lösen keine eigenen Ereignisse aus; achte auf change:graphic:statusmarkers.

bereit

Dieses Ereignis wird jedes Mal ausgelöst, wenn der Sandkasten startet, nachdem die Kampagnendaten geladen wurden. Suche erst nach Objekten, die bereits existieren, nachdem ready ausgelöst wurde. Wenn du dich an add-Ereignisse (wie add:graphic) bindest, bevor ready ausgelöst wird, erhältst du auch add-Ereignisse für Objekte, die bereits in der Kampagne waren. Skripte werden in der Reihenfolge der Einstellungen für Mod-Skripte von links nach rechts geladen; ready-Handler werden in der Reihenfolge ausgeführt, in der sie gebunden wurden.

Callback-Parameter: keine

on("ready", function() {
  var tokenThatAlreadyExisted = getObj("graphic", "-ABc123");
});

Chat-Events

chat:message

Wird immer dann ausgelöst, wenn eine neue Chat-Nachricht eingeht, einschließlich Nachrichten, die mit sendChat() gesendet wurden. Der Callback erhält ein msg -Objekt. Zu den Nachrichtentypen gehören general, rollresult, gmrollresult, secretrollresult (/sr), supersecretrollresult (/ssr), emote, whisper, desc, direct und api. Nachrichten, die mit ! beginnen haben type === "api" und werden im Chat nicht angezeigt.

Callback-Parameter: msg

Siehe Mod-Skripte: Chat für die vollständige Liste der msg-Eigenschaften und die Verarbeitung von Würfelergebnissen.

Kampagnenereignisse

Das Kampagnenobjekt unterstützt change:campaign und change:campaign:PROPERTY für jede Kampagneneigenschaft. Das sind die, auf die die meisten Skripte achten:

change:campaign:playerpageid

Wird immer dann ausgelöst, wenn sich die Seite ändert, auf der sich die Spieler gerade befinden.

change:campaign:turnorder

Wird immer dann ausgelöst, wenn sich die Zugreihenfolgeliste für die Kampagne ändert.

change:campaign:initiativepage

Wird immer dann ausgelöst, wenn die Zugreihenfolge für eine Seite ausgeblendet oder angezeigt wird. Dies ist möglicherweise nicht mit der ID der aktuell aktiven Seite identisch. Wenn dies auf false gesetzt ist (auch wenn ein Mod-Skript es auf false setzt), wird die Zugreihenfolge für alle SL/Spieler geschlossen. Wenn du eine gültige Seiten-ID festlegst, wird sie für alle SLs/Spieler geöffnet.

Objektereignisse

Jeder Objekttyp unterstützt:

• add:TYPE
• change:TYPE
• change:TYPE:PROPERTY
• destroy:TYPE

Du kannst auch eine Bindung an eine bestimmte Objekt-ID vornehmen: change:TYPE:ID, change:TYPE:ID:PROPERTY und destroy:TYPE:ID.

Siehe „Mod-Skripte: Objekte“ für die Eigenschaften der einzelnen Typen.

change:graphic

Wird immer dann ausgelöst, wenn sich ein Grafikobjekt (fast jedes Objekt auf dem Spieltisch, einschließlich Spielmarker, Karten und Kartenobjekten) ändert.

Hinweis: Grafikobjekte, die durch Skripte erstellt werden, lösen dieses Ereignis bei ihrer Erstellung aus.

Callback-Parameter: obj, prev

on("change:graphic", function(obj, prev) {
  //Hier etwas mit „obj“ machen. „prev“ ist eine Liste vorheriger Werte.
  // Beachten Sie, dass „obj“ und „prev“ unterschiedliche Objekttypen sind.
  // Um mit obj zu arbeiten, müssen Sie obj.get("name"); verwenden.
  // um mit prev zu arbeiten, können Sie prev["name"] verwenden;
});

change:graphic:(property)

Sie können auch für jede spezifische Eigenschaft des Objekts eine Bindung an ein Ereignis herstellen. Wenn du also ein Skript hast, das nur ausgeführt werden soll, wenn sich rotation ändert, würdest du Folgendes tun:

on("change:graphic:rotation", function(obj, prev) {
  //Setze die Drehung immer wieder auf 0 zurück, damit niemand Objekte drehen kann.
  obj.set("Rotation", 0);
});

add:graphic

Wird immer dann ausgelöst, wenn ein Grafikobjekt zum ersten Mal zur Tischplatte hinzugefügt wird. Wird auch für vorhandene Objekte aufgerufen, wenn der Spieltisch gestartet wird, wenn du an dieses Ereignis außerhalb des ready-Ereignisses bindest.

Callback-Parameter: obj

var started = false;
on("add:graphic", function(obj) {
  if (!started) return;
  // Nur Grafiken, die nach „ready“ hinzugefügt wurden.
});
on("ready", function() {
  started = true;
});

destroy:graphic

Wird immer dann ausgelöst, wenn ein Grafikobjekt vom Spieltisch entfernt wurde.

Callback-Parameter: obj

Grafik-Untertypen

Grafiken lösen Ereignisse auch über ihren _subtype aus. Karten verwenden den Untertyp token.

card ist sowohl ein Roll20-Objekttyp als auch ein Grafik-Untertyp. Daher müssen Handler für change:card und ähnliche Ereignisse anhand des Objekttyps unterscheiden (zum Beispiel obj.get("_type")), um sicherzustellen, dass sie für die richtige Art von Objekt ausgelöst werden.

Alle Objekttypen

Jeder der unten aufgeführten Typen unterstützt add:TYPE, change:TYPE, change:TYPE:PROPERTY und destroy:TYPE.

Nur Mod-Skript-Sandkasten v1.5. pageFolder-Objekte verfügen über add:pageFolder, change:pageFolder, destroy:pageFolder und Eigenschaftsereignisse wie change:pageFolder:name. Seiten lösen außerdem change:page:_placement und change:page:_path aus, wenn sich die Hierarchie des Seitenmenüs ändert.

Jumpgate-/Latest-VTT-Engine-Objekttypen (pathv2, pin, window, door) sind Funktionen der VTT-Engine und keine Funktionen der Sandkasten-Version. Ein Spiel der Version 1.0, das auf der neuesten VTT-Engine läuft, verfügt immer noch über diese Objekttypen und deren Ereignisse.