Revision as of 13:15, 23 April 2013

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
}

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",
  "rolls": [
    {
      "type":"G",
      "rolls": [
        [
          {
            "type":"R",
            "dice":2,
            "sides":6,
            "mods":{},
            "results": [
             {
               "v":1
             },
             {
               "v":5
             }
            ]
          }
        ]
      ],
      "mods":{},
      "resultType":"sum",
      "results": [
        {
          "v":6
        }
      ]
    },
    {
      "type":"M",
      "expr":"+5+"
    },
    {
      "type":"R",
      "dice":1,
      "table":"weather",
      "mods":{},
      "sides":2,
      "results": [
        {
          "v":0,
          "tableidx":1,
          "tableItem": {
            "name":"rainy",
            "avatar":"",
            "weight":1,
            "id":"-IpzPx2j_9piP09ceyOv"
          }
        }
      ]
    },
    {
      "type":"C",
      "text":" Attack!"
    }
  ],
  "resultType":"sum",
  "total":11
}

Example:

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.