Types of Objects

There are several different types of objects that are used throughout the Roll20 API. Here's a quick listing of each, what it is, and what properties it contains (along with the default values). As a general rule of thumb, properties that begin with an underscore (_) are read-only and cannot be changed.

Path

{    
  _id: "-Abc123", //unique ID for this object. globally unique across all objects in this campaign    
  fill: "transparent", //fill color. "transparent" or a color HEX    
  stroke: "#000000", // stroke color    
  rotation: 0, //rotation (in degrees)    
  layer: "", //current layer, one of "gmlayer", "objects", "map", "walls" (dynamic lighting) -- Paths on the "walls" layer are automatically used to block light.    
  stroke_width: 5,    
  width: 0,    
  height: 0,    
  top: 0,    
  left: 0,    
  scaleX: 1,    
  scaleY: 1,    
  _type: "path", //can be used to identify the object as a Path. read-only.
  _pageid: "-Abc123" //The ID of the page this object is in
}

Text

{    
  _id: "-Abc123",    
  top: 0,    
  left: 0,    
  width: 0,    
  height: 0,    
  text: "",    
  font_size: 16, //for best results stick to the pre-sets in the text editing menu    
  rotation: 0,    
  color: "#000000",    
  font_family: "unset", //see values of select element in text editing menu    
  layer: "",    
  _type: "text", //identifies the object is text. read-only.
  _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_value: "", //Current value of Bar 1 (number OR text)    
  bar1_max: "", //Max value of Bar 1    
  _bar1_link: "", //Set to an ID if Bar 1 is linked to a Character Attrbute. read-only.    
  bar2_value: "",    
  bar2_max: "",    
  _bar2_link: "",    
  bar3_value: "",    
  bar3_max: "",    
  _bar3_link: "",    
  aura1_radius: "", //Radius (integer or float) of the aura. Set to empty string ("") for none.    
  aura1_color: "#FFFF99", //HEX color    
  aura1_square: false, //Is the aura square?    
  aura2_radius: "",    aura2_color: "#59E594",    
  aura2_square: false,    
  tint_color: "transparent", //HEX color or "transparent"    
  status_redmarker: false, //show the red marker on the token    
  status_bluemarker: false,    
  status_greenmarker: false,    
  status_brownmarker: false,    
  status_purplemarker: false,    
  status_dead: false,    
  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_name: false, // allow controlling players to edit the name. also show the name to controlling players even if showplayers_name is 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    
  _type: "graphic", //identifies the object as a graphic. read-only.    
  _subtype: "token", //"token" (tokens and maps) or "card"    
  _cardid: "", //set to a value if the graphic represents a card.
  _pageid: ""
}

NOTE: If a bar is linked to a Character Attribute (for example, the _bar1_link value is set), then modifying the bar1_value or bar1_max will not have any in-game effect. Instead you should modify the Attribute's current and max properties, which will update both the Attribute and the bars that are displayed for the token in-game.

Page (Read Only)

{    
  _id: "-Abc123",    
  name: "", //Page's title    
  showgrid: true, //are we showing the grid?    
  showdarkness: false, //Is the Fog of War active?    
  showlighting: false, //Is Dynamic Lighting active?    
  width: 25, //width in units    
  height: 25, //height in units    
  snapping_increment: 1.0, //the size of a grid space in units    
  grid_opacity: 0.50, //opacity of the grid    
  fog_opacity: 0.35, //opacity of the fog of war for the GM    
  background_color: "#ffffff", //background color (HEX)    
  gridcolor: "#C0C0C0", //grid color (HEX)    
  grid_type: "square", //eitehr "square", "hexv", or "hexh"    
  scale_number: 5, //1 unit = how much distance    
  scale_units: "ft", //scale is in these units    
  gridlabels: false, //show grid labels for hex grid    
  diagonaltype: "foure", //one of "foure", "pythagorean" (Euclidean), "threefive", or "manhattan"
}

Campaign

{    
  _type: "campaign",    
  _turnorder: "", // a JSON string   
  initiativepage: false, //ID of the page that is currently used for the tracker when turn window is open. Set to false and window will close.   
  playerpageid: false //ID of the page that the player bookmark is set to  
}

Player

{    
  _d20userid: "", //The site-wide unique ID of the user.
  _displayname: "", //Current display name     
  _online: false,    
  color: "#13B9F0",    
  _macrobar: "", //Comma-delimited string of the macros in the player's macro bar.   
  showmacrobar: false, //Show macro bar?   
  _id: "",    
  _type: "player"  
}

Macro

{    
  name: "",    
  action: "",    
  visibleto: "", //Comma-delimited list of additional players this macro is visible to.   
  _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: "",    
  _rollabletableid: "" //ID of the rollable table this item belongs to 
}

Character

{    
  name: "",    
  bio: "",    
  gmnotes: "",    
  archived: false,    
  _inplayerjournals: "",  //Comma-deliminted list of player IDs  
  _controlledby: "",  //Comma-delimited list of player IDs  
  _id: "",    
  _type: "character"
}

Attribute

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

Ability

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

Handout

{    
  name: "Mysterious Note",    
  notes: "",    
  _inplayerjournals: "",    
  archived: false,    
  _controlledby: "",    
  _type: "handout",    
  _id: "" 
}

Global Objects

There are several objects that are globally available anywhere in your script.

Campaign() (function)

A function which returns the Campaign object. Since there is only one campaign, this global always points to the only campaign in the game. Useful for doing things like checking to see if an object is on the active page using Campaign().playerpageid.

state

This is an object that is initialized as a blank object whenver your script is loaded. You can set whatever properties you want on this object, and they are available to all of your event callbacks, and persist between callbacks.

Note: Eventually this object will be persisted between play sessions, but right now it's not.

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

Finding/Filtering Objects

The API provides several helper functions which can be used to find objects.

findObjs(attrs)

Pass this function a list of attributes, and it will return all objects that match. Note that this operates on all objects of all types across all pages -- so you probably want to include at least a filter for _type and _pageid if you're working with tabletop objects.

var currentPageGraphics = findObjs({                              
  _pageid: Campaign().get("playerpageid"),                              
  _type: "graphic",                          
});
_.each(currentPageGraphics, function(obj) {    
  //Do something with obj, which is in the current page and is a graphic.
});

filterObjs(callback)

Will execute the provided callback funtion on each object, and if the callback returns true, the object will be included in the result array.

var results = filterObjs(function(obj) {    
  if(obj.get("left") < 200 && obj.get("top") < 200) return true;    
  else return false;
});
//Results is an array of all objects that are in the top-left corner of the tabletop.

getAllObjs()

Returns an array of all the objects in the Campaign (all types). Equivalent to calling filterObjs and just returning true for every object.