API: Chat

Auf dieser Seite werden Details zur Roll20-API in Bezug auf Chat-Funktionen beschrieben.


Chat-Events

chat:Nachricht

Wird immer dann ausgelöst, wenn eine neue Chat-Nachricht empfangen wird. Beachten Sie, dass Sie, wenn die Nachricht vom Typ „rollresult“ oder „gmrollresult“ ist,JSON.parse() für den Inhalt der Nachricht aufrufen müssen, um ein Objekt zu erhalten, das Informationen zu den Rollergebnissen enthält.

Hinweis:Wenn ein Spieler eine Chat-Nachricht eingibt, die mit einem Ausrufezeichen (!) beginnt, hat diese Nachricht den Typ „API“ und wird niemandem angezeigt. Es ist beabsichtigt, dass diese Funktionalität verwendet werden kann, um Befehle bereitzustellen, auf die Mod (API)-Skripte reagieren. Wenn die Nachricht vom Typ "API" ist, wurde sie noch niemandem angezeigt, und der Spieler, der die Chat-Nachricht gesendet hat, erwartet wahrscheinlich, dass ein Mod (API)-Skript als Ergebnis der Nachricht etwas tut.

Rückrufparameter:

Eigentum Standardwert Anmerkung
WHO „“ Der Anzeigename des Spielers oder Charakters, der die Nachricht gesendet hat.
Spieler-ID   Die ID des Spielers, der die Nachricht gesendet hat.
Art "allgemein" Eines von „general“, „rollresult“, „gmrollresult“, „emote“, „whisper“, „desc“ oder „api“.
inhalt „“ Der Inhalt der Chat-Nachricht. WennTyp„rollresult“ ist, ist dies eine JSON-Zeichenfolge mit Daten über die Rolle.
origRoll   (nur „rollresult“ oder „gmrollresult“ eingeben)Der Originaltext des Wurfs, z. B. „2d10+5 Feuerschaden“, wenn der Spieler „/r 2d10+5 Feuerschaden“ eingibt. Dies entspricht der Verwendung vonInhaltfür Nachrichten mit anderen Typen als „rollresult“ oder „gmrollresult“.
Inlinerollen   (Inhalt enthält nur eine oder mehrere Inline-Rollen)Ein Array von Objekten mit Informationen zu allen Inline-Rollen in der Nachricht.
Rollenvorlage   (Inhalt enthält nur eine oder mehrere Rollenvorlagen)Der Name der angegebenen Vorlage.
target   (nur „Whisper“ eingeben)Die Spieler-ID der Person, an die das Whisper gesendet wird. Wenn das Flüstern an den GM gesendet wurde, ohne dessen Anzeigenamen zu verwenden (z. B. „/w gm text“ anstelle von „/w Riley text“, wenn Riley der GM ist), oder wenn das Flüstern an einen Charakter ohne Verwendung dieses Namens gesendet wurde Bei kontrollierenden Spielern lautet der Wert „gm“.
Zielname   (nur „Whisper“ eingeben)Der Anzeigename des Spielers oder Charakters, an den das Whisper gesendet wurde.
ausgewählt   (nur Typ „api“)Ein Array von Objekten, die der Benutzer ausgewählt hatte, als der Befehl eingegeben wurde.

Hinweis:Sie benötigen wahrscheinlich nicht alle diese Informationen. In den meisten Fällen interessiert Sie nur das Gesamtergebnis des Wurfs (siehe unten im ersten Beispiel). Es wird jedoch alles bereitgestellt, wenn Sie wirklich tiefer in die Ergebnisse eines Wurfs eintauchen möchten.

 


Rollergebnisstruktur Bsp. 1

Nachdem SieJSON.parsefür diecontentEigenschaft einer „rollresult“- oder „gmrollresult“-Nachricht aufgerufen haben, erhalten Sie ein Objekt mit dem folgenden Format (dies ist das Ergebnis des Befehls. /roll {2d6}+5+1t[weather] Angriff!)

{
  „type“: „V“, // „V“ = „Validated Roll“ (dies wird im Moment immer „V“ sein)
  „rolls“: [
    {
      „type“: „G“, // „G“ zeigt eine gruppierte Rolle an. Eine Gruppe ist wie eine Reihe von „Unterrollen“ innerhalb einer Rolle.
      „rolls“: [
        [
          {
            „type“: „R“, // „R“ = „Roll“
            „dice“:2, // Anzahl der gewürfelten Würfel (2dX bedeutet 2 Würfel)
            „Seiten“ :6, //Anzahl der Würfelseiten (Xd6 bedeutet 6 Seiten)
            "mods":{},
            "results": [ //Ein Array der Ergebnisse jedes Wurfs.
             {
               "v":1 // Wir haben eine 1 für unseren ersten 2W6
             },
             {
               "v":5 //Wir haben eine 5 für unseren zweiten 2W6
             }
            ]
          }
        ]
      ],
      gewürfelt „mods“:{},
      „resultType“: „sum“, //Das Ergebnis ist eine Summe (im Gegensatz zu einer Erfolgsprüfung)
      „results“: [
        {
          „v“:6 // In diesem Fall , das Gesamtergebnis (total) der Gruppe.
        }
      ]
    },
    {
      "type": "M", //"M" = Mathe-Ausdruck
      "expr": "+5+"
    },
    {
      "type": "R", / /"R" = Würfeln Sie
      „Würfel“:1,
      „Tisch“: „Wetter“, // Die Tabelleneigenschaft wird auf den Namen des verwendeten Tisches gesetzt, wenn dieser Wurf gegen einen Tisch
      „Mods“:{ durchgeführt wurde. },
      "sides":2, //Sie können dies wahrscheinlich für Tischrollen einfach ignorieren.
      "results": [
        {
          "v":0, //Der „Wert“ des gewürfelten Tabellenelements. Bei Texttabellen ist dieser immer 0.
          "tableidx":1, //Der Index des Elements in der Tabelle, das gerollt wurde.
          "tableItem": { //Eine Kopie des Tabellenelementobjekts, wie es beim Rollen der Tabelle vorhanden war.
            „name“: „rainy“, 
            „avatar“: „, // Dies ist eine URL zu einem Bild, wenn der rollbare Tisch Bildsymbole verwendet
            „weight“:1,
            „id“: „-IpzPx2j_9piP09ceyOv“
          }
        }
      ]
    },
    {
      „type“: „C“, // „C“ = Kommentar
      „text“: „Angriff!“
    }
  ],
  „resultType“: „sum“, // Der Gesamtergebnistyp der gesamten Rolle
  „total“:11 // Die Gesamtsumme der gesamten Rolle (einschließlich aller Untergruppen)
}

Rollergebnisstruktur Bsp. 2

Eine kommentierte Struktur für das Ergebnis von/roll {1d6!!>5}>6(zeigt explodierende Modifikationen und Zielerfolge):

{
  „Typ“: „V“,
  „Würfel“: [
    {
      „Typ“: „G“,
      „Würfel“: [
        [
          {
            „Typ“: „R“,
            „Würfel“ :1,
            "sides":6,
            "mods": { //Änderungen an der Rolle
              "compounding": { //"compounding" = "Compounding explodiert (!!)"
                "comp": ">=", //Vergleichstyp
                "point":5 //Vergleichspunkt
              }
            },
            "results": [
              {
                "v":13 //Gesamtwürfelergebnis. Beachten Sie, dass es nur ein Würfelergebnis gibt, da es sich hier um eine explodierende Kombination handelt.
              }
            ]
          }
        ]
      ],
      „mods“: {
        „success“: {
          „comp“: „>=",
          „point":6
        }
      },
      „resultType“: „sum ",
      „results“: [
        {
          „v“:13
        }
      ]
    }
  ],
  „resultType“: „success“, // In diesem Fall ist das Ergebnis eine Anzahl von Erfolgen insgesamt
  „ ":1 //Gesamtzahl der Erfolge
}

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

on("chat:message", function(msg) {
  //Dies ermöglicht es Spielern, !sr <number> einzugeben, um eine Anzahl von W6-Würfeln mit einem Ziel von 4 zu würfeln.
  if(msg.type == "api" && msg.content.indexOf("!sr ") !== -1) {
    var numdice = msg.content.replace("!sr ", "");
    sendChat(msg.who, „/roll“ + numdice + „d6>4“);
  }
});

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

Mit dieser Funktion können Sie eine Chat-Nachricht versenden.

speakAskann einer von 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 Sie dies tun, werden automatisch der Avatar und der Name des Spielers verwendet.
  • Die ID eines Charakters, formatiert als"character|-Abc123". Wenn Sie dies tun, werden automatisch der Avatar und der Name des Charakters verwendet.


Eingabesollte ein beliebiger gültiger Ausdruck sein, genau wie die, die in der Roll20-App verwendet werden. Sie geben Text ein, um eine einfache Nachricht zu senden, oder verwenden Schrägstrichbefehle wie „/roll“, „/em“, „/w“ usw. Zusätzlich:

  • Sie können Zeichenattribute mit dem Format@{CharacterName|AttributeName}verwenden.
  • Sie können Charakterfähigkeiten mit dem Format verwenden:%{CharacterName|AbilityName}.
  • SieMakros verwenden.
  • Sie können den Befehl „/direct <msg>“ verwenden, um eine Nachricht ohne jegliche Verarbeitung (z. B. automatische Verknüpfung von URLs) zu senden, und Sie können die folgenden HTML-Tags in der Nachricht verwenden:

 

<code><span><div><label><a><br><br /><p><b><i><del><strike><u><img>
<blockquote><mark><cite><h6><small><ul><ol><li><hr><dl><dt><dd>
<td><sub><pre><figure><big><figcaption><strong><sup><em><tr><table><th>
<tbody><h4><tfoot><thead><h1><h2><h3><h5>

Rückrufist ein optionaler dritter Parameter, der aus einer Rückruffunktion besteht, der die Ergebnisse des AufrufssendChat()übergeben werden, anstatt die Befehle an das Spiel zu senden. Die Verwendung vonsendChat()auf diese Weise ist asynchron. Die Ergebnisse des BefehlssendChat()sind ein ARRAY von Operationen, und jedes einzelne Objekt ist genau wie ein Objekt, das Sie während eines Ereignisseschat:messageerhalten (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 wird ein ARRAY von Befehlsergebnissen sein.
    var rollresult = ops[0];
    //Jetzt machen Sie etwas mit rollresult, genau wie Sie es während eines chat:message-Ereignisses tun würden ...
});

Optionenist ein optionaler vierter Parameter zum Festlegen von Optionen für die Behandlung der Nachricht. Optionen werden als Javascript-Objekt angegeben, dessen Eigenschaften die Namen der festzulegenden Optionen sind und dessen Werte die Einstellungen für sie sind, im Allgemeinenwahrda sie standardmäßig auf falsch eingestellt sind.

Verfügbare Optionen:

  • noarchive -- setze dies auf true, um zu verhindern, dass die Nachricht im Chatprotokoll gespeichert wird. Dies ist besonders nützlich für Ausgaben, die nicht Teil der Geschichte sind, wie Mod (API)-Knopfmenüs und Statusinformationen.
  • use3d– Sie können jetzt 3D-Würfelwürfe mit der Funktion sendChat() generieren. Die Syntax ist einfach:sendChat("Name", "Rolling [[3d6]]", null, {use3d: true});Wenn Sie eine Spieler-ID an den Namensparameter übergeben, 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 einer 3D-Rolle anzeigen, daher ist es nicht sinnvoll, mehrere separate 3D-Rollen hintereinander zu erstellen. Beachten Sie außerdem, dass die Verwendung von 3D-Würfen den QuantumRoll-Server etwas stärker belastet. Seien Sie also urteilsfähig und führen Sie nicht innerhalb einer Sekunde 100 3D-Würfe durch. Verwenden Sie 3D-Würfe, wenn der Wurf für den Spieler „wichtig“ ist und einen Einfluss auf das Spiel hat.

    Wenn Sie diese Optionen anpassen möchten, aber keinenCallback-Parameter (dritter Parameter – siehe oben) verwenden möchten, können Sie einfachnullan seiner Stelle übergeben:

 

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

Mod (API)-Befehl Knöpfe

Jetzt mit dem Update von Holding kannst du von der neuen Textchat-Formatierung (in deinen API-generierten Nachrichten und denen, die von Makros und Fähigkeiten generiert werden) profitieren, um "Mod (API)-Befehl knöpfe" im Chat zu erstellen.

Gehen Sie dazu mithilfe der Markdown-Formatierung wie folgt vor:

[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. Geben Sie beispielsweise @{Character|AC} nicht ein, wenn nicht jeder, der die Nachricht sehen kann, auf dieses Zeichen 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 Schaltflächen funktionieren in allen Nachrichtentypen, allgemeinen Nachrichten, Flüsternachrichten, GMWhispers usw.

Beachten Sie, dass wir keine Markdown-Analyse durchführen, wenn Sie /direct zum Senden einer Nachricht verwenden. Sie müssen also Ihre eigenen <a> -Tags einfügen. Hier ist ein Beispiel dafür:

<a href="!attackroll">Angriffswurf</a>

Eingabe von Mod (API)-Knöpfen im Chat

Du kannst auch Markdown-Syntax Mod (API)-Knöpfe in den Chat tippen, 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:

PC sheet Ersatz
 % &#37;
) &#41;
 ? &#63;
@ &#64;
[ &#91; oder &lbrack;
] &#93; oder &rbrack;

Diese Beispielschaltfläche verwendet einige davon:

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

Du kannst tatsächlich die Mod (API)-Knöpfe verwenden, um Makros oder Fähigkeiten aufzurufen.

PC sheet Ersatz
<carriage return> &#13;

Dazu beginnen Sie den Befehlsteil einfach mit dem Sondercode!&#13;Fügen Sie dann den Makroaufruf mit#oder den Fähigkeitsaufruf mit&#37 hinzu;(%):

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

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

Hinweis:Zu diesem Zeitpunkt führt das erneute Öffnen eines Makros, das auf der Registerkarte „Sammlungen“ der Seitenleiste gespeichert ist, dazu, dass darin enthaltene HTML-Entitäten zurückgesetzt werden. Wenn das Makro dann gespeichert wird, werden auch diese Umkehrungen gespeichert. Dieses Verhalten ist beiFähigkeitenoder Fähigkeitsbefehlsschaltflächen nicht vorhanden.

Wenn sich fürAbility Command Buttonsdie Fähigkeit, die die Schaltfläche erstellt, und die Fähigkeit, auf die sie verweist, beide auf demselben Blatt befinden, ist die Syntax sehr einfach:

[Ability](~AbilityName)

War dieser Beitrag hilfreich?
14 von 21 fanden dies hilfreich