Roll20 Wiki

Roll20 Mod
Use Mods

Mod Development

Reference

Cookbook

Chat Events

chat:message

Triggered whenever a new chat message is received. Note that if the message is of type "rollresult", you will need to call JSON.parse() on the content of the message to get an object which contains information on the roll results. If the message is of type "api", then it hasn't been shown to anyone, and the player who sent the chat message is probably expecting an API script to do something as a result of the message.

Callback parameter:

{    
  who: "Riley D.", //The person who sent the message. Can be any string.
  type: "general", //One of "general", "rollresult", "emote", "whisper", "desc", "api"
  content: "The chat message", //The chat message, if it's a rollresult this will be a JSON string of data about the roll
  target: "-Abc123", //For whispers, the target of the whisper
  origroll: "/roll 2d6" //For rollresults, this is the original formula as it was entered, without any processing done.
}

Note: You probably don't need all of this information. In most cases you'll only be interested in the overall result of the roll (see the bottom of the first example). However all of it is provided if you want to really dig deeper into the results of a roll.

Roll Result Structure Example 1

After you call JSON.parse on the content property of a "rollresult" message, you'll get an object with the following format (this is the result from the command /roll {2d6}+5}1t[weather] Attack!)

{
  "type":"V", //"V" = "Validated Roll" (this will always be "V" right now)
  "rolls": [
    {
      "type":"G", //"G" indicates a grouped roll. A group is like a series of "sub-rolls" within a roll.
      "rolls": [
        [
          {
            "type":"R", //"R" = "Roll"
            "dice":2, // Number of dice rolled (2dX means 2 dice)
            "sides":6, //Number of sides for the dice (Xd6 means 6 sides)
            "mods":{},
            "results": [ //An array of the results of each roll.
             {
               "v":1 // We rolled a 1 for our first 2d6
             },
             {
               "v":5 //We rolled a 5 for our second 2d6
             }
            ]
          }
        ]
      ],
      "mods":{},
      "resultType":"sum", //The result is a sum (as opposed to a success check)
      "results": [
        {
          "v":6 // In this case, the overall result (total) of the group.
        }
      ]
    },
    {
      "type":"M", //"M" = Math Expression
      "expr":"+5+"
    },
    {
      "type":"R", //"R" = Roll
      "dice":1,
      "table":"weather", //The table property is set to the name of the table used if this roll was made against a table
      "mods":{},
      "sides":2, //You can probably just ignore this for table rolls.
      "results": [
        {
          "v":0, //The "value" of the table item rolled. For text tables this is always 0.
          "tableidx":1, //The index of the item in the table that was rolled.
          "tableItem": { //A copy of the table item object as it existed when the table was rolled.
            "name":"rainy", 
            "avatar":"", //This will be a URL to an image if the rollable table uses image icons
            "weight":1,
            "id":"-IpzPx2j_9piP09ceyOv"
          }
        }
      ]
    },
    {
      "type":"C", // "C" = Comment
      "text":" Attack!"
    }
  ],
  "resultType":"sum", //The overall result type of the entire roll
  "total":11 // The overall total of the entire roll (including all sub-groups)
}

Roll Result Structure Example 2

An annotated structure for the result of /roll {1d6!!>5}>6 (showing exploding modifications and target successes):

{
  "type":"V",
  "rolls": [
    {
      "type":"G",
      "rolls": [
        [
          {
            "type":"R",
            "dice":1,
            "sides":6,
            "mods": { //Modifications to the roll
              "compounding": { //"compounding" = "Compounding exploding (!!)"
                "comp":">=", //Comparison type
                "point":5 //Comparison point
              }
            },
            "results": [
              {
                "v":13 //Overall dice result. Note that since this is compounding exploding there is only one dice result.
              }
            ]
          }
        ]
      ],
      "mods": {
        "success": {
          "comp":">=",
          "point":6
        }
      },
      "resultType":"sum",
      "results": [
        {
          "v":13
        }
      ]
    }
  ],
  "resultType":"success", // In this case, the result is a count of successes
  "total":1 //Total number of successes
}

Chat Event Example (Implementing Custom Roll Type)

on("chat:message", function(msg) {
  //This allows players to enter !sr <number> to roll a number of d6 dice with a target of 4.
  if(msg.type == "api" && msg.content.indexOf("!sr ") !== -1) {
    var numdice = msg.content.replace("!sr ", "");
    sendChat(msg.who, "/roll " + numdice + "d6>4");
  }
});

Chat Functions

sendChat(speakingAs, input)

You can use this function to send a chat message.

speakingAs should 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. If you do this it will automatically use the avatar and name of the player.
A character's ID, formatted as "character|-Abc123". If you do this it will automatically use the avatar and name of the Character.

input should be any valid expression just like the ones used in the Roll20 App. You enter text to send a basic message, or use slash-commands such as "/roll", "/em", "/w", etc. In addition:

You can use Character Attributes with the format @{CharacterName|AttributeName}.
You can use Character Abilities with the format: %{CharacterName|AbilityName}.
You cannot use macros.

Roll20 Wiki

Navigation

Personal tools

Toolbox

Mod:Chat

From Roll20 Wiki

Chat Events

Chat Functions