API: Chat

Cette page décrit les détails relatifs à l'API Roll20 en ce qui concerne les fonctions de chat.


Événements de Chat

chat:message

Déclenché chaque fois qu'un nouveau message de chat est reçu. Notez que si le message est de type "rollresult" ou "gmrollresult", vous devrez appelerJSON.parse() sur le contenu du message pour obtenir un objet contenant des informations sur les résultats des jets.

Note :Si un joueur entre un message de chat commençant par un point d'exclamation ( !), ce message aura le type "api" et ne sera montré à personne. Il est prévu que cette fonctionnalité puisse être utilisée pour fournir des commandes auxquelles les scripts API répondent. Donc, si le message est de type "api", alors il n'a été vu par personne et le joueur qui a envoyé le message de chat s'attend probablement à ce qu'un script API fasse quelque chose en réponse au message.

Paramètre de rappel :

Propriété Valeur par défaut Notes
qui "" Le nom d'affichage du joueur ou du personnage qui a envoyé le message.
playerid   L'ID du joueur qui a envoyé le message.
type "général" L'un des éléments suivants : "general", "rollresult", "gmrollresult", "emote", "whisper", "desc" ou "api".
contenu "" Le contenu du message de chat. Si le typeest "rollresult", il s'agira d'une chaîne JSON contenant des données sur le rouleau.
origRoll   (type "rollresult" ou "gmrollresult" uniquement)Le texte original du jet, par exemple "2d10+5 fire damage" lorsque le joueur tape "/r 2d10+5 fire damage" : "2d10+5 dégâts de feu" lorsque le joueur tape "/r 2d10+5 dégâts de feu". Cela équivaut à l'utilisation decontentpour les messages dont le type est autre que "rollresult" ou "gmrollresult".
inlinerolls   (le contenu ne contient qu'un ou plusieurs rouleaux en ligne)Tableau d'objets contenant des informations sur tous les rouleaux en ligne du message.
rolltemplate   (content contains one or more roll templates only)The name of the template specified.
target   (type "whisper" only)The player ID of the person the whisper is sent to. If the whisper was sent to the GM without using his or her display name (ie, "/w gm text" instead of "/w Riley text" when Riley is the GM), or if the whisper was sent to a character without any controlling players, the value will be "gm".
target_name   (type "whisper" only)The display name of the player or character the whisper was sent to.
selected   (type "api" only) Un tableau d'objets que l'utilisateur avait sélectionné lorsque la commande a été entrée.

Remarque : Tu n'auras probablement pas besoin de toutes ces informations. Dans la plupart des cas, tu t'intéresseras seulement au résultat global du jet de dés (voir la fin du premier exemple). Cependant, tout est fourni si tu veux vraiment creuser davantage dans les résultats d'un jet de dés.

 


Structure du Résultat du Jet Ex. 1

Après avoir appeléJSON.parsesur la propriétécontentd'un message "rollresult" ou "gmrollresult", vous obtiendrez un objet au format suivant (c'est le résultat de la commande/roll {2d6}+5+1t[weather] Attack !)

{
  "type" : "V", //"V" = "Rouleau validé" (ce sera toujours "V" pour l'instant)
  "rolls" : [
    {
      "type" : "G", //"G" indique un rouleau groupé. Un groupe est comme une série de "sous-rouleaux" à l'intérieur d'un rouleau.
      "rolls" : [
        [
          {
            "type" : "R", // "R" = "Roll"
            "dice":2, // Nombre de dés lancés (2dX signifie 2 dés)
            "sides":6, //Nombre de faces pour le dé (Xd6 signifie 6 faces)
            "mods":{},
            "results" : [ //An array of the results of each roll.
             {
               "v":1 // Nous avons obtenu un 1 pour notre premier 2d6
             },
             {
               "v":5 //Nous avons obtenu un 5 pour notre deuxième 2d6
             }
            ]
          }
        ]
      ],
      "mods":{},
      "resultType":"somme", //Le résultat est une somme (par rapport à une vérification de succès)
      "results": [
        {
          "v":6 // Dans ce cas, le résultat global (total) du groupe.
        }
      ]
    },
    {
      "type":"M", //"M" = Expression mathématique
      "expr":"+5+"
    },
    {
      "type":"R", //"R" = Lancer
      "dice":1,
      "table":"météo", //La propriété table est définie avec le nom de la table utilisée si ce lancer a été effectué contre une table
      "mods":{},
      "sides":2, //Vous pouvez probablement ignorer ceci pour les lancers de table.
      "results": [
        {
          "v":0, //La "valeur" de l'élément de table tiré. Pour les tables de texte, cela est toujours 0.
          "tableidx":1, //L'index de l'élément dans la table qui a été roulé.
          "tableItem": { //Une copie de l'objet d'élément de table tel qu'il existait lorsque la table a été roulée.
            "name":"pluvieux", 
            "avatar":"", //Il s'agit d'une URL vers une image si la table de dés utilise des icônes d'image
            "poids":1,
            "id":"-IpzPx2j_9piP09ceyOv"
          }
        }
      ]
    },
    {
      "type":"C", // "C" = Commentaire
      "text":" Attaque !"
    }
  ],
  "resultType":"somme", //Le type de résultat global du lancer complet
  "total":11 //Le total global du lancer complet (incluant tous les sous-groupes)
}

Structure du Résultat de Lancer Ex. 2

Une structure annotée pour le résultat de /roll {1d6!!>5}>6 (montrant les modifications explosives et les réussites cibles) :

{
  "type" : "V",
  "rouleaux" : [
    {
      "type" : "G",
      "rolls" : [
        [
          {
            "type" : "R",
            "dice":1,
            "sides":6,
            "mods" : { //Modifications du jet
              "compounding" : { //"compounding" = "Compounding exploding ( !!)"
                "comp" :">=", //Comparaison type
                "point":5 //Point de comparaison
              }
            },
            "results" : [
              {
                "v":13 //Résultat global du dé. Notez que puisqu'il s'agit d'une explosion composée, il n'y a qu'un seul résultat au dé.
              }
            ]
          }
        ]
      ],
      "mods": {
        "success": {
          "comp":">=",
          "point":6
        }
      },
      "resultType":"sum",
      "results": [
        {
          "v":13
        }
      ]
    }
  ],
  "resultType":"success", // Dans ce cas, le résultat est un nombre de réussites
  "total":1 //Nombre total de réussites
}

Chat Event Example (Implémentation d'un type de roll personnalisé)

on("chat:message", function(msg) {
  //Cela permet aux joueurs de saisir !sr <number> pour lancer un certain nombre de dés d6 avec une cible de 4.
  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]] )

You can use this function to send a chat message.

speakingAs can be one of:

  • Any string, in which case that will be used as the name of the person who sent the message. E.g. "Riley"
  • A player's ID, formatted as "player|-Abc123" where "-Abc123" is the ID of the player. Dans ce cas, l'avatar et le nom du joueur seront automatiquement utilisés.
  • L'identifiant d'un personnage, formaté comme suit :"character|-Abc123". Dans ce cas, l'avatar et le nom du personnage seront automatiquement utilisés.


inputdoit être une expression valide, comme celles utilisées dans l'application Roll20. Vous pouvez saisir du texte pour envoyer un message de base ou utiliser des commandes de type "slash" telles que "/roll", "/em", "/w", etc. En outre :

  • Vous pouvez utiliser des attributs de caractères au format@{CharacterName|AttributeName}.
  • Vous pouvez utiliser les capacités des personnages au format :%{CharacterName|AbilityName}.
  • Vousne pouvez pasutiliser des macros.
  • Vous pouvez utiliser la commande "/direct <msg>" pour envoyer un message sans aucun traitement (par exemple, l'établissement automatique de liens URL) et vous pouvez utiliser les balises HTML suivantes dans le message :

 

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

callbackest un troisième paramètre facultatif qui consiste en une fonction de rappel à laquelle seront transmis les résultats de l'appelsendChat()au lieu d'envoyer les commandes au jeu. Utiliser la méthode sendChat()de cette manière est asynchrone. Les résultats de la commandesendChat()seront un ARRAY d'opérations, et chaque objet individuel sera comme un objet que vous recevez lors d'un événementchat:message(voir ci-dessus).

Vous pouvez utiliser cela, par exemple, pour effectuer un jet de dé en utilisant le moteur de dés Roll20, puis obtenir immédiatement les résultats du jet. Vous pouvez ensuite effectuer des modifications supplémentaires sur le jet avant de l'envoyer aux joueurs dans le jeu.

sendChat("Riley", "/roll 1d20+4", function(ops) {
    // ops sera un TABLEAU des résultats de la commande.
    var resultatroule = ops[0];
    //Maintenant, faites quelque chose avec resultatroule, tout comme vous le feriez lors d'un événement chat:message...
});

options est un quatrième paramètre facultatif permettant de définir des options pour la gestion du message. Les options sont spécifiées sous forme d'objet JavaScript dont les propriétés correspondent aux noms des options à définir et dont les valeurs correspondent à leurs paramètres, généralementtrue car elles ont une valeur par défaut de false.

Options disponibles:

  • noarchive - Définissez cette option sur true pour empêcher l'enregistrement du message dans le journal de discussion. Ceci est particulièrement utile pour les sorties qui ne font pas partie de l'histoire, telles que les menus boutons d'API et les informations d'état.
  • use3d - Vous pouvez maintenant générer des lancers de dés en 3D en utilisant la fonction sendChat(). La syntaxe est simple :sendChat("Nom", "Lancer [[3d6]]", null, {use3d: true}); Si vous passez un ID de joueur au paramètre de nom, par exemplesendChat("joueur|-ABC123",...), la couleur du joueur sera utilisée pour le dé. Sinon, une couleur blanche par défaut sera utilisée. 

    Remarque : Les clients ne peuvent afficher qu'un seul résultat simultané de lancers de dés en 3D, donc effectuer plusieurs lancers de dés en 3D à la suite n'est pas utile. Notez également que l'utilisation de lancers de dés en 3D exerce une pression supplémentaire sur le serveur QuantumRoll, donc utilisez votre jugement et ne réalisez pas 100 lancers de dés en 3D en une seconde. Utilisez les lancers de dés en 3D lorsque le lancer aura une "importance" pour le joueur et aura un impact sur le jeu.

    Si vous souhaitez ajuster ces options, mais que vous ne voulez pas utiliser unrappel paramètre (troisième paramètre -- voir ci-dessus), vous pouvez simplement passernull à sa place:

 

sendChat("Statut", "Tous les joueurs sont connectés.", null, {noarchive:true} );

Boutons de commande API

Maintenant disponible avec la mise à jour de la détention, vous pouvez profiter du nouveau formatage du chat texte (à la fois vos messages générés par l'API et ceux générés par des macros et des compétences) pour créer des « boutons de commande API » dans le chat.

Pour ce faire en utilisant le formatage Markdown:

[Jet d'attaque](!attackroll)

Le texte entre les crochets apparaîtra dans le bouton, et la partie entre les parenthèses est la commande à exécuter. Vous pouvez inclure n'importe quoi dans un jet normal (macros, compétences, requêtes, etc.), mais gardez à l'esprit que la commande elle-même sera exécutée par le joueur qui clique dessus. Par exemple, n'incluez pas @{Character|AC} si tout le monde qui peut voir le message ne peut pas accéder à ce personnage. Au lieu de cela, incluez la valeur réelle telle qu'elle existait lorsque vous avez envoyé la commande en la saisissant vous-même avant d'envoyer le message de chat. Ces boutons fonctionneront dans tous les types de messages, messages généraux, chuchotements, gmdemandes, etc.

Notez que si vous utilisez /direct pour envoyer un message, nous ne ferons pas d'analyse Markdown, vous devez donc inclure vos propres balises <a> . Voici un exemple de cela :

<a href="!attackroll">Jet d'attaque</a>

Entrée de boutons API dans le chat

Vous pouvez également taper la syntaxe Markdown des boutons API dans le chat pour que d'autres les utilisent. Parce qu'ils seront interprétés par l'analyseur de chat, si vous souhaitez que les attributs, les requêtes et les lancers soient développés lorsque le bouton est cliqué, vous devez entrer certaines parties de la commande avec une syntaxe spéciale (Entités HTML) :

Caractère Remplacement
 % &#37 ;
) &#41;
 ? &#63;
@ &#64;
[ &#91; or &lbrack;
] &#93; or &rbrack;

This sample button uses some of them:

[Lancer le jet d'attaque](!attackroll &#64;{target|token_id} &#91;[1d6+&#63;{Bonus|0}]&#93;)

Vous pouvez réellement utiliser les boutons API pour appeler des macros ou des compétences.

Personnage Remplacement
<carriage return> &#13;

Pour ce faire, vous commencez simplement la partie commande avec le code spécial!&#13;puis ajoutez l'appel de macro avec#ou l'appel de compétence avec&#37;(%):

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

[Compétence](!&#13;&#37;{CharName|AbilityName})

Note: À ce moment, la réouverture d'une macro enregistrée sous l'onglet Collections de la barre latérale provoque la réversion des entités HTML qu'elle contient ; si la macro est ensuite enregistrée, ces réversions le sont également. Ce comportement n'est pas présent dans lesAbilities ou les boutons de commande de l'ability.

Pour les boutons de commande de l'Ability, si l'Ability qui crée le bouton et l'Ability à laquelle il fait référence sont tous les deux sur la même feuille, la syntaxe est très simple:

[Ability](~AbilityName)

Cet article vous a-t-il été utile ?
Utilisateurs qui ont trouvé cela utile : 14 sur 20