1. Roll20 Hilfezentrum
  2. Automatisierungen
  3. Mod-Skripte (API)

Mod-Skripte: Chat

Auf dieser Seite findest du Informationen zu Mod-Skripten im Zusammenhang mit Chat-Funktionen.

Chat-Events

chat:message

Wird immer dann ausgelöst, wenn eine neue Chatnachricht empfangen wird. Beachte: Wenn die Nachricht vom Typ rollresult, gmrollresult, secretrollresult oder supersecretrollresult ist, musst du JSON.parse() für den Inhalt der Nachricht aufrufen, um ein Objekt zu erhalten, das Informationen zu den Würfelergebnissen enthält.

Wenn ein Spieler eine Chat-Nachricht eingibt, die mit ! beginnt,, hat diese Nachricht den type "api" und wird im Chat nicht angezeigt. Skripte verwenden diesen Typ für Befehle. sendChat() löst außerdem chat:message aus, und diese Nachrichten haben playerid "API".

Callback-Parameter:

Eigenschaft Standardwert Anmerkungen
Wer "" Der Anzeigename des Spielers oder Charakters, der die Nachricht gesendet hat. Für einen SL endet dies mit (GM). Entferne dieses Suffix, bevor du who an sendChat übergibst, wenn es nicht im geposteten Namen erscheinen soll.
playerid Die ID des Spielers, der die Nachricht gesendet hat. Von sendChat() erstellte Nachrichten verwenden "API".
rolle "allgemein" Eines von general, rollresult, gmrollresult, secretrollresult, supersecretrollresult, emote, whisper, desc, direct oder api.
inhalt "" Der Inhalt der Chat-Nachricht. Wenn type rollresult, gmrollresult, secretrollresult oder supersecretrollresult ist, handelt es sich hierbei um eine JSON-Zeichenkette mit Daten zum Wurf.
origRoll (nur Würfelbefehle) Der Originaltext des Würfelbefehls, z. B.: 2d10+5 Feuerschaden, wenn der Spieler /r 2d10+5 Feuerschaden eingibt. Das entspricht der Verwendung von content bei Nachrichten mit anderen Typen als Wurfergebnis-Typen.
In-line-Würfe Vorhanden, wenn content Inline-Würfe enthält. In einer "api"-Nachricht erscheinen die Würfe in content als $[[0]], $[[1]] usw., und dieses Array enthält die geparsten Würfe in dieser Reihenfolge. Ein Eintrag kann secret: true enthalten.
Würfelvorlage (Inhalt enthält ausschließlich eine oder mehrere Würfel-Vorlagen) Der Name der angegebenen Vorlage.
Ziel (nur Typ whisper) Die Spieler-ID der Person, an die das Flüstern gesendet wird. Wenn das Flüstern an den SL gesendet wurde, ohne dessen Anzeigenamen zu verwenden (z. B. /w gm text statt /w Riley text, wenn Riley der SL ist), oder wenn das Flüstern an einen Charakter ohne steuernde Spieler gesendet wurde, lautet der Wert gm.
Zielname (nur Typ whisper) Der Anzeigename des Spielers oder Charakters, an den das Flüstern gesendet wurde.
selected Vorhanden bei "api"-Befehlen von Spielern, wenn etwas ausgewählt ist. Jeder Eintrag ist ein einfaches Objekt {_id, _type}, kein Roll20-Objekt. Wird weggelassen, wenn die Nachricht von sendChat() stammt.
geheimnis "false" true für geheime und streng geheime Würfe und Nachrichten.
Geheimhaltung "öffentlich" "public", "secret" oder "super".

Geheime und streng geheime Würfe verwenden diese Befehle (verfügbar in beiden Sandkasten-Versionen):

  • /secretroll oder /sr – type ist "secretrollresult", secret ist true, secrecy ist "secret".
  • /supersecretroll oder /ssr – type ist "supersecretrollresult", secret ist true, secrecy ist "super".
  • /secret oder /s, gefolgt von einer Nachricht (zum Beispiel /secret [[1d6]]) – type bleibt "general", secret ist true, secrecy ist "secret". Kompakte, geheime Form eines an den SL geflüsterten Wurfs: Der SL sieht den Wert; der Würfelnde sieht, dass ein geheimer Wurf stattgefunden hat.
  • /supersecret oder /ss, gefolgt von einer Nachricht – type bleibt "general", secret ist true, secrecy ist "super".

/sr und /ssr sind Wurfbefehle. Sie sind keine ! Befehle. Eine Nachricht, die mit ! beginnt, hat den type "api".

Hinweis: Du brauchst wahrscheinlich nicht alle diese Informationen. In den meisten Fällen interessiert dich nur das Gesamtergebnis des Würfelwurfs (siehe unten im ersten Beispiel). Es wird jedoch alles bereitgestellt, wenn du wirklich tiefer in die Ergebnisse eines Wurfs eintauchen möchtest.

Rollergebnisstruktur Bsp. 1

Nachdem du JSON.parse auf die content-Eigenschaft einer rollresult-, gmrollresult-, secretrollresult- oder supersecretrollresult-Nachricht angewendet hast, erhältst du ein Objekt im folgenden Format (das ist das Ergebnis des Befehls /roll {2d6}+5+1t[weather] Attack!)

{
  "Typ":"V", //"V" = "Validierter Wurf" (dies wird immer "V" sein)
  "Würfe": [
    {
      "Typ":"G", //"G" zeigt einen gruppierten Wurf an. Eine Gruppe ist wie eine Reihe von „Unterwürfen“ innerhalb eines Wurfs.
      "Würfe": [
        [
          {
            "Typ":"R", //"R" = "Wurf"
            "Würfel":2, // Anzahl der gewürfelten Würfel (2dX bedeutet 2 Würfel)
            "Seiten":6, //Anzahl der Seiten für die Würfel (Xd6 bedeutet 6 Seiten)
            "Mods":{},
            "Ergebnisse": [ //Ein Array der Ergebnisse jedes Wurfs.
              {
                "v":1 // Wir haben bei unserem ersten 2d6-Wurf eine 1 gewürfelt
              },
              {
                "v":5 // Wir haben bei unserem zweiten 2d6-Wurf eine 5 gewürfelt
              }
            ]
          }
        ]
      ],
      "mods":{},
      "resultType":"sum", // Das Ergebnis ist eine Summe (im Gegensatz zu einer Erfolgsprüfung)
      "results": [
        {
          "v":6 // In diesem Fall das Gesamtergebnis (Gesamtsumme) der Gruppe.
        }
      ]
    },
    {
      "Typ":"M", //"M" = Mathematischer Ausdruck
      "Ausdruck":"+5+"
    },
    {
      "Typ":"R", //"R" = Wurf
      "Würfel":1,
      "Tabelle":"wetter", // Die Tabelleneigenschaft wird auf den Namen der Tabelle gesetzt, wenn dieser Wurf gegen eine Tabelle gemacht wurde
      "Mods":{},
      "Seiten":2, //Dieses Ergebnis kann bei Tabellenergebnissen möglicherweise ignoriert werden.
      "Ergebnisse": [
        {
          "v":0, //Der "Wert" des Tabelleneintrags, der gewürfelt wurde. Bei Texttabellen ist dieser immer 0.
          "Tabellenindex":1, //Der Index des Eintrags in der Tabelle, der gewürfelt wurde.
          "Tabelleneintrag": { //Eine Kopie des Tabelleneintragsobjekts, wie es existierte, als die Tabelle gewürfelt wurde.
            "name":"rainy",
            "avatar":"", //Dies ist eine URL zu einem Bild, wenn die Wurf-Tabelle Bildsymbole verwendet
            "weight":1,
            "id":"-IpzPx2j_9piP09ceyOv"
          }
        }
      ]
    },
    {
      "type":"C", // "C" = Kommentar
      "text":" Attack!"
    }
  ],
  "Ergebnistyp":"sum", // Der Gesamtergebnistyp des gesamten Wurfs
  "Gesamt":11 // Der Gesamttotal des gesamten Wurfs (inklusive aller Untergruppen)
}

Rollergebnisstruktur Bsp. 2

Eine kommentierte Struktur für das Ergebnis von /roll {1d6!!>5}>6 (mit Angaben zu Explosionsmodifikatoren und Zielerfolgen):

{
  "Typ":"V",
  "Würfe": [
    {
      "Typ":"G",
      "Würfe": [
        [
          {
            "Typ":"R",
            "Würfel":1,
            "Seiten":6,
            "Mods": { //Änderungen an dem Wurf
              "kombinierend": { //"kombinierend" = "Kombinierend explodierend (!!)"
                "comp":">=", //Vergleichsart
                "punkt":5 //Vergleichspunkt
              }
            },
            "Ergebnisse": [
              {
                "v":13 //Gesamtwürfelergebnis. Beachten Sie, dass es nur ein Würfelergebnis gibt, da es sich hier um eine explodierende Kombination handelt.
              }
            ]
          }
        ]
      ],
      "Mods": {
        "Erfolg": {
          "comp":">=",
          "punkt":6
        }
      },
      "Ergebnistyp":"sum",
      "Ergebnisse": [
        {
          "v":13
        }
      ]
    }
  ],
  "Ergebnistyp":"Erfolg", // In diesem Fall ist das Ergebnis eine Anzahl von Erfolgen
  "Gesamt":1 // Gesamtanzahl der Erfolge
}

Beispiel für ein Chat-Ereignis (Implementierung eines benutzerdefinierten Wurftyps)

on("chat:message", function(msg) {
  // Spieler geben „!d6 3“ ein, um so viele Sechsenseiter gegen eine Zielzahl von 4 zu würfeln.
  if (msg.type !== "api" || msg.content.indexOf("!d6 ") !== 0) return;
  var numdice = parseInt(msg.content.substring(4), 10);
  if (!numdice || numdice < 1) return;
  var who = msg.who.replace(/ \(GM\)$/, "");
  sendChat(who, "/roll " + numdice + "d6>4");
});

sendChat(speakingAs, input [,callback [, options]] )

Du kannst diese Funktion verwenden, um eine Chat-Nachricht zu senden.

speakingAs kann eines der folgenden sein:

  • Eine beliebige Zeichenfolge. In diesem Fall wird sie als Name der Person verwendet, die die Nachricht gesendet hat. Z. B. „Riley“
  • Die ID eines Spielers, formatiert als "player|-Abc123", wobei -Abc123 die ID des Spielers ist. Wenn du das machst, werden automatisch der Avatar und der Name des Spielers übernommen.
  • Die ID eines Charakters, formatiert als "character|-Abc123". Wenn du das machst, werden automatisch der Avatar und der Name des Charakters verwendet.

input sollte ein beliebiger gültiger Ausdruck sein, genau wie die, die in der Roll20-App verwendet werden. Du gibst Text ein, um eine einfache Nachricht zu senden, oder verwendest Slash-Befehle wie /roll, /em, /w, /secretroll (/sr), /supersecretroll (/ssr), /secret (/s), /supersecret (/ss) usw. Zusätzlich:

  • Du kannst Charakterattribute im Format @{CharacterName|AttributeName} verwenden.
  • Du kannst Charakterfähigkeiten im folgenden Format verwenden: %{CharacterName|AbilityName}.
  • Du kannst Makros nicht über sendChat aufrufen, so wie ein Spieler #MacroName eingibt. Ein Knopf kann beim Anklicken ein Makro ausführen: [Name](!&#13;#MacroName).
  • @{selected|...} wird innerhalb von sendChat nicht aufgelöst. Lies stattdessen msg.selected in einem chat:message-Handler aus.
  • Normale Nachrichten und Flüsternachrichten können die folgenden HTML-Stichwörter enthalten. /direct <msg> sendet die Nachricht ohne Markdown und ohne automatische URL-Verlinkung und kann dieselben Stichwörter verwenden:
<code><span><div><label><a><br><br /><p><b><i><del><strike><u><img>
<blockquote><mark><cite><small><ul><ol><li><hr><dl><dt><dd><sup>
<sub><big><pre><figure><figcaption><strong><em><table><tr><td><th>
<tbody><thead><tfoot><h1><h2><h3><h4><h5><h6>

callback ist ein optionaler dritter Parameter, der aus einer Callback-Funktion besteht, an die die Ergebnisse des Aufrufs von sendChat() übergeben werden, anstatt die Befehle an das Spiel zu senden. Die Verwendung von sendChat() auf diese Weise erfolgt asynchron. Das Ergebnis des Befehls sendChat() ist ein ARRAY von Operationen, und jedes einzelne Objekt entspricht genau einem Objekt, das du bei einem chat:message-Ereignis erhältst (siehe oben).

Sie können dies beispielsweise verwenden, um einen Wurf mit der Roll20-Roll-Engine durchzuführen und dann sofort die Ergebnisse des Wurfs zu erhalten. Anschließend können Sie weitere Änderungen am Wurf vornehmen, bevor Sie ihn an die Spieler im Spiel senden.

sendChat("Riley", "/roll 1d20+4", function(ops) {
  // ops ist ein ARRAY mit den Befehlsergebnissen.
  var rollresult = ops[0];
  //Jetzt mach etwas mit rollresult, genau wie du es bei einem chat:message-Ereignis tun würdest ...
});

options ist ein optionaler vierter Parameter, mit dem du Optionen für die Verarbeitung der Nachricht festlegen kannst. Optionen werden als JavaScript-Objekt angegeben, dessen Eigenschaften die Namen der festzulegenden Optionen sind und dessen Werte die entsprechenden Einstellungen darstellen – in der Regel true, da sie standardmäßig false sind.

Verfügbare Optionen:

  • noarchive – Setze diesen Wert auf „true“, um zu verhindern, dass die Nachricht im Chat-Protokoll gespeichert wird. Das ist besonders nützlich für Ausgaben, die nicht Teil der Geschichte sind, wie zum Beispiel Menüs von Mod-Skript-Knöpfen und Statusinformationen.
  • use3d – Du kannst jetzt mit der Funktion sendChat() Würfe mit 3D Würfeln generieren. Die Syntax ist ganz einfach: sendChat("Name", "Rolling [[3d6]]", null, {use3d: true}); Wenn du dem Parameter name eine Spieler-ID übergibst, z. B. sendChat("player|-ABC123",...), wird die Farbe des Spielers für die Würfel verwendet. Andernfalls wird die Standardfarbe Weiß verwendet.

Hinweis: Clients können jeweils nur das Ergebnis eines 3D-Wurfs anzeigen, daher ist es nicht sinnvoll, mehrere separate 3D-Würfe hintereinander zu erzeugen. Beachte außerdem, dass die Verwendung von 3D-Würfen den Quantenwurf-Server etwas stärker belastet. Nutze also dein Urteilsvermögen und führe nicht 100 3D-Würfe innerhalb einer Sekunde aus. Verwende 3D-Würfe, wenn der Wurf für den Spieler wichtig ist und sich auf das Spiel auswirkt.

Wenn du diese Optionen anpassen möchtest, aber keinen callback-Parameter (dritter Parameter – siehe oben) verwenden willst, kannst du an seiner Stelle einfach null übergeben:

sendChat("Status", "Alle Spieler sind angemeldet.", null, {noarchive:true});

Mod-Skript-Befehls-Knöpfe

Die Formatierung im Text-Chat, in Mod-Skript-Nachrichten sowie in Makros und Fähigkeiten kann Befehls-Knöpfe im Chat erzeugen.

Dazu kannst du die Markdown-Formatierung verwenden:

[Angriffswurf](!attackroll)

Der Text zwischen den Klammern wird in der Schaltfläche angezeigt und der Teil in den Klammern ist der auszuführende Befehl. Sie können alles in einen normalen Wurf einfügen (Makros, Fähigkeiten, Abfragen usw.), aber bedenken Sie, dass der Befehl selbst von dem Spieler ausgeführt wird, der darauf klickt. Füge zum Beispiel nicht @{Character|AC} ein, wenn nicht jeder, der die Nachricht sehen kann, auch auf diesen Charakter zugreifen kann. Fügen Sie stattdessen den tatsächlichen Wert ein, der beim Senden des Befehls vorlag, indem Sie ihn selbst ausfüllen, bevor Sie die Chat-Nachricht senden. Diese Knöpfe funktionieren in allgemeinen Nachrichten, Flüsternachrichten und Flüsternachrichten an den SL. Der Klick wird als der Spieler ausgeführt, der klickt, mit der playerid dieses Spielers und dessen selected.

/direct überspringt Markdown, daher wird aus [Attack Roll](!attackroll) kein Knopf.

Mod-Skript-Knöpfe im Chat eingeben

Du kannst auch Mod-Skript-Knöpfe in Markdown-Syntax in den Chat eingeben, damit andere sie verwenden können. Da sie vom Chat-Parser interpretiert werden, müssen Sie Teile des Befehls mit einer speziellen Syntax (HTML-Entitäten) eingeben, wenn Sie möchten, dass Attribute, Abfragen und Rollen beim Klicken auf die Schaltfläche erweitert werden:

Charakter Ersatz
% &#37;
) &#41;
? &#63;
@ &#64;
[ &#91; oder &lbrack;
] &#93; oder &rbrack;
{ &#123;
} &#125;
| &#124;
, &#44;

Diese Beispielschaltfläche verwendet einige davon:

[Angriffswurf](!attackroll &#64;{target|token_id} &#91;[1d6+&#63;{Bonus|0}]&#93;)

Du kannst die Mod-Skript-Knöpfe tatsächlich nutzen, um Makros oder Fähigkeiten aufzurufen.

Charakter Ersatz
<carriage return> &#13;

Dazu beginnst du den Befehlsteil einfach mit dem Sondercode !&#13; und fügst dann den Makroaufruf mit # oder den Fähigkeitsaufruf mit &#37; (%) hinzu:

[Macro](!&#13;#MakroName)

[Ability](!&#13;&#37;{CharName|AbilityName})

Hinweis: Wenn du derzeit ein Makro erneut öffnest, das unter dem Reiter „Sammlungen“ der Seitenleiste gespeichert ist, werden die darin enthaltenen HTML-Entitäten zurückgesetzt; wenn das Makro anschließend gespeichert wird, werden auch diese Rücksetzungen gespeichert. Dieses Verhalten tritt nicht auf in Fähigkeiten oder Fähigkeits-Befehls-Knöpfen.

Bei Fähigkeits-Befehls-Knöpfen gilt: Wenn sich sowohl die Fähigkeit, die den Knopf erstellt, als auch die Fähigkeit, auf die er verweist, auf demselben Bogen befinden, ist die Syntax ganz einfach:

[Ability](~AbilityName)

War dieser Beitrag hilfreich?
17 von 26 fanden dies hilfreich