Character Vault
Any Concept / Any System
Your System Come To Life
Roll20 for Android
Streamlined for your Tablet
Roll20 for iPad
Streamlined for your Tablet

Personal tools


From Roll20 Wiki

Revision as of 19:17, 19 August 2013 by Brian (Talk | contribs)

Jump to: navigation, search

Roll20 API

Getting Started


Cookbook (Examples)

Community Scripts


Types of Objects




  stroke: "#000000", // stroke color    
  rotation: 0, //rotation (in degrees)    
  stroke_width: 5,    
  width: 0,    
  height: 0,    
  top: 0, // the center Y coordinate   
  left: 0, // the center X coordinate
  scaleX: 1,    
  scaleY: 1,    


  _id: "-Abc123",    
  top: 0,    
  left: 0,    
  width: 0,    
  height: 0,    
  text: "",    
  rotation: 0,    
  color: "#000000",    
  layer: "",    
  _pageid: "-Abc123"

Graphic (Token/Map/Card/Etc.)

  _id: "-Abc123",    
  left: 0,    
  top: 0,   
  width: 0,    
  height: 0,    
  rotation: 0.0,    
  layer: "",    
  isdrawing: false, //advanced -> is drawing?    
  flipv: false, //flip vertically    
  fliph: false, //flip horizontally    
  name: "", //Token Name    
  gmnotes: "", //GM Notes    
  bar1_max: "", //Max value of Bar 1    
  bar2_value: "",    
  bar2_max: "",    
  _bar2_link: "",    
  bar3_value: "",    
  bar3_max: "",    
  _bar3_link: "",
  aura1_color: "#FFFF99", //HEX color    
  aura1_square: false, //Is the aura square?    
  aura2_radius: "",    
  aura2_color: "#59E594",    
  aura2_square: false,    
  statusmarkers: "", //The statusmarkers on the token, see note below for more info
  showname: false, //show the nameplate    
  showplayers_name: false, //show the name to all players    
  showplayers_bar1: false,    
  showplayers_bar2: false,    
  showplayers_bar3: false,    
  showplayers_aura1: false,    
  showplayers_aura2: false,    
  playersedit_bar1: false,    
  playersedit_bar2: false,    
  playersedit_bar3: false,    
  playersedit_aura1: false,    
  playersedit_aura2: false,    
  light_radius: "", //dynamic lighting radius    
  light_dimradius: "", //dim radius    
  light_otherplayers: false, //show light to all players    
  _pageid: ""

Important Notes About Linked Characters + Tokens




Important Notes About Status Markers

As of August 6, 2013 the way that status markers on tokens are handled has changed. The "statusmarkers" property of the Graphic object is now a comma-delimited list of all status marker colors/icons that should be active on the token. The format is as follows:

//Comma-delimited (use join to create or split to turn into an array). If a status icon/color is followed by an "@" symbol, the number after "@" will be shown as the badge on the icon
statusmarkers = "red,blue,skull,dead,brown@2,green@6"

While you can access the statusmarkers property directly, to maintain backward-compatibility with existing scripts, and to provide an easy way to work with the status markers without needing to write code to handle splitting up and parsing the string yourself, we provide a set of "virtual" properties on the object that you can set/get to work with the status markers. Each status marker has a "status_<markername>" property. For example:

obj.get("status_red"); //Will return false if the marker is not active, true if it is, and a string (e.g. "2" or "5") if there is currently a badge set on the marker
obj.get('status_bluemarker'); //Is still supported for backwards compatability, and is equivalent to doing obj.get("status_blue");
obj.set("status_red", false); //would remove the marker
obj.set("status_skull", "2"); //would set a badge of "2" on the skull icon, and add it to the token if it's not already active.

Note that these virtual properties do not have events, so you must use change:graphic:statusmarkers to listen for changes to the status markers of a token, and for example change:graphic:status_red is NOT a valid event that will ever fire.

The full list of status markers that are available (in the same order they appear in the marker tray):

"red", "blue", "green", "brown", "purple", "pink", "yellow", "dead", "skull", "sleepy", "half-heart", "half-haze", "interdiction", "snail", "lightning-helix", "spanner", "chained-heart", "chemical-bolt", "death-zone", "drink-me", "edge-crack", "ninja-mask", "stopwatch", "fishing-net", "overdrive", "strong", "fist", "padlock", "three-leaves", "fluffy-wing", "pummeled", "tread", "arrowed", "aura", "back-pain", "black-flag", "bleeding-eye", "bolt-shield", "broken-heart", "cobweb", "broken-shield", "flying-flag", "radioactive", "trophy", "broken-skull", "frozen-orb", "rolling-bomb", "white-tower", "grab", "screaming", "grenade", "sentry-gun", "all-for-one", "angel-outfit", "archery-target"

Page (Read Only)

  _id: "-Abc123",    
  name: "", //Page's title    
  showgrid: true, //are we showing the grid?    
  showlighting: false, //Is Dynamic Lighting active?    
  width: 25, //width in units    
  height: 25, //height in units    
  grid_opacity: 0.50, //opacity of the grid    
  scale_number: 5, //1 unit = how much distance    
  gridlabels: false, //show grid labels for hex grid    


  _type: "campaign",    

Turn Order




To modify the turn order, edit the current turn order object and then use JSON.stringify() to change the attribute on the Campaign. Note that the ordering for the turn order in the list is the same as the order of the array, so for example push() adds an item onto the end of the list, unshift() adds to the beginning, etc.

var turnorder;

    id: "-1",
    pr: "15",
    custom: "Turn Counter"


  _displayname: "", //Current display name     
  _online: false,    
  color: "#13B9F0",    
  showmacrobar: false, //Show macro bar?   
  _id: "",    
  _type: "player"  


  name: "",    
  action: "",    
  _id: "",    
  _type: "macro",    
  _playerid: "" //Player this macro belongs to 

Rollable Table

  name: "new-table",    
  showplayers: true,    
  _type: "rollabletable",    
  _id: ""  

Table Item

  name: "",    
  weight: 1,    
  _type: "tableitem",    
  _id: "",    


  name: "",    
  bio: "",    
  gmnotes: "",    
  archived: false,    
  _id: "",    
  _type: "character"


  name: "Untitled",    
  current: "",    
  max: "",    
  _id: "",    
  _type: "attribute",    
  _characterid: ""  


  name: "Untitled_Ability",    
  description: "",    
  action: "",    
  _id: "",    
  _characterid: "",    
  _type: "ability"  


  name: "Mysterious Note",    
  notes: "",    
  archived: false,    
  _type: "handout",    
  _id: "" 

Creating Objects

createObj(type, attributes)



on("add:character", function(obj) {
    createObj("attribute", {
        name: "Strength",
        current: 0,
        max: 30,

Global Objects


Campaign() (function)





state.numTimesTokensMoved = 0;
on("change:graphic", function(obj) {    
  state.numTimesTokensMoved = state.numTimesTokensMoved + 1;

Finding/Filtering Objects


getObj(type, id)


on("change:graphic:represents", function(obj) {



var currentPageGraphics = findObjs({                              
  _type: "graphic",                          
_.each(currentPageGraphics, function(obj) {    



var targetTokens = findObjs({
    name: "target"
}, {caseInsensitive: true});



var results = filterObjs(function(obj) {    
  else return false;

