API: Chat

Chat-Events

chat:message

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

Callback-Parameter:

Rollergebnisstruktur Bsp. 1

Nachdem du den JSON.parse-Befehl für die content-Eigenschaft einer "rollresult"- oder "gmrollresult"-Nachricht aufgerufen hast, erhältst du ein Objekt mit folgendem Format (dies ist das Ergebnis des Befehls /roll {2d6}+5+1t[weather] Angriff!)

{
  "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 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.
        }
      ]
    },
    {
      "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 die URL zu einem Bild, falls die würfelbare Tabelle Bildsymbole verwendet
            "gewichtung":1,
            "id":"-IpzPx2j_9piP09ceyOv"
          }
        }
      ]
    },
    {
      "type":"C", // "C" = Kommentar
      "text":" Angriff!"
    }
  ],
  "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 (zeigt explodierende Modifikationen und Zielerfolge):

{
  "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
}

Chat-Ereignis Beispiel (Implementierung eines benutzerdefinierten Würfeltyps)

on("chat:message", function(msg) {
  //Dies ermöglicht es Spielern, !sr  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]] )

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

speakingAs kann eines von 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 dies tust, werden automatisch der Avatar und der Name des Spielers verwendet.
• Die ID eines Charakters, formatiert als"character|-Abc123". Wenn du dies tust, 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:

• Du kannst Charakterattribute mit dem Format @{CharacterName|AttributeName} verwenden.
• Du kannst Charakterfähigkeiten mit dem Format verwenden: %{CharacterName|AbilityName}.
• Dukannst keineMakros verwenden.
• Du kannst den Befehl „/direct “ verwenden, um eine Nachricht ohne jegliche Verarbeitung (z. B. automatische Verknüpfung von URLs) zu senden, und du kannst 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><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 Rückruffunktion besteht, welcher die Ergebnisse des Aufrufs sendChat() ü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 ist ein ARRAY mit den Ergebnissen des Befehls.
    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 Chat-Protokoll gespeichert wird. Das ist besonders nützlich für Ausgaben, die nicht zur Story gehören, z. B. 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 eines 3D-Wurfs anzeigen, daher ist es nicht sinnvoll, mehrere separate 3D-Würfe 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. Verwende 3D-Würfe, wenn der Wurf für die Spieler „wichtig“ ist und einen Einfluss auf das Spiel hat.

  Wenn du diese Optionen ändern möchtest, aber keinen Callback-Parameter (dritter Parameter – siehe oben) verwenden möchtest, kannst du einfach null anstelle dessen übergeben:

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

Mod (API)-Befehls-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)-Befehls-Knöpfe" im Chat zu erstellen.

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. 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>

Mod-(API)-Knöpfe im Chat eingeben

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:

Diese Beispielschaltfläche verwendet einige davon:

[Angriffswurf](!attackroll @{target|token_id} [[1d6+?{Bonus|0}]])

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

Dazu beginnst du den Befehlsteil einfach mit dem Sondercode !
, dann fügst du den Makro-Aufruf mit # oder den Fähigkeitsaufruf mit % (%) hinzu:

[Macro](!
#MakroName)

[Ability](!
%{CharName|AbilityName})

Wenn sich für Fähigkeits-Knöpfe die Fähigkeit, die den Knopf erstellt, und die Fähigkeit, auf die er verweist, beide auf demselben Bogen befinden, ist die Syntax sehr einfach:

[Ability](~AbilityName)