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

Personal tools

Difference between revisions of "Mod:Objects"

From Roll20 Wiki

Jump to: navigation, search
(categorized)
(updated object descriptions, added some undocumented properties.)
Line 1: Line 1:
 
{{apibox}}
 
{{apibox}}
  
==Types of Objects==
+
== 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. You must access properties on objects using <code>obj.get("property")</code> and set new values using <code>obj.set("property", newvalue)</code> or <code>obj.set({property: newvalue, property2: newvalue2})</code>.
 
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. You must access properties on objects using <code>obj.get("property")</code> and set new values using <code>obj.set("property", newvalue)</code> or <code>obj.set({property: newvalue, property2: newvalue2})</code>.
Line 7: Line 7:
 
'''Note:''' The <code>id</code> property of an object is a globally-unique ID: no two objects should have the same one, even across different types of objects. In addition, since an object's id is frequently-accessed and never changes, there is a shortcut available where you can access it by using <code>obj.id</code> instead of <code>obj.get("_id")</code> if you wish (either will work).
 
'''Note:''' The <code>id</code> property of an object is a globally-unique ID: no two objects should have the same one, even across different types of objects. In addition, since an object's id is frequently-accessed and never changes, there is a shortcut available where you can access it by using <code>obj.id</code> instead of <code>obj.get("_id")</code> if you wish (either will work).
  
===Path===
+
=== Path ===
<pre data-language="javascript">
+
{   
+
  _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, // the center Y coordinate 
+
  left: 0, // the center X coordinate
+
  scaleX: 1,   
+
  scaleY: 1,   
+
  controlledby: "", //Comma-delimited list of player IDs who can control (including delete) this path. Automatically includes the player who created the path if it was created by a player.
+
  _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
+
}
+
</pre>
+
  
===Text===
+
{| class="wikitable"
 +
|-
 +
! Property
 +
! Default Value
 +
! Notes
 +
|-
 +
| _id
 +
|
 +
| A unique ID for this object. Globally unique across all objects in this campaign. Read-only.
 +
|-
 +
| _type
 +
| "path"
 +
| Can be used to identify the object type or search for the object. Read-only.
 +
|-
 +
| _pageid
 +
|
 +
| ID of the page the object is in. Read-only.
 +
|-
 +
| _path
 +
|
 +
| An array describing the lines in the path. Read-only.
 +
|-
 +
| fill
 +
| "transparent"
 +
| Fill color. Use the string "transparent" of a hex color as a string, for example "#000000"
 +
|-
 +
| stroke
 +
| "#000000"
 +
| Stroke (border) color.
 +
|-
 +
| rotation
 +
| 0
 +
| Rotation (in degrees).
 +
|-
 +
| layer
 +
| ""
 +
| Current layer, one of "gmlayer", "objects", "map", or "walls". The walls layer is used for dynamic lighting, and paths on the walls layer will block light.
 +
|-
 +
| stroke_width
 +
| 5
 +
|
 +
|-
 +
| width
 +
| 0
 +
|
 +
|-
 +
| height
 +
| 0
 +
|
 +
|-
 +
| top
 +
| 0
 +
| Y-coordinate for the center of the path
 +
|-
 +
| left
 +
| 0
 +
| X-coordinate for the center of the path
 +
|-
 +
| scaleX
 +
| 1
 +
|
 +
|-
 +
| scaleY
 +
| 1
 +
|
 +
|-
 +
| controlledby
 +
| ""
 +
| Comma-delimited list of player IDs who can control the path. Controlling players may delete the path. If the path was created by a player, that player is automatically included in the list.
 +
|}
  
<pre data-language="javascript">
+
=== 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: "",   
+
  controlledby: "", //Comma-delimited list of Player IDs who can control (including delete) this text object. Automatically set to the player who created it if created by a player.
+
  _type: "text", //identifies the object is text. read-only.
+
  _pageid: "-Abc123"
+
}
+
</pre>
+
  
===Graphic (Token/Map/Card/Etc.)===
+
{| class="wikitable"
<pre data-language="javascript">
+
|-
{   
+
! Property
  _id: "-Abc123",   
+
! Default Value
  left: 0,   
+
! Notes
  top: 0
+
|-
  width: 0,   
+
| _id
  height: 0,   
+
|
  rotation: 0.0,   
+
| A unique ID for this object. Globally unique across all objects in this campaign. Read-only.
  layer: "",   
+
|-
  isdrawing: false, //advanced -> is drawing?   
+
| _type
  flipv: false, //flip vertically  
+
| "text"
  fliph: false, //flip horizontally  
+
| Can be used to identify the object type or search for the object. Read-only.
  name: "", //Token Name   
+
|-
  gmnotes: "", //GM Notes  
+
| _pageid
  controlledby: "", //Comma-delimited list of Player IDs who can control (select and move) this graphic. The GM can always control all graphics.
+
|
  bar1_value: "", //Current value of Bar 1 (number OR text)   
+
| ID of the page the object is in. Read-only.
  bar1_max: "", //Max value of Bar 1  
+
|-
  _bar1_link: "", //Set to an ID if Bar 1 is linked to a Character Attrbute. read-only.   
+
| top
  bar2_value: "",   
+
| 0
  bar2_max: "",   
+
|
  _bar2_link: "",   
+
|-
  bar3_value: "",   
+
| left
  bar3_max: "",   
+
| 0
  _bar3_link: "",
+
|
  _represents: "", // The ID of a Character that this token represents   
+
|-
  aura1_radius: "", //Radius (integer or float) of the aura. Set to empty string ("") for none.   
+
| width
  aura1_color: "#FFFF99", //HEX color   
+
| 0
  aura1_square: false, //Is the aura square?   
+
|
  aura2_radius: "",   
+
|-
  aura2_color: "#59E594",   
+
| height
  aura2_square: false,   
+
| 0
  tint_color: "transparent", //HEX color or "transparent"  
+
|
  statusmarkers: "", //The statusmarkers on the token, see note below for more info
+
|-
  showname: false, //show the nameplate  
+
| text
  showplayers_name: false, //show the name to all players  
+
| ""
  showplayers_bar1: false,   
+
|
  showplayers_bar2: false,   
+
|-
  showplayers_bar3: false,   
+
| font_size
  showplayers_aura1: false,   
+
| 16
  showplayers_aura2: false,   
+
| For best results, stick to the preset sizes in the editing menu: 8, 10, 12, 14, 16, 18, 20, 22, 26, 32, 40, 56, 72, 100, 200, 300.
  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,  
+
| rotation
  playersedit_bar2: false,   
+
| 0
  playersedit_bar3: false,   
+
|
  playersedit_aura1: false,  
+
|-
  playersedit_aura2: false,   
+
| color
  light_radius: "", //dynamic lighting radius  
+
| "rgb(0, 0, 0)"
  light_dimradius: "", //dim radius  
+
|
  light_otherplayers: false, //show light to all players   
+
|-
  _type: "graphic", //identifies the object as a graphic. read-only.   
+
| font_family
  _subtype: "token", //"token" (tokens and maps) or "card"   
+
| "unset"
  _cardid: "", //set to a value if the graphic represents a card.
+
| See values in text editing menu.
  _pageid: ""
+
|-
}
+
| layer
</pre>
+
| ""
 +
|
 +
|-
 +
| controlledby
 +
| ""
 +
| Comma-delimited list of player IDs who can control the text. Controlling players may delete the text. If the text was created by a player, that player is automatically included in the list.
 +
|}
 +
 
 +
=== Graphic (Token/Map/Card/Etc.) ===
 +
 
 +
{| class="wikitable"
 +
! Property
 +
! Default Value
 +
! Notes
 +
|-
 +
| _id
 +
|
 +
| A unique ID for this object. Globally unique across all objects in this campaign. Read-only.
 +
|-
 +
| _type
 +
| "graphic"
 +
| Can be used to identify the object type or search for the object. Read-only.
 +
|-
 +
| _subtype
 +
| "token"
 +
| May be "token" (for tokens and maps) or "card" (for cards). Read-only.
 +
|-
 +
| _cardid
 +
|
 +
| Set to an ID if the graphic is a card. Read-only.
 +
|-
 +
| _pageid
 +
|
 +
| ID of the page the object is in. Read-only.
 +
|-
 +
| _bar1_link
 +
|
 +
| Set to an ID if Bar 1 is linked to a character. Read-only.
 +
|-
 +
| _bar2_link
 +
|
 +
|
 +
|-
 +
| _bar3_link
 +
|
 +
|
 +
|-
 +
| _represents
 +
|
 +
| ID of the character this token represents. Read-only.
 +
|-
 +
| left
 +
| 0
 +
|
 +
|-
 +
| top
 +
| 0
 +
|
 +
|-
 +
| width
 +
| 0
 +
|
 +
|-
 +
| height
 +
| 0
 +
|
 +
|-
 +
| rotation
 +
| 0
 +
|
 +
|-
 +
| layer
 +
| ""
 +
|
 +
|-
 +
| isdrawing
 +
| false
 +
| This property is changed from the Advanced context menu.
 +
|-
 +
| flipv
 +
| false
 +
| Flip vertically.
 +
|-
 +
| fliph
 +
| false
 +
| Flip horizontally.
 +
|-
 +
| name
 +
| ""
 +
| The token's name.
 +
|-
 +
| gmnotes
 +
| ""
 +
| Notes on the token only visible to the GM.
 +
|-
 +
| controlledby
 +
| ""
 +
| Comma-delimited list of player IDs who can control the text. Controlling players may delete the text. If the text was created by a player, that player is automatically included in the list.
 +
|-
 +
| bar1_value
 +
| ""
 +
| Current value of Bar 1. This may be a number or text.
 +
|-
 +
| bar2_value
 +
| ""
 +
|
 +
|-
 +
| bar3_value
 +
| ""
 +
|
 +
|-
 +
| bar1_max
 +
| ""
 +
| Maximum value of Bar 1. If _value and _max are both set, a bar may be displayed above the token showing the percentage of Bar 1.
 +
|-
 +
| bar2_max
 +
| ""
 +
|
 +
|-
 +
| bar3_max
 +
| ""
 +
|
 +
|-
 +
| aura1_radius
 +
| ""
 +
| Radius of the aura, using the units set in the page's settings. May be an integer or a float. Set to the empty string to clear the aura.
 +
|-
 +
| aura2_radius
 +
| ""
 +
|
 +
|-
 +
| aura1_color
 +
| "#FFFF99"
 +
| A hexadecimal color or the aura.
 +
|-
 +
| aura2_color
 +
| "#59E594"
 +
|
 +
|-
 +
| aura1_square
 +
| false
 +
| Is the aura a circle or a square?
 +
|-
 +
| aura2_square
 +
| false
 +
|
 +
|-
 +
| tint_color
 +
| "transparent"
 +
| Hexadecimal color, or "transparent". Will tint the color of the graphic.
 +
|-
 +
| statusmarkers
 +
| ""
 +
| A comma-delimited list of currently active statusmarkers. See the notes below for more information.
 +
|-
 +
| showname
 +
| false
 +
| Whether the token's nameplate is shown.
 +
|-
 +
| showplayers_name
 +
| false
 +
| Show the nameplate to all players.
 +
|-
 +
| showplayers_bar1
 +
| false
 +
| Show Bar 1 to all players.
 +
|-
 +
| showplayers_bar2
 +
| false
 +
|
 +
|-
 +
| showplayers_bar3
 +
| false
 +
|
 +
|-
 +
| showplayers_aura1
 +
| false
 +
| Show Aura 1 to all players.
 +
|-
 +
| showplayers_aura2
 +
| false
 +
|
 +
|-
 +
| playersedit_name
 +
| false
 +
| Allow controlling players to edit the token's name. Also shows the nameplate to controlling players, even if showplayers_name is false.
 +
|-
 +
| playersedit_bar1
 +
| false
 +
| Allow controlling players to edit the token's Bar 1. Also shows Bar 1 to controlling players, even if showplayers_bar1 is false.
 +
|-
 +
| playersedit_bar2
 +
| false
 +
|
 +
|-
 +
| playersedit_bar3
 +
| false
 +
|
 +
|-
 +
| playersedit_aura1
 +
| false
 +
| Allow controlling players to edit the token's Aura 1. Also shows Aura 1 to controlling players, even if showplayers_aura1 is false.
 +
|-
 +
| playersedit_aura2
 +
| false
 +
|
 +
|-
 +
| light_radius
 +
| ""
 +
| Dynamic lighting radius.
 +
|-
 +
| light_dimradius
 +
| ""
 +
| Start of dim light radius. If light_dimradius is the empty string, the token will emit bright light out to the light_radius distance. If light_dimradius has a value, the token will emit bright light out to the light_dimradius value, and dim light from there to the light_radius value.
 +
|-
 +
| light_otherplayers
 +
| false
 +
| Show the token's light to all players.
 +
|}
  
 
'''Important Notes About Linked Characters + Tokens'''
 
'''Important Notes About Linked Characters + Tokens'''
Line 138: Line 389:
 
<code>"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"</code>
 
<code>"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"</code>
  
===Page (Read Only)===
+
=== Page ===
<pre data-language="javascript">
+
{   
+
  _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"
+
}
+
</pre>
+
  
===Campaign===
+
{| class="wikitable"
<pre data-language="javascript">
+
|-
{   
+
! Property
  _type: "campaign",  
+
! Default Value
  turnorder: "", // a JSON string, see below for more details 
+
! Notes
  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
+
| _id
}
+
|
</pre>
+
| A unique ID for this object. Globally unique across all objects in this campaign. Read-only.
 +
|-
 +
| _type
 +
| "page"
 +
| Can be used to identify the object type or search for the object. Read-only.
 +
|-
 +
| _zorder
 +
| ""
 +
| Comma-delimited list of IDs specifying the ordering of objects on the page. <code>toFront</code> and <code>toBack</code> (and their associated context menu items) can re-order this list. Read-only.
 +
|-
 +
| name
 +
| ""
 +
| Page's title.
 +
|-
 +
| showgrid
 +
| true
 +
| Show the grid on the map.
 +
|-
 +
| showdarkness
 +
| false
 +
| Show fog of war on the map.
 +
|-
 +
| showlighting
 +
| false
 +
| Use dynamic lighting.
 +
|-
 +
| width
 +
| 25
 +
| Width in units.
 +
|-
 +
| height
 +
| 25
 +
| Height in units.
 +
|-
 +
| snapping_increment
 +
| 1
 +
| Size of a grid space in units.
 +
|-
 +
| grid_opacity
 +
| 0.5
 +
| Opacity of the grid lines.
 +
|-
 +
| fog_opacity
 +
| 0.35
 +
| Opacity of the fog of war for the GM.
 +
|-
 +
| background_color
 +
| "#FFFFFF"
 +
| Hexadecimal color of the map background.
 +
|-
 +
| gridcolor
 +
| "#C0C0C0"
 +
| Hexadecimal color of the grid lines.
 +
|-
 +
| grid_type
 +
| "square"
 +
| One of "square", "hexv", or "hexh".
 +
|-
 +
| scale_number
 +
| 5
 +
| The distance of one unit.
 +
|-
 +
| scale_units
 +
| "ft"
 +
| The type of units to use for the scale.
 +
|-
 +
| gridlabels
 +
| false
 +
| Show grid labels for hexagonal grid.
 +
|-
 +
| diagonaltype
 +
| "foure"
 +
| One of "foure", "pythagorean" (Euclidean), "threefive", or "manhattan".
 +
|-
 +
| archived
 +
| false
 +
| whether the page has been put into archive storage.
 +
|}
 +
 
 +
=== Campaign ===
 +
 
 +
{| class="wikitable"
 +
|-
 +
! Property
 +
! Default Value
 +
! Notes
 +
|-
 +
| _id
 +
| "root"
 +
| A unique ID for this object. Globally unique across all objects in this campaign. Read-only.
 +
|-
 +
| _type
 +
| "campaign"
 +
| Can be used to identify the object type or search for the object &mdash; however, note that there is only one Campaign object, and it can be accessed via <code>Campaign()</code>. Read-only.
 +
|-
 +
| turnorder
 +
| ""
 +
| A JSON string of the turn order. See below.
 +
|-
 +
| initiativepage
 +
| false
 +
| ID of the page used for the tracker when the turn order window is open. When set to <code>false</code>, the turn order window closes.
 +
|-
 +
| playerpageid
 +
| false
 +
| ID of the page the player bookmark is set to.
 +
|}
  
 
'''Turn Order'''
 
'''Turn Order'''
Line 208: Line 544:
 
</pre>
 
</pre>
  
===Player===
+
=== Player ===
<pre data-language="javascript">
+
{   
+
  _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" 
+
}
+
</pre>
+
  
 +
{| class="wikitable"
 +
|-
 +
! Property
 +
! Default Value
 +
! Notes
 +
|-
 +
| _id
 +
|
 +
| A unique ID for this object. Globally unique across all objects in this campaign. Read-only.
 +
|-
 +
| _type
 +
| "player"
 +
| Can be used to identify the object type or search for the object. Read-only.
 +
|-
 +
| _d20userid
 +
|
 +
| User ID &mdash; site-wide. For example, the player's user page on the wiki is /User:''ID'', where ID is the same value stored in _d20userid. Read-only.
 +
|-
 +
| _displayname
 +
| ""
 +
| The player's current display name. May be changed from the user's settings page. Read-only.
 +
|-
 +
| _online
 +
| false
 +
| Read-only.
 +
|-
 +
| _macrobar
 +
| ""
 +
| Comma-delimited string of the macros in the player's macro bar. Read-only.
 +
|-
 +
| speakingas
 +
| ""
 +
| The player or character ID of who the player has selected from the "As" dropdown. When set to the empty string, the player is speaking as him- or herself. When set to a character, the value is "character|''ID''", where ID is the character's ID. When the GM is speaking as another player, the value is "player|''ID''", where ID is the player's ID.
 +
|-
 +
| color
 +
| "#13B9F0"
 +
| The color of the square by the player's name, as well as the color of their measurements on the map, their ping circles, etc.
 +
|-
 +
| showmacrobar
 +
| false
 +
| Whether the player's macro bar is showing.
 +
|}
  
===Macro===
+
=== Macro ===
<pre data-language="javascript">
+
{   
+
  name: "",   
+
  action: "",   
+
  visibleto: "", //Comma-delimited list of additional Player IDs this macro is visible to. 
+
  _id: "",   
+
  _type: "macro",   
+
  _playerid: "" //Player this macro belongs to
+
}
+
</pre> 
+
  
 +
{| class="wikitable"
 +
|-
 +
! Property
 +
! Default Value
 +
! Notes
 +
|-
 +
| _id
 +
|
 +
| A unique ID for this object. Globally unique across all objects in this campaign. Read-only.
 +
|-
 +
| _type
 +
| "macro"
 +
| Can be used to identify the object type or search for the object. Read-only.
 +
|-
 +
| _playerid
 +
|
 +
| The ID of the player that created this macro. Read-only.
 +
|-
 +
| name
 +
| ""
 +
| The macro's name.
 +
|-
 +
| action
 +
| ""
 +
| The text of the macro.
 +
|-
 +
| visibleto
 +
| ""
 +
| Comma-delimited list of player IDs who may view the macro in addition to the player that created it.
 +
|}
  
===Rollable Table===
+
=== Rollable Table ===
<pre data-language="javascript">
+
{   
+
  name: "new-table",   
+
  showplayers: true,   
+
  _type: "rollabletable",   
+
  _id: "" 
+
}
+
</pre>
+
  
 +
{| class="wikitable"
 +
|-
 +
! Property
 +
! Default Value
 +
! Notes
 +
|-
 +
| _id
 +
|
 +
| A unique ID for this object. Globally unique across all objects in this campaign. Read-only.
 +
|-
 +
| _type
 +
| "rollabletable"
 +
| Can be used to identify the object type or search for the object. Read-only.
 +
|-
 +
| name
 +
| "new-table"
 +
|
 +
|-
 +
| showplayers
 +
| true
 +
|
 +
|}
  
===Table Item===
+
=== Table Item ===
<pre data-language="javascript">
+
{   
+
  name: "",   
+
  weight: 1,   
+
  _type: "tableitem",   
+
  _id: "",   
+
  _rollabletableid: "" //ID of the rollable table this item belongs to
+
}
+
</pre>
+
  
 +
{| class="wikitable"
 +
|-
 +
! Property
 +
! Default Value
 +
! Notes
 +
|-
 +
| _id
 +
|
 +
| A unique ID for this object. Globally unique across all objects in this campaign. Read-only.
 +
|-
 +
| _type
 +
| "tableitem"
 +
| Can be used to identify the object type or search for the object. Read-only.
 +
|-
 +
| _rollabletableid
 +
| ""
 +
| ID of the table this item belongs to. Read-only.
 +
|-
 +
| _avatar
 +
| ""
 +
| URL to an image used for the table item. Read-only.
 +
|-
 +
| name
 +
| ""
 +
|
 +
|-
 +
| weight
 +
| 1
 +
| Weight of the table item compared to the other items in the same table. Simply put, an item with weight 3 is three times more likely to be selected when rolling on the table than an item with weight 1.
 +
|}
  
===Character===
+
=== Character ===
<pre data-language="javascript">
+
{   
+
  name: "",   
+
  bio: "",   
+
  gmnotes: "",   
+
  archived: false,   
+
  inplayerjournals: "",  //Comma-deliminted list of player IDs  who can view this Character in the Journal listing. The GM can always view all Characters.
+
  controlledby: "",  //Comma-delimited list of player IDs 
+
  _id: "",   
+
  _type: "character"
+
}
+
</pre> 
+
  
 +
{| class="wikitable"
 +
|-
 +
! Property
 +
! Default Value
 +
! Notes
 +
|-
 +
| _id
 +
|
 +
| A unique ID for this object. Globally unique across all objects in this campaign. Read-only.
 +
|-
 +
| _type
 +
| "character"
 +
| Can be used to identify the object type or search for the object. Read-only.
 +
|-
 +
| _avatar
 +
| ""
 +
| URL to an image used for the character. Read-only.
 +
|-
 +
| name
 +
| ""
 +
|
 +
|-
 +
| bio
 +
| ""
 +
| The character's biography.
 +
|-
 +
| gmnotes
 +
| ""
 +
| Notes on the character only viewable by the GM.
 +
|-
 +
| archived
 +
| false
 +
|
 +
|-
 +
| inplayerjournals
 +
| ""
 +
| Comma-delimited list of player ID who can view this character. Use "all" to give all players the ability to view.
 +
|-
 +
| controlledby
 +
| ""
 +
| Comma-delimited list of player IDs who can control and edit this character. Use "all" to give all players the ability to edit.
 +
|}
  
===Attribute===
+
=== Attribute ===
<pre data-language="javascript">
+
{   
+
  name: "Untitled",   
+
  current: "",   
+
  max: "",   
+
  _id: "",   
+
  _type: "attribute",   
+
  _characterid: "" 
+
}
+
</pre> 
+
  
 +
{| class="wikitable"
 +
|-
 +
! Property
 +
! Default Value
 +
! Notes
 +
|-
 +
| _id
 +
|
 +
| A unique ID for this object. Globally unique across all objects in this campaign. Read-only.
 +
|-
 +
| _type
 +
| "attribute"
 +
| Can be used to identify the object type or search for the object. Read-only.
 +
|-
 +
| _characterid
 +
| ""
 +
| ID of the character this attribute belongs to. Read-only.
 +
|-
 +
| name
 +
| "Untitled"
 +
|
 +
|-
 +
| current
 +
| ""
 +
| The current value of the attribute can be accessed in chat and macros with the syntax <code>@{Character Name|Attribute Name}</code> or in abilities with the syntax <code>@{Attribute Name}</code>.
 +
|-
 +
| max
 +
| ""
 +
|
 +
|}
  
===Ability===
+
=== Ability ===
<pre data-language="javascript">
+
{   
+
  name: "Untitled_Ability",   
+
  description: "",   
+
  action: "",   
+
  _id: "",   
+
  _characterid: "",   
+
  _type: "ability" 
+
}
+
</pre>
+
  
 +
{| class="wikitable"
 +
|-
 +
! Property
 +
! Default Value
 +
! Notes
 +
|-
 +
| _id
 +
|
 +
| A unique ID for this object. Globally unique across all objects in this campaign. Read-only.
 +
|-
 +
| _type
 +
| "ability"
 +
| Can be used to identify the object type or search for the object. Read-only.
 +
|-
 +
| _characterid
 +
| ""
 +
| The character this ability belongs to.
 +
|-
 +
| name
 +
| "Untitled_Ability"
 +
|
 +
|-
 +
| description
 +
| ""
 +
| The description does not appear in the character sheet interface.
 +
|-
 +
| action
 +
| ""
 +
| The text of the ability.
 +
|}
  
===Handout===
+
=== Handout ===
<pre data-language="javascript">
+
 
{   
+
{| class="wikitable"
  name: "Mysterious Note",   
+
|-
  notes: "",   
+
! Property
  inplayerjournals: "", //Comma-delimited list of Player IDs who can see this Handout in their journal. The GM can always see the Handout.  
+
! Default Value
  archived: false,   
+
! Notes
  controlledby: "", //Comma-delimited list of Player IDs who can control (and edit) this Handout.  
+
|-
  _type: "handout",   
+
| _id
  _id: ""
+
|
}
+
| A unique ID for this object. Globally unique across all objects in this campaign. Read-only.
</pre>
+
|-
 +
| _type
 +
| "handout"
 +
| Can be used to identify the object type or search for the object. Read-only.
 +
|-
 +
 
 +
| _avatar
 +
| ""
 +
| URL to an image used for the handout. Read-only.
 +
|-
 +
| name
 +
| "Mysterious Note"
 +
|
 +
|-
 +
| notes
 +
| ""
 +
| Contains the text in the handout.
 +
|-
 +
| inplayerjournals
 +
| ""
 +
| Comma-delimited list of player ID who can see this handout. Use "all" to display to all players.
 +
|-
 +
| archived
 +
| false
 +
|
 +
|-
 +
| controlledby
 +
| ""
 +
| Comma-delimited list of player IDs who can control and edit this handout.
 +
|}
  
==Creating Objects==
+
== Creating Objects ==
  
 
{{mbox | text= Note: Currently only '''characters, handouts, attributes, and abilities''' can be created. Other objects will be supported soon.}}
 
{{mbox | text= Note: Currently only '''characters, handouts, attributes, and abilities''' can be created. Other objects will be supported soon.}}
Line 337: Line 857:
 
</pre>
 
</pre>
  
==Global Objects==
+
== Global Objects ==
 
There are several objects that are globally available anywhere in your script.
 
There are several objects that are globally available anywhere in your script.
  
Line 357: Line 877:
 
</pre>
 
</pre>
  
==Finding/Filtering Objects==
+
== Finding/Filtering Objects ==
  
 
The API provides several helper functions which can be used to find objects.
 
The API provides several helper functions which can be used to find objects.

Revision as of 05:20, 28 August 2013


Contents

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. You must access properties on objects using obj.get("property") and set new values using obj.set("property", newvalue) or obj.set({property: newvalue, property2: newvalue2}).

Note: The id property of an object is a globally-unique ID: no two objects should have the same one, even across different types of objects. In addition, since an object's id is frequently-accessed and never changes, there is a shortcut available where you can access it by using obj.id instead of obj.get("_id") if you wish (either will work).

Path

Property Default Value Notes
_id A unique ID for this object. Globally unique across all objects in this campaign. Read-only.
_type "path" Can be used to identify the object type or search for the object. Read-only.
_pageid ID of the page the object is in. Read-only.
_path An array describing the lines in the path. Read-only.
fill "transparent" Fill color. Use the string "transparent" of a hex color as a string, for example "#000000"
stroke "#000000" Stroke (border) color.
rotation 0 Rotation (in degrees).
layer "" Current layer, one of "gmlayer", "objects", "map", or "walls". The walls layer is used for dynamic lighting, and paths on the walls layer will block light.
stroke_width 5
width 0
height 0
top 0 Y-coordinate for the center of the path
left 0 X-coordinate for the center of the path
scaleX 1
scaleY 1
controlledby "" Comma-delimited list of player IDs who can control the path. Controlling players may delete the path. If the path was created by a player, that player is automatically included in the list.

Text

Property Default Value Notes
_id A unique ID for this object. Globally unique across all objects in this campaign. Read-only.
_type "text" Can be used to identify the object type or search for the object. Read-only.
_pageid ID of the page the object is in. Read-only.
top 0
left 0
width 0
height 0
text ""
font_size 16 For best results, stick to the preset sizes in the editing menu: 8, 10, 12, 14, 16, 18, 20, 22, 26, 32, 40, 56, 72, 100, 200, 300.
rotation 0
color "rgb(0, 0, 0)"
font_family "unset" See values in text editing menu.
layer ""
controlledby "" Comma-delimited list of player IDs who can control the text. Controlling players may delete the text. If the text was created by a player, that player is automatically included in the list.

Graphic (Token/Map/Card/Etc.)

Property Default Value Notes
_id A unique ID for this object. Globally unique across all objects in this campaign. Read-only.
_type "graphic" Can be used to identify the object type or search for the object. Read-only.
_subtype "token" May be "token" (for tokens and maps) or "card" (for cards). Read-only.
_cardid Set to an ID if the graphic is a card. Read-only.
_pageid ID of the page the object is in. Read-only.
_bar1_link Set to an ID if Bar 1 is linked to a character. Read-only.
_bar2_link
_bar3_link
_represents ID of the character this token represents. Read-only.
left 0
top 0
width 0
height 0
rotation 0
layer ""
isdrawing false This property is changed from the Advanced context menu.
flipv false Flip vertically.
fliph false Flip horizontally.
name "" The token's name.
gmnotes "" Notes on the token only visible to the GM.
controlledby "" Comma-delimited list of player IDs who can control the text. Controlling players may delete the text. If the text was created by a player, that player is automatically included in the list.
bar1_value "" Current value of Bar 1. This may be a number or text.
bar2_value ""
bar3_value ""
bar1_max "" Maximum value of Bar 1. If _value and _max are both set, a bar may be displayed above the token showing the percentage of Bar 1.
bar2_max ""
bar3_max ""
aura1_radius "" Radius of the aura, using the units set in the page's settings. May be an integer or a float. Set to the empty string to clear the aura.
aura2_radius ""
aura1_color "#FFFF99" A hexadecimal color or the aura.
aura2_color "#59E594"
aura1_square false Is the aura a circle or a square?
aura2_square false
tint_color "transparent" Hexadecimal color, or "transparent". Will tint the color of the graphic.
statusmarkers "" A comma-delimited list of currently active statusmarkers. See the notes below for more information.
showname false Whether the token's nameplate is shown.
showplayers_name false Show the nameplate to all players.
showplayers_bar1 false Show Bar 1 to all players.
showplayers_bar2 false
showplayers_bar3 false
showplayers_aura1 false Show Aura 1 to all players.
showplayers_aura2 false
playersedit_name false Allow controlling players to edit the token's name. Also shows the nameplate to controlling players, even if showplayers_name is false.
playersedit_bar1 false Allow controlling players to edit the token's Bar 1. Also shows Bar 1 to controlling players, even if showplayers_bar1 is false.
playersedit_bar2 false
playersedit_bar3 false
playersedit_aura1 false Allow controlling players to edit the token's Aura 1. Also shows Aura 1 to controlling players, even if showplayers_aura1 is false.
playersedit_aura2 false
light_radius "" Dynamic lighting radius.
light_dimradius "" Start of dim light radius. If light_dimradius is the empty string, the token will emit bright light out to the light_radius distance. If light_dimradius has a value, the token will emit bright light out to the light_dimradius value, and dim light from there to the light_radius value.
light_otherplayers false Show the token's light to all players.

Important Notes About Linked Characters + Tokens

Note that for tokens that are linked to Characters, the controlledby field on the token is overridden by the controlledby field on the Character.

For token bars (e.g. bar1_value and bar1_max) where the token is linked to an Attribute (e.g. bar1_link is set), setting a value to the bar will automatically update the underlying Attribute's current and/or max values as well, so you don't have to set both manually.

In addition, when the Attribute (or token bar) is modified in-game, you will hear a change:attribute (and property-specific, e.g. change:attribute:current) event, followed by a change:graphic (and change:graphic:bar1_value) event. You can choose to respond to either event, but the underlying bar values will not yet be updated when the attribute event fires, since it fires first.

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

Property Default Value Notes
_id A unique ID for this object. Globally unique across all objects in this campaign. Read-only.
_type "page" Can be used to identify the object type or search for the object. Read-only.
_zorder "" Comma-delimited list of IDs specifying the ordering of objects on the page. toFront and toBack (and their associated context menu items) can re-order this list. Read-only.
name "" Page's title.
showgrid true Show the grid on the map.
showdarkness false Show fog of war on the map.
showlighting false Use dynamic lighting.
width 25 Width in units.
height 25 Height in units.
snapping_increment 1 Size of a grid space in units.
grid_opacity 0.5 Opacity of the grid lines.
fog_opacity 0.35 Opacity of the fog of war for the GM.
background_color "#FFFFFF" Hexadecimal color of the map background.
gridcolor "#C0C0C0" Hexadecimal color of the grid lines.
grid_type "square" One of "square", "hexv", or "hexh".
scale_number 5 The distance of one unit.
scale_units "ft" The type of units to use for the scale.
gridlabels false Show grid labels for hexagonal grid.
diagonaltype "foure" One of "foure", "pythagorean" (Euclidean), "threefive", or "manhattan".
archived false whether the page has been put into archive storage.

Campaign

Property Default Value Notes
_id "root" A unique ID for this object. Globally unique across all objects in this campaign. Read-only.
_type "campaign" Can be used to identify the object type or search for the object — however, note that there is only one Campaign object, and it can be accessed via Campaign(). Read-only.
turnorder "" A JSON string of the turn order. See below.
initiativepage false ID of the page used for the tracker when the turn order window is open. When set to false, the turn order window closes.
playerpageid false ID of the page the player bookmark is set to.

Turn Order

The turn order is a JSON string representing the current turn order listing. It is an array of objects. Currently, the turn order can only contain objects from one page at a time -- the current Page ID for the turn order is the "initiativepage" attribute. Be sure to keep them both in-sync or you may end up with strange results.

To work with the turn order, you will want to use JSON.parse() to get an object representing the current turn order state (NOTE: Check to make sure it's not an empty string "" first...if it is, initialize it yourself with an empty array). Here's an example turn order object:

[
    {
     "id":"36CA8D77-CF43-48D1-8682-FA2F5DFD495F", //The ID of the Graphic object. If this is set, the turn order list will automatically pull the name and icon for the list based on the graphic on the tabletop.
     "pr":"0", //The current value for the item in the list. Can be a number or text.
     "custom":"" //Custom title for the item. Will be ignored if ID is set to a value other than "-1".
    },
    {
     "id":"-1", //For custom items, the ID MUST be set to "-1" (note that this is a STRING not a NUMBER.
     "pr":"12",
     "custom":"Test Custom" //The name to be displayed for custom items.
    }
]

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;
if(Campaign().get("turnorder") == "") turnorder = []; //NOTE: We check to make sure that the turnorder isn't just an empty string first. If it is treat it like an empty array.
else turnorder = JSON.parse(Campaign().get("turnorder"));

//Add a new custom entry to the end of the turn order.
turnorder.push({
    id: "-1",
    pr: "15",
    custom: "Turn Counter"
});
Campaign().set("turnorder", JSON.stringify(turnorder));

Player

Property Default Value Notes
_id A unique ID for this object. Globally unique across all objects in this campaign. Read-only.
_type "player" Can be used to identify the object type or search for the object. Read-only.
_d20userid User ID — site-wide. For example, the player's user page on the wiki is /User:ID, where ID is the same value stored in _d20userid. Read-only.
_displayname "" The player's current display name. May be changed from the user's settings page. Read-only.
_online false Read-only.
_macrobar "" Comma-delimited string of the macros in the player's macro bar. Read-only.
speakingas "" ID", where ID is the character's ID. When the GM is speaking as another player, the value is "player|ID", where ID is the player's ID.
color "#13B9F0" The color of the square by the player's name, as well as the color of their measurements on the map, their ping circles, etc.
showmacrobar false Whether the player's macro bar is showing.

Macro

Property Default Value Notes
_id A unique ID for this object. Globally unique across all objects in this campaign. Read-only.
_type "macro" Can be used to identify the object type or search for the object. Read-only.
_playerid The ID of the player that created this macro. Read-only.
name "" The macro's name.
action "" The text of the macro.
visibleto "" Comma-delimited list of player IDs who may view the macro in addition to the player that created it.

Rollable Table

Property Default Value Notes
_id A unique ID for this object. Globally unique across all objects in this campaign. Read-only.
_type "rollabletable" Can be used to identify the object type or search for the object. Read-only.
name "new-table"
showplayers true

Table Item

Property Default Value Notes
_id A unique ID for this object. Globally unique across all objects in this campaign. Read-only.
_type "tableitem" Can be used to identify the object type or search for the object. Read-only.
_rollabletableid "" ID of the table this item belongs to. Read-only.
_avatar "" URL to an image used for the table item. Read-only.
name ""
weight 1 Weight of the table item compared to the other items in the same table. Simply put, an item with weight 3 is three times more likely to be selected when rolling on the table than an item with weight 1.

Character

Property Default Value Notes
_id A unique ID for this object. Globally unique across all objects in this campaign. Read-only.
_type "character" Can be used to identify the object type or search for the object. Read-only.
_avatar "" URL to an image used for the character. Read-only.
name ""
bio "" The character's biography.
gmnotes "" Notes on the character only viewable by the GM.
archived false
inplayerjournals "" Comma-delimited list of player ID who can view this character. Use "all" to give all players the ability to view.
controlledby "" Comma-delimited list of player IDs who can control and edit this character. Use "all" to give all players the ability to edit.

Attribute

Property Default Value Notes
_id A unique ID for this object. Globally unique across all objects in this campaign. Read-only.
_type "attribute" Can be used to identify the object type or search for the object. Read-only.
_characterid "" ID of the character this attribute belongs to. Read-only.
name "Untitled"
current "" Attribute Name} or in abilities with the syntax @{Attribute Name}.
max ""

Ability

Property Default Value Notes
_id A unique ID for this object. Globally unique across all objects in this campaign. Read-only.
_type "ability" Can be used to identify the object type or search for the object. Read-only.
_characterid "" The character this ability belongs to.
name "Untitled_Ability"
description "" The description does not appear in the character sheet interface.
action "" The text of the ability.

Handout

Property Default Value Notes
_id A unique ID for this object. Globally unique across all objects in this campaign. Read-only.
_type "handout" Can be used to identify the object type or search for the object. Read-only.
_avatar "" URL to an image used for the handout. Read-only.
name "Mysterious Note"
notes "" Contains the text in the handout.
inplayerjournals "" Comma-delimited list of player ID who can see this handout. Use "all" to display to all players.
archived false
controlledby "" Comma-delimited list of player IDs who can control and edit this handout.

Creating Objects


createObj(type, attributes)

You can create a new object in the game using the createObj function. You must pass in the type of the object (one of the valid _type properties from the objects list above), as well as a an attributes object containing a list of properties for the object. Note that if the object is has a parent object (for example, attributes and abilities belong to characters), you must pass in the ID of the parent in the list of properties (for example, you must include the characterid property when creating an attribute). Also note that even when creating new objects, you can't set read-only properties, they will automatically be set to their default value.

createObj will return the new object, so you can continue working with it.

//Create a new Strength attribute on any Characters that are added to the game.
on("add:character", function(obj) {
    createObj("attribute", {
        name: "Strength",
        current: 0,
        max: 30,
        characterid: obj.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().get("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. In addition, the state object is persisted between play sessions, so you can use this object to store long-term information about the state of the game.

You should use the state object to store information that is only related to the API, since it is not sent to player computers and does not make your campaign file larger, and store properties that are needed in-game in the objects themselves.

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.

getObj(type, id)

This function gets a single object if pass in the _type of the object and the _id. It's best to use this function over the other find functions whenever possible, as its the only one that doesn't have to iterate through the entire collection of objects.

on("change:graphic:represents", function(obj) {
    if(obj.get("represents") != "") {
       var character = getObj("character", obj.get("represents"));
    }
});


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.
});

You can also pass in an optional second argument which contains an object with a list of options, including:

  • caseInsensitive (true/false): If true, string properties will be compared without regard for the case of the string.


var targetTokens = findObjs({
    name: "target"
}, {caseInsensitive: true});
//Returns all tokens with a name of 'target', 'Target', 'TARGET', etc.


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.