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 "API:Objects"

From Roll20 Wiki

Jump to: navigation, search
(Graphic (Token/Map/Card/Etc.))
(Card)
 
(173 intermediate revisions by 29 users not shown)
Line 1: Line 1:
 +
{{revdate}}{{HCbox| {{hc|articles/360037772793-API-Objects Here}} }}
 +
{{API dev}}
 
{{apibox}}
 
{{apibox}}
 +
== 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 ({{code|_}}) are '''read-only''' and cannot be changed. You must access properties on objects using {{code|obj.get("property")}} and set new values using <code>obj.set("property", newvalue)</code> or <code>obj.set({property: newvalue, property2: newvalue2})</code>.
  
==Types of Objects==
+
'''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).
  
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>.
+
__TOC__
 +
=== [[Campaign]] ===
  
'''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).
+
{| class="wikitable"
 +
|-
 +
! Property
 +
! Default Value
 +
! Notes
 +
|-
 +
| _id
 +
| "root"
 +
| A unique ID for this object. Globally unique across all objects in this game. 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 Tracker|turn order]]. See below.
 +
|-
 +
| initiativepage
 +
| false
 +
| ID of the page used for the {{Turn 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. [[Players]] see this page by default, unless overridden by playerspecificpages below.
 +
|
 +
|-
 +
| playerspecificpages
 +
| false
 +
| An object (NOT JSON STRING) of the format: {"player1_id": "page_id", "player2_id": "page_id" ... } Any player set to a page in this object will override the playerpageid.
 +
|
 +
|-
 +
| _journalfolder
 +
| ""
 +
| A JSON string which contains data about the folder structure of the game. Read-only.
 +
|-
 +
| _jukeboxfolder
 +
| ""
 +
| A JSON string which contains data about the jukebox playlist structure of the game. Read-only.
 +
|-
 +
| [[API:Token Markers|token_markers]]
 +
| ""
 +
| A stringified JSON array containing an object for each token marker currently in the game
 +
|}
  
===Path===
+
====Turn Order====
<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===
+
The turn order is a JSON string representing the current turn order listing seen on the {{Turn Tracker}}. 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 <code>initiativepage</code> attribute. Be sure to keep them both in-sync or you may end up with strange results. You must include the Page ID in <code>_pageid</code> property for each item in the <code>turnorder</code> when added or edited.
  
<pre data-language="javascript">
+
To work with the turn order, you will want to use <code>JSON.parse()</code> to get an object representing the current turn order state (NOTE: Check to make sure it's not an empty string <code>""</code> first...if it is, initialize it yourself with an empty array). Here's an example turn order object:
{  
+
 
  _id: "-Abc123",  
+
<pre style="overflow:auto;white-space:pre-wrap;" data-language="javascript">
  top: 0,  
+
[
  left: 0,   
+
    {
  width: 0,   
+
    "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.
  height: 0,   
+
    "pr":"0", //The current value for the item in the list. Can be a number or text.
  text: "",   
+
    "custom":"", //Custom title for the item. Will be ignored if ID is set to a value other than "-1".
  font_size: 16, //for best results stick to the pre-sets in the text editing menu   
+
    "_pageid": Campaign().get("playerpageid")
  rotation: 0,   
+
    },
  color: "#000000",   
+
    {
  font_family: "unset", //see values of select element in text editing menu   
+
    "id":"-1", //For custom items, the ID MUST be set to "-1" (note that this is a STRING not a NUMBER.
  layer: "",  
+
    "pr":"12",
  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.
+
    "custom":"Test Custom", //The name to be displayed for custom items.
  _type: "text", //identifies the object is text. read-only.
+
    "_pageid": Campaign().get("playerpageid")
  _pageid: "-Abc123"
+
    }
}
+
]
 
</pre>
 
</pre>
  
===Graphic (Token/Map/Card/Etc.)===
+
To modify the turn order, edit the current turn order object and then use <code>JSON.stringify()</code> 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 <code>push()</code> adds an item onto the end of the list, <code>unshift()</code> adds to the beginning, etc.
<pre data-language="javascript">
+
 
{   
+
<pre style="overflow:auto;white-space:pre-wrap;" data-language="javascript">
  _id: "-Abc123",   
+
var turnorder;
  left: 0,   
+
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.
  top: 0, 
+
else turnorder = JSON.parse(Campaign().get("turnorder"));
  width: 0,   
+
 
  height: 0,   
+
//Add a new custom entry to the end of the turn order.
  rotation: 0.0,   
+
turnorder.push({
  layer: "",   
+
    id: "-1",
  isdrawing: false, //advanced -> is drawing?   
+
    pr: "15",
  flipv: false, //flip vertically   
+
    custom: "Turn Counter"
  fliph: false, //flip horizontally   
+
    _pageid: Campaign().get("playerpageid")
  name: "", //Token Name   
+
});
  gmnotes: "", //GM Notes   
+
Campaign().set("turnorder", JSON.stringify(turnorder));
  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)  
+
  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: "",
+
  _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.   
+
  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"   
+
  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_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: ""
+
}
+
 
</pre>
 
</pre>
  
'''Important Notes About Linked Characters + Tokens'''
+
=== Player ===
 +
See also: [[Player]]
 +
 
 +
{| class="wikitable"
 +
|-
 +
! Property
 +
! Default Value
 +
! Notes
 +
|-
 +
| _id
 +
|
 +
| A unique ID for the player (referred to as "player ID" in other parts of the guide). Globally unique across all objects in this game. Read-only. Players will have new player ID for each game they are part of, so does not persist between games. See '''roll20id''' below for the permanent ID unique to each account.
 +
|-
 +
| _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 {{code|_d20userid}}. Also called [[roll20id]]. Read-only.
 +
|-
 +
| _displayname
 +
| ""
 +
| The player's current display name. May be changed from the user's [[My Settings]]-tab. Read-only.
 +
|-
 +
| _online
 +
| false
 +
| Read-only.
 +
|-
 +
| _lastpage
 +
| ""
 +
| The page id of the last page the player viewed as a [[GM]].  This property is not updated for players or GMs that have joined as players. 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 "Speaking As" dropdown. When set to the empty string, the player is speaking as themselves. When set to a character, the value is {{code|character<nowiki>|</nowiki>''ID''", where ID is the character's ID. When the GM is speaking as another player, the value is {{code|player<nowiki>|</nowiki>''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.
 +
|}
 +
 
 +
=== Page ===
 +
See Also: [[Page Toolbar]]
 +
 
 +
{| class="wikitable"
 +
|-
 +
! Property
 +
! style="min-width:10em" | Default Value
 +
! Notes
 +
|-
 +
| _id
 +
|
 +
| A unique ID for this object. Globally unique across all objects in this game. 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.
 +
|-
 +
| width
 +
| 25
 +
| Width in units.
 +
|-
 +
| height
 +
| 25
 +
| Height in units.
 +
|-
 +
| background_color
 +
| "#FFFFFF"
 +
| Hexadecimal color of the map background.
 +
|-
 +
| archived
 +
| false
 +
| Whether the page has been put into archive storage.
 +
|-
 +
| jukeboxtrigger || || Controls the Page Play on Load. Options include ‘nonestopall’ or the id-of-the-track
 +
|-
 +
| showdarkness
 +
| false
 +
| Show [[Fog of War]] on the map.
 +
|-
 +
| fog_opacity
 +
| 0.35
 +
| Opacity of the [[Fog of War]] for the GM.
 +
|- style="background-color: #c6c2c2;"
 +
|  || '''Grid''' || grid-related keys
 +
|-
 +
| showgrid
 +
| true
 +
| Show the grid on the map.
 +
|-
 +
| grid_opacity
 +
| 0.5
 +
| Opacity of the grid lines.
 +
|-
 +
| gridcolor
 +
| "#C0C0C0"
 +
| Hexadecimal color of the grid lines.
 +
|-
 +
| grid_type
 +
| "square"
 +
| One of "square", "hex", "hexr"  (hex corresponds to Hex(V), and hexr corresponds to Hex(H)), "dimetric", or "isometric".
 +
|-
 +
| gridlabels
 +
| false
 +
| Show grid labels for hexagonal grid.
 +
|-
 +
| snapping_increment
 +
| 1
 +
| Size of a grid space in units.
 +
|-
 +
| scale_number
 +
| 5
 +
| The distance of one unit.
 +
|-
 +
| scale_units
 +
| "ft"
 +
| The type of units to use for the scale.
 +
|-
 +
| diagonaltype
 +
| "foure"
 +
| One of "foure", "pythagorean" (Euclidean), "threefive", or "manhattan".
 +
|- style="background-color: #c6c2c2;"
 +
|  || '''[[Dynamic Lighting]]''' || keys for Updated DL
 +
|-
 +
| dynamic_lighting_enabled || Boolean || Toggles updated dynamic lighting for the page.
 +
|-
 +
| daylight_mode_enabled || Boolean || Toggles daylight mode for the page. This should not be turned on if dynamic_lighting_enabled is not turned on.
 +
|-
 +
| daylightModeOpacity || || {{fpl|10334884/ use example}}
 +
|-
 +
| explorer_mode || String || Toggles explorer mode for the page. This should not be turned on if dynamic_lighting_enabled is not turned on.
 +
Use the strings ”basic” to turn on or ”off” to turn off.
 +
|-
 +
| force_lighting_refresh || Boolean || Triggers a refresh of all token lighting/vision on a page. Can be used in a single call after putting multiple tokens onto a page. (Will be deprecated in the coming months!)
 +
|-
 +
| fog_opacity || Boolean || Opacity of the fog of war for the GM.
 +
|-
 +
| lightupdatedrop || Boolean || Only update Dynamic Lighting when an object is dropped.
 +
|- style="background-color: #c6c2c2;"
 +
|  || [[Legacy DL]] || keys for Legacy Dynamic Lighting. Some are still used with UDL
 +
|-
 +
| showlighting
 +
| false
 +
| Use dynamic lighting.
 +
|-
 +
| lightupdatedrop
 +
| false
 +
| Only update [[Dynamic Lighting]] when an object is dropped.
 +
|-
 +
| lightenforcelos
 +
| false
 +
| Enforce Line of Sight for objects.
 +
|-
 +
| lightrestrictmove
 +
| false
 +
| Don't allow objects that have sight to move through Dynamic Lighting walls.
 +
|-
 +
| lightglobalillum
 +
| false
 +
| If true anywhere a [[token]] can "see" it is assumed there is bright light present.
 +
|}
 +
 
 +
=== Path ===
 +
{{main|API:Objects/Path}}
 +
For more information on the {{code|_path}} data format, see: [[API:Objects/Path|Objects/Path]]
 +
{{:API:Objects/Path}}
 +
 
 +
=== Text ===
 +
 
 +
{| class="wikitable"
 +
|-
 +
! Property
 +
! Default Value
 +
! Notes
 +
|-
 +
| _id
 +
|
 +
| A unique ID for this object. Globally unique across all objects in this game. 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
 +
| "Arial"
 +
| If this is not set, when later changing the value of the "text" property the font_size will shrink to 8.  Possible values (Case is not important):
 +
* "Arial"
 +
* "Patrick Hand"
 +
* "Contrail One"
 +
* "Shadows Into Light"
 +
* "Candal"
 +
* "Tahoma"
 +
* "Nunito"
 +
* "Merriweather"
 +
* "Anton"
 +
* "Rye"
 +
* "IM Fell DW Pica"
 +
* "Montserrat"
 +
* "Goblin One"
 +
* "Della Respira"
 +
* "Crimson Text"
 +
* "Kaushan Script"
 +
 
 +
Specifying an invalid name results in an unnamed, monospaced serif font being used.
 +
|-
 +
| layer
 +
| ""
 +
| <code>gmlayer</code>, <code>objects</code>, <code>map</code>, or <code>walls</code>.
 +
|-
 +
| 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.
 +
 
 +
'''All Players''' is represented by having 'all' in the list.
 +
|}
 +
 
 +
=== Graphic (Token/Map/Card/Etc.) ===
 +
For the new [[UDL]] support for [[tokens]], see the [[Help Center]]'s {{hc|articles/360046490373-Updated-Dynamic-Lighting-API-Support API UDL Support}}.
 +
 
 +
 
 +
====General====
 +
{| class="wikitable"
 +
! Property
 +
! Default Value
 +
! Notes
 +
|-
 +
| _id
 +
|
 +
| A unique ID for this object. Globally unique across all objects in this game. 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.
 +
|-
 +
| imgsrc
 +
|
 +
| The URL of the graphic's image. More details under [[#imgsrc and avatar property restrictions]]
 +
|-
 +
| represents
 +
|
 +
| ID of the character this token represents.
 +
|-
 +
| left
 +
| 0
 +
| Number of pixels from the left edge of the map to the center of the graphic.
 +
|-
 +
| top
 +
| 0
 +
| Number of pixels from the top edge of the map to the center of the graphic.
 +
|-
 +
| width
 +
| 0
 +
| Width of the graphic, in pixels.
 +
|-
 +
| height
 +
| 0
 +
| Height of the graphic, in pixels.
 +
|-
 +
| rotation
 +
| 0
 +
| The orientation of the token in degrees.
 +
|-
 +
| layer
 +
| ""
 +
| <code>gmlayer</code>, <code>objects</code>, <code>map</code>, or <code>walls</code>
 +
|-
 +
| 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.
 +
|-
 +
| tooltip
 +
| ""
 +
| The text saved on a token's [[Token Tooltip|tootip]]. ''(May 2022)'': API can exceed the 150 character limit when writing to the tooltip. 
 +
|-
 +
| show_tooltip
 +
| false
 +
| '''(toggle doesn't work yet(2021-10-05))''' show or hide the token's tooltip.
 +
|-
 +
| controlledby
 +
| ""
 +
| Comma-delimited list of [[player]] IDs who can control the graphic. Controlling players may delete the graphic. If the graphic was created by a player, that player is automatically included in the list.
 +
 
 +
'''All Players''' is represented by having 'all' in the list.
 +
|-
 +
| bar1_link
 +
|
 +
| Set to an ID if Bar 1 is linked to a character.
 +
|-
 +
| bar2_link || ||
 +
|-
 +
| bar3_link  || ||
 +
|-
 +
| 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 <code>_value</code> and <code>_max</code> are both set, a bar may be displayed above the token showing the percentage of Bar 1.
 +
|-
 +
| bar2_max  || ||
 +
|-
 +
| bar3_max
 +
|-
 +
| bar_location ||  || Adjusts the location of the token bars. Options include <code>overlap_top</code>, <code>overlap_bottom</code>, <code>bottom</code>
 +
|-
 +
| compact_bar ||  || Adjusts whether the bar is compact or not. Other option is compact.
 +
|-
 +
| 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
 +
| true
 +
| Allow controlling players to edit the token's name. Also shows the nameplate to controlling players, even if {{c|showplayers_name}} is false.
 +
|-
 +
| playersedit_bar1
 +
| true
 +
| Allow controlling players to edit the token's Bar 1. Also shows Bar 1 to controlling players, even if {{c|showplayers_bar1}} is false.
 +
|-
 +
| playersedit_bar2
 +
| true
 +
|
 +
|-
 +
| playersedit_bar3
 +
| true
 +
|
 +
|-
 +
| playersedit_aura1
 +
| true
 +
| Allow controlling players to edit the token's Aura 1. Also shows Aura 1 to controlling players, even if {{c|showplayers_aura1}} is false.
 +
|-
 +
| playersedit_aura2
 +
| true
 +
|
 +
|-
 +
| lastmove
 +
| ""
 +
| The last move of the token. It's a comma-delimited list of coordinates. For example, {{c|300,400}} would mean that the token started its last move at left=300, top=400. It's always assumed that the current top + left values of the token are the "ending point" of the last move. [[Manipulating Graphics#Waypoints|Waypoints]] are indicated by multiple sets of coordinates. For example, {{c|300,400,350,450,400,500}} would indicate that the token started at left=300, top=400, then set a waypoint at left=350, top=450, another waypoint at left=400, top=500, and then finished the move at its current top + left coordinates.
 +
|-
 +
| sides
 +
| ""
 +
| A list of the image URLs for a rollable table token ([[Multi-sided Token]]), delimited by pipes <code>&#124;</code>
 +
|-
 +
| currentSide
 +
| 0
 +
| The index of the current image displayed by a rollable table token (multi-sided token)
 +
|-
 +
| lockMovement
 +
| false
 +
| (boolean) If the token's movement is locked or not.{{source|https://app.roll20.net/forum/permalink/10728108/ March 2nd, 2022}} A locked token can still be moved by API commands. See also: [[Token Lock]]
 +
|}
 +
 
 +
====[[UDL|Dynamic Lighting]]====
 +
{| class="wikitable"
 +
! Property
 +
! Description
 +
! Type
 +
|-
 +
| has_bright_light_vision || Toggles vision for the token. || Boolean
 +
|-
 +
| has_night_vision || Toggles night vision for the token. || Boolean
 +
|-
 +
| night_vision_distance || Sets the range of night vision for the token. || Integer
 +
|-
 +
| emits_bright_light || Toggles bright light for the token. || Boolean
 +
|-
 +
| bright_light_distance || Sets the range of the amount of bright light emitting from a token. || Integer
 +
|-
 +
| emits_low_light || Toggles low light for the token. This would be useful for a torch or a source with a low amount of light. Use the booleans true to turn on or false to turn off. || Boolean
 +
|-
 +
| dim_light_opacity || Sets the "opacity" of the dim light. Lower values provide dimmer light, higher values yield brighter dim light. Default on new graphics is 0.75. || Decimal from 0.0 to 1.0
 +
|-
 +
| low_light_distance || Sets the range of the amount of low light emitting from a token. When setting this value, you must include any Bright Light Distance you have set. The reason for this is because Low Light Distance is calculated from the center of the token. So if you have set Bright Light Distance to 10, and you would like an additional 10 feet of Low Light Distance, the value of {{c|low_light_distance}} must be 20. || Integer
 +
|-
 +
| light_sensitivity_multiplier || Multiplier on the effectiveness of light sources. A multiplier of 200 would allow the token to see twice as far as a token with a multiplier of 100, with the same light source. || Integer
 +
|-
 +
| night_vision_effect || Changes the Night Vision Effect. Other options include {{c|Dimming}} and {{c|Nocturnal}} || String
 +
|-
 +
| has_limit_field_of_vision || Toggles limit field of vision for the token. || Boolean
 +
|-
 +
| limit_field_of_vision_center || Sets the value for where the center of the field of vision starts. || Integer
 +
|-
 +
| limit_field_of_vision_total || Set the value for the total size of the field of vision. || Integer
 +
|-
 +
| has_limit_field_of_night_vision || Toggles limit field of night vision for the token. || Boolean
 +
|-
 +
| limit_field_of_night_vision_center || Sets the value for where the center of the field of night vision starts. || Integer
 +
|-
 +
| limit_field_of_night_vision_total || Set the value for the total size of the field of night vision. || Integer
 +
|-
 +
| has_directional_bright_light || Toggles directional bright light for the token. || Boolean
 +
|-
 +
| directional_bright_light_center || Sets the value for where the center of the field of bright light starts. || Integer
 +
|-
 +
| directional_bright_light_total || Set the value for the total size of the field of bright light. || Integer
 +
|-
 +
| has_directional_dim_light || Toggles directional low light for the token. || Boolean
 +
|-
 +
| directional_dim_light_center || Sets the value for where the center of the field of low light starts. || Integer
 +
|-
 +
| directional_dim_light_total || Set the value for the total size of the field of low light. || Integer
 +
|-
 +
| lightColor || Sets color of light. (e.g. {{c|#FF0000}} for red) || hexadecimal
 +
|}
 +
 
 +
====[[Legacy Dynamic Lighting]]====
 +
{| class="wikitable"
 +
! Property
 +
! Default Value
 +
! Notes
 +
|-
 +
| light_radius
 +
| ""
 +
| Dynamic lighting radius.
 +
|-
 +
| light_dimradius
 +
| ""
 +
| Start of dim light radius. If {{c|light_dimradius}} is the empty string, the token will emit bright light out to the {{c|light_radius}} distance. If {{c|light_dimradius}} has a value, the token will emit bright light out to the {{c|light_dimradius}} value, and dim light from there to the {{c|light_radius}} value.
 +
|-
 +
| light_otherplayers
 +
| false
 +
| Show the token's light to all players.
 +
|
 +
|-
 +
| light_hassight
 +
| false
 +
| The light has "sight" for controlling players for the purposes of the "Enforce Line of Sight" setting.
 +
|
 +
|-
 +
| light_angle
 +
| "360"
 +
| Angle (in degrees) of the light's angle. For example, {{c|180}} means the light would show only for the front "half" of the "field of vision".
 +
|
 +
|-
 +
| light_losangle
 +
| "360"
 +
| Angle (in degrees) of the field of vision of the graphic (assuming that {{c|light_hassight}} is set to {{c|true}})
 +
|
 +
|-
 +
| light_multiplier
 +
| "1"
 +
| Multiplier on the effectiveness of light sources. A multiplier of two would allow the token to see twice as far as a token with a multiplier of one, with the same light source.
 +
|-
 +
| adv_fow_view_distance
 +
| ""
 +
| The radius around a token where [[Advanced Fog of War]] is revealed.
 +
|}
 +
 
 +
====Linked Characters + Tokens ====
  
 
Note that for tokens that are linked to Characters, the <code>controlledby</code> field on the token is overridden by the <code>controlledby</code> field on the Character.  
 
Note that for tokens that are linked to Characters, the <code>controlledby</code> field on the token is overridden by the <code>controlledby</code> field on the Character.  
Line 113: Line 693:
 
In addition, when the Attribute (or token bar) is modified in-game, you will hear a <code>change:attribute</code> (and property-specific, e.g. <code>change:attribute:current</code>) event, followed by a <code>change:graphic</code> (and <code>change:graphic:bar1_value</code>) 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.
 
In addition, when the Attribute (or token bar) is modified in-game, you will hear a <code>change:attribute</code> (and property-specific, e.g. <code>change:attribute:current</code>) event, followed by a <code>change:graphic</code> (and <code>change:graphic:bar1_value</code>) 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'''
+
The {{c|statusmarkers}} property of the Graphic object is (still in 2021?) a comma-delimited list of all status marker colors/icons that should be active on the token. The format is as follows:
 
+
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:
+
  
<pre data-language="javascript">
+
<pre style="overflow:auto;white-space:pre-wrap;" data-language="javascript">
 
//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
 
//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"
 
statusmarkers = "red,blue,skull,dead,brown@2,green@6"
 
</pre>
 
</pre>
  
While you can access the <code>statusmarkers</code> 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:
+
While you can access the <code>statusmarkers</code> 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 {{c|status_<markername>}} property. For example:
  
<pre data-language="javascript">
+
<pre style="overflow:auto;white-space:pre-wrap;" data-language="javascript">
 
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_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.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_red", false); //would remove the marker
obj.set("status_red", "2"); //would set a badge of "2" on the red marker, and add it to the token if it's not already active.
+
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.
 
</pre>
 
</pre>
  
Note that these virtual properties do not have events, so you must use <code>change:graphic:statusmarkers</code> to listen for changes to the status markers of a token, and for example <code>change:graphic:status_red</code> is NOT a valid event that will ever fire.
+
Note that these virtual properties do not have events, so you must use <code>change:graphic:statusmarkers</code> to listen for changes to the status markers of a token, and for example <code>change:graphic:status_red</code> is NOT a valid event and will never fire.
  
 
The full list of status markers that are available (in the same order they appear in the marker tray):
 
The full list of status markers that are available (in the same order they appear in the marker tray):
Line 137: Line 715:
 
<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)===
 
<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===
+
==== imgsrc and avatar property restrictions ====
<pre data-language="javascript">
+
{   
+
  _type: "campaign",   
+
  turnorder: "", // a JSON string, see below for more details 
+
  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 
+
}
+
</pre>
+
  
'''Turn Order'''
+
While you can now edit the <code>imgsrc</code> and <code>avatar</code>([[#Character|Character]]) properties, in order to provide safety to all Roll20's users we have put the following restrictions in place for those properties:
  
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.
+
* '''You must use an image file that has been uploaded to [[Art Library|your Roll20 Library]]''' -- not an external site (such as Imgur), and not the Roll20 [[Marketplace]]. It will begin with <code><nowiki>https://s3.amazonaws.com/files.d20.io/images/</nowiki></code> for images uploaded to the Main server, or <code><nowiki>https://s3.amazonaws.com/files.staging.d20.io/images/</nowiki></code> for images uploaded to the [[Dev Server]]. You can view an image's source URL using the developer tools of your browser.
  
To work with the turn order, you will want to use <code>JSON.parse()</code> to get an object representing the current turn order state (NOTE: Check to make sure it's not an empty string <code>""</code> first...if it is, initialize it yourself with an empty array). Here's an example turn order object:
+
* You must include the query string in the URL -- for example <code><nowiki>https://s3.amazonaws.com/files.staging.d20.io/images/123456/med.png?12345678</nowiki></code>, not just <code><nowiki>https://s3.amazonaws.com/files.staging.d20.io/images/123456/med.png</nowiki></code>
  
<pre data-language="javascript">
+
* For Graphic objects (tokens), you must use the "thumb" size of the image. It should look like <code><nowiki>https://s3.amazonaws.com/files.staging.d20.io/images/123456/thumb.png?12345678</nowiki></code>.
[
+
    {
+
    "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.
+
    }
+
]
+
</pre>
+
  
To modify the turn order, edit the current turn order object and then use <code>JSON.stringify()</code> 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 <code>push()</code> adds an item onto the end of the list, <code>unshift()</code> adds to the beginning, etc.
 
  
<pre data-language="javascript">
+
In the future we may add a tool so that images can be uploaded specifically for use with API scripts, but for now just use images uploaded to your own [[Art Library|library]]. '''Note:''' If you delete an image from your library, it will be removed from all Games which use that image, including Games using your API scripts.
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.
+
=== Journal===
turnorder.push({
+
Things in the {{Journal}}, i.e Characters & Handouts.
    id: "-1",
+
==== [[Character]] ====
    pr: "15",
+
See also the [[#imgsrc and avatar property restrictions|imgsrc and avatar property restrictions]]
    custom: "Turn Counter"
+
});
+
Campaign().set("turnorder", JSON.stringify(turnorder));
+
</pre>
+
  
===Player===
+
{| class="wikitable"
<pre data-language="javascript">
+
|-
{   
+
! Property
  _d20userid: "", //The site-wide unique ID of the user.
+
! Default Value
  _displayname: "", //Current display name   
+
! Notes
  _online: false,   
+
|-
  color: "#13B9F0",   
+
| _id
  _macrobar: "", //Comma-delimited string of the macros in the player's macro bar.  
+
|
  showmacrobar: false, //Show macro bar? 
+
| A unique ID for this object. Globally unique across all objects in this game. Read-only.
  _id: "",   
+
|-
  _type: "player"
+
| _type
}
+
| "character"
</pre>
+
| Can be used to identify the object type or search for the object. Read-only.
 +
|-
 +
| avatar
 +
| ""
 +
| URL to an image used for the character. See the note about avatar and imgsrc restrictions below.
 +
|-
 +
| name
 +
| ""
 +
|
 +
|-
 +
| bio
 +
| ""
 +
| The character's biography. See the note below about accessing the Notes, GMNotes, and bio fields.
 +
|-
 +
| gmnotes
 +
| ""
 +
| Notes on the character only viewable by the GM. See the note below about accessing the Notes, GMNotes, and bio fields.
 +
|-
 +
| archived
 +
| false
 +
|
 +
|-
 +
| inplayerjournals
 +
| ""
 +
| Comma-delimited list of player ID who can view this character. Use "all" to give all players the ability to view.
  
 +
'''All Players''' is represented by having 'all' in the list.
 +
|-
 +
| controlledby
 +
| ""
 +
| Comma-delimited list of player IDs who can control and edit this character. Use "all" to give all players the ability to edit.
  
===Macro===
+
'''All Players''' is represented by having 'all' in the list.
<pre data-language="javascript">
+
|-
{   
+
| _defaulttoken
  name: "",   
+
| ""
  action: "",   
+
|  A JSON string that contains the data for the Character's default token if one is set. Note that this is a "blob" similar to "bio" and "notes", so you must pass a callback function to get(). Read-only.
  visibleto: "", //Comma-delimited list of additional Player IDs this macro is visible to
+
|}
  _id: "",   
+
  _type: "macro",  
+
  _playerid: "" //Player this macro belongs to  
+
}
+
</pre> 
+
  
 +
===== [[Attribute]] =====
  
===Rollable Table===
+
{| class="wikitable"
<pre data-language="javascript">
+
|-
{   
+
! Property
  name: "new-table",   
+
! Default Value
  showplayers: true,   
+
! Notes
  _type: "rollabletable",   
+
|-
  _id: ""
+
| _id
}
+
|
</pre>
+
| A unique ID for this object. Globally unique across all objects in this game. 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. Mandatory when using <code>createObj</code>.
 +
|-
 +
| name
 +
| "Untitled"
 +
|
 +
|-
 +
| current
 +
| ""
 +
| The current value of the attribute can be accessed in chat and macros with the syntax <code>@{Character Name<nowiki>|</nowiki>Attribute Name}</code> or in abilities with the syntax <code>@{Attribute Name}</code>.
 +
|-
 +
| max
 +
| ""
 +
|The max value of the attribute can be accessed in chat and macros with the syntax <code>@{Character Name<nowiki>|</nowiki>Attribute Name<nowiki>|</nowiki>max}</code> or in abilities with the syntax <code>@{Attribute Name<nowiki>|</nowiki>max}</code>.
 +
|}
  
  
===Table Item===
+
'''Important: See the note below about working with [[Character Sheets]] for information on how Character Sheet default values affect the use of Attributes.'''
 +
 
 +
===== [[Ability]] =====
 +
 
 +
{| class="wikitable"
 +
|-
 +
! Property
 +
! Default Value
 +
! Notes
 +
|-
 +
| _id
 +
|
 +
| A unique ID for this object. Globally unique across all objects in this game. 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. Read-only. Mandatory when using <code>createObj</code>.
 +
|-
 +
| name
 +
| "Untitled_Ability"
 +
|
 +
|-
 +
| description
 +
| ""
 +
| The description does not appear in the character sheet interface.
 +
|-
 +
| action
 +
| ""
 +
| The text of the ability.
 +
|-
 +
| istokenaction
 +
| false
 +
| Is this ability a token action that should show up when tokens linked to its parent Character are selected?
 +
|}
 +
 
 +
 
 +
 
 +
===== Working with Character Sheets =====
 +
 
 +
The [[Character Sheets]] affects the usage of the Attributes object type, because the sheets have the capability of specifying a default value for each attribute on the sheet. However, if the attribute is set to the default value, there is not yet an actual Attribute object created in the game for that Character. We provide a convenience function which hides this complexity from you. You should use this function to get the value of an attribute going forward, especially if you know that a game is using a Character Sheet.
 +
 
 +
More about editing character sheets and how they work: [[Building Character Sheets]]
 +
 
 +
'''getAttrByName(character_id, attribute_name, value_type)'''
 +
 
 +
Simply specify the character's ID, the '''name''' (not ID) of the attribute (e.g. "HP" or "Str"), and then if you want the "current" or "max" for value_type. Here's an example:
 +
 
 
<pre data-language="javascript">
 
<pre data-language="javascript">
{   
+
var character = getObj("character", "-JMGkBaMgMWiQdNDwjjS");
  name: "",  
+
getAttrByName(character.id, "str"); // the current value of str, for example "12"
  weight: 1,  
+
getAttrByName(character.id, "str", "max"); //the max value of str, for example "[[floor(@{STR}/2-5)]]"
  _type: "tableitem",  
+
  _id: "",  
+
  _rollabletableid: "" //ID of the rollable table this item belongs to
+
}
+
 
</pre>
 
</pre>
  
 +
Note that fields which have [[Auto-Calc|auto-calculated values]] will return the formula rather than the result of the value. You can then pass that formula to <code>sendChat()</code> to use the dice engine to calculate the result for you automatically.
 +
 +
Be sure to also look at the [[Building Character Sheets]] documentation for more information on how they interact with the API.
 +
 +
<code>getAttrByName</code> will ''only'' get the value of the attribute, not the attribute object itself. If you wish to reference properties of the attribute other than "current" or "max", or if you wish to change properties of the attribute, you must use one of the other functions above, such as <code>findObjs</code>.
 +
 +
In the case that the requested attribute does not exist, <code>getAttrByName()</code> will return <code>undefined</code>.
 +
 +
==== [[Handouts|Handout]] ====
 +
 +
{| class="wikitable"
 +
|-
 +
! Property
 +
! Default Value
 +
! Notes
 +
|-
 +
| _id
 +
|
 +
| A unique ID for this object. Globally unique across all objects in this game. 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. See the note about avatar and imgsrc restrictions below.
 +
|-
 +
| name
 +
| "Mysterious Note"
 +
|
 +
|-
 +
| notes
 +
| ""
 +
| Contains the text in the handout. See the note below about using Notes and GMNotes.
 +
|-
 +
| gmnotes
 +
| ""
 +
| Contains the text in the handout that only the GM sees. See the note below about using Notes and GMNotes.
 +
|-
 +
| inplayerjournals
 +
| ""
 +
| Comma-delimited list of player ID who can see this handout. Use "all" to display to all players.
 +
 +
'''All Players''' is represented by having 'all' in the list.
 +
|-
 +
| archived
 +
| false
 +
|
 +
|-
 +
| controlledby
 +
| ""
 +
| Comma-delimited list of player IDs who can control and edit this handout.
 +
 +
'''All Players''' is represented by having 'all' in the list.
 +
|}
 +
 +
 +
'''Note:''' The API does not have access to the folder hierarchy. API created handouts will be placed at the root level.
 +
 +
==== Using the Notes, GMNotes, and Bio fields {{Asynchronous}} ====
 +
 +
In order to access the "notes", "gmnotes", or "bio" fields on [[Journal|Characters and Handouts]], you must pass a callback function as the second argument to the get() function. Here's an example:
  
===Character===
 
 
<pre data-language="javascript">
 
<pre data-language="javascript">
{   
+
var character = getObj("character", "-JMGkBaMgMWiQdNDwjjS");
  name: "",  
+
character.get("bio", function(bio) {
  bio: "",   
+
    log(bio); //do something with the character bio here.
  gmnotes: "",  
+
});</pre>
  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>
+
  
 +
You can set the value of these fields as normal. Note that there is currently (as at 2016/05/09) a bug with these asynchronous fields, whereby setting them by passing values to createObj fails quietly, leaving the object in a strange state. You should only set these values using .set until this issue is resolved. Details on the [https://app.roll20.net/forum/post/3345763/async-notes-slash-gmnotes-dont-work-immediately-after-creation forum]. There is also a bug (as of 2016/11/05) where attempting to set both the notes and gmnotes properties in the same set() call results in the second property in the call being set erroneously. Details on the [https://app.roll20.net/forum/post/4206469/api-bug-setting-handout-gmnotes-at-the-same-time-as-notes-gives-random-large-integer-or-blank-string/?pageforid=4206469#post-4206469 forum].
 +
 +
Setting the gmnotes does not update the object, only setting notes does - so while the presentation order is notes > gmnotes, it is better to reverse this update order so any notes updates are set asynchronously after any call to set gmnotes, [https://app.roll20.net/forum/post/9607011/help-handout-gm-notes-updating-through-api-dot-dot-dot-with-last-change-dot-dot-dot-sometimes/?pageforid=9607878#post-9607878 which will update both visually].
 +
 +
 +
===== Async/Await solution =====
 +
Alternatively, you can use modern ES6 javascript Async/Await to streamline the getting of these properties. The below function can be added to any script to provide a quick way to access these properties.
  
===Attribute===
 
 
<pre data-language="javascript">
 
<pre data-language="javascript">
{  
+
/**
  name: "Untitled",   
+
* Gets the blob info from roll20 objects asynchronously
  current: "",   
+
* @param {string} prop - the property to get
  max: "",  
+
* @param {Roll20 Object} obj - the Roll20 object to get the prop from
  _id: "",  
+
* @returns {Promise<string>} - The contents of the blob.
  _type: "attribute",  
+
*/
  _characterid: "" 
+
const getNotes = function (prop,obj) {
}
+
    return new Promise((resolve, reject) => {
</pre>
+
        obj.get(prop, (p) => {
 +
            resolve(p);
 +
        });
 +
    });
 +
};</pre>
  
 +
To use this function, you will need to write an Async function:
  
===Ability===
 
 
<pre data-language="javascript">
 
<pre data-language="javascript">
{  
+
const myFunc = async (charObj) => {
   name: "Untitled_Ability",  
+
   const charBio = await getNotes('bio',charObj);
   description: "",   
+
   // Do something with the bio content
  action: "",   
+
};</pre>
  _id: "",   
+
  _characterid: "",   
+
  _type: "ability" 
+
}
+
</pre>
+
  
 +
You can use this function to get any of the async text values:
  
===Handout===
+
* bio and gmnotes on characters
 +
* gmnotes and notes on handouts
 +
 
 +
Simply pass the property you want as the first argument and the object that you want to get it from as the second argument.
 +
 
 +
=== Macro ===
 +
See also: [[Macro]]
 +
 
 +
{| class="wikitable"
 +
|-
 +
! Property
 +
! Default Value
 +
! Notes
 +
|-
 +
| _id
 +
|
 +
| A unique ID for this object. Globally unique across all objects in this game. 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.
 +
 
 +
'''All Players''' is represented by having 'all' in the list.
 +
|-
 +
| istokenaction
 +
| false
 +
| Is this macro a token action that should show up when tokens are selected?
 +
|}
 +
 
 +
=== [[Roll Table|Rollable Table]] ===
 +
 
 +
{| class="wikitable"
 +
|-
 +
! Property
 +
! Default Value
 +
! Notes
 +
|-
 +
| _id
 +
|
 +
| A unique ID for this object. Globally unique across all objects in this game. 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 ====
 +
 
 +
{| class="wikitable"
 +
|-
 +
! Property
 +
! Default Value
 +
! Notes
 +
|-
 +
| _id
 +
|
 +
| A unique ID for this object. Globally unique across all objects in this game. 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. See the note about avatar and imgsrc restrictions below.
 +
|-
 +
| 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.
 +
|}
 +
 
 +
=== Deck ===
 +
 
 +
Note there are helper API methods to "draw", "deal", or "shuffle" cards from the '''[[Deck]]'''. See [https://app.roll20.net/forum/post/6223396/slug%7D API Upate forum post from March 2018].
 +
 
 +
{| class="wikitable"
 +
|-
 +
! Property
 +
! Default Value
 +
! Notes
 +
|-
 +
| _id
 +
| ""
 +
| id of the deck
 +
|-
 +
| _type
 +
| "deck"
 +
|   
 +
|-
 +
| name
 +
| ""
 +
| name of the deck
 +
|-
 +
| _currentDeck
 +
| ""
 +
| a comma-delimited list of cards which are currently in the deck (including those which have been played to the tabletop/hands). Changes when the deck is shuffled.
 +
|-
 +
| _currentIndex
 +
| -1
 +
| the current index of our place in the deck, 'what card will be drawn next?'
 +
|-
 +
| _currentCardShown
 +
| true
 +
| show the current card on top of the deck
 +
|-
 +
| showplayers
 +
| true
 +
| show the deck to the players
 +
|-
 +
| playerscandraw
 +
| true
 +
| can players draw cards?
 +
|-
 +
| avatar
 +
| ""
 +
| the 'back' of the cards for this deck
 +
|-
 +
| shown
 +
| false
 +
| show the deck on the gameboard (is the deck currently visible?)
 +
|-
 +
| players_seenumcards
 +
| true
 +
| can players see the number of cards in other player's hands?
 +
|-
 +
| players_seefrontofcards
 +
| false
 +
| can players see the fronts of cards when looking in other player's hands?
 +
|-
 +
| gm_seenumcards
 +
| true
 +
| can the GM see the number of cards in each player's hand?
 +
|-
 +
| gm_seefrontofcards
 +
| false
 +
| can the GM see the fronts of cards when looking in each player's hand?
 +
|-
 +
| infinitecards
 +
| false
 +
| are there an 'infinite' number of cards in this deck?
 +
|-
 +
| _cardSequencer
 +
| -1
 +
| internally used to advance the deck when drawing cards.
 +
|-
 +
| cardsplayed
 +
| "faceup"
 +
| how are cards from this deck played to the tabletop? 'faceup' or 'facedown'.
 +
|-
 +
| defaultheight
 +
| ""
 +
| what's the default height for cards played to the tabletop?
 +
|-
 +
| defaultwidth
 +
| ""
 +
|
 +
|-
 +
| discardpilemode
 +
| "none"
 +
| what type of discard pile does this deck have? 'none' = no discard pile, 'choosebacks' = allow players to see backs of cards and choose one, 'choosefronts' = see fronts and choose, 'drawtop' = draw the most recently discarded card, 'drawbottom' = draw the oldest discarded card.
 +
|-
 +
| _discardPile
 +
| ""
 +
| what's the current discard pile for this deck? comma-delimited list of cards. These are cards which have been removed from play and will not be put back into the deck on a shuffle until a recall is performed.
 +
|-
 +
| removedcardsmode
 +
| 'choosefronts'
 +
|
 +
|-
 +
| removedcards
 +
| 'none'
 +
|
 +
|}
 +
 
 +
==== Card ====
 +
See Also: [[Cards]]
 +
{| class="wikitable"
 +
|-
 +
! Property
 +
! Default Value
 +
! Notes
 +
|-
 +
|    name
 +
| ""
 +
| Name of the card
 +
|-
 +
|    avatar
 +
| ""
 +
| Front of the card
 +
|-
 +
|    _deckid
 +
| ""
 +
| ID of the deck 
 +
|-
 +
|    _type
 +
| "card"
 +
|   
 +
|-
 +
|    _id
 +
| ""
 +
|
 +
|-
 +
| is_removed
 +
| "false"
 +
|
 +
|-
 +
| tooltip
 +
| ""
 +
| tooltip text
 +
|-
 +
| card_back
 +
| ""
 +
| Back of the card
 +
|}
 +
 
 +
==== Hand ====
 +
Note that each player should only have ONE hand.
 +
 
 +
{| class="wikitable"
 +
|-
 +
! Property
 +
! Default Value
 +
! Notes
 +
|-
 +
|    currentHand
 +
| ""
 +
| comma-delimited list of cards currently in the hand.  Note that this is no longer read only.  Ideally, it should only be adjusted with the card deck functions.
 +
|-
 +
|    _type
 +
| "hand"
 +
|
 +
|-
 +
|    _parentid
 +
| ""
 +
| ID of the player to whom the hand belongs
 +
|-
 +
|    _id
 +
| ""
 +
|
 +
|-
 +
|    currentView
 +
| "bydeck"
 +
| when player opens hand, is the view 'bydeck' or 'bycard'?
 +
|}
 +
 
 +
=== Jukebox Track ===
 +
See also: {{Jukebox}}
 +
{| class="wikitable"
 +
|-
 +
! Property
 +
! Default Value
 +
! Notes
 +
|-
 +
| _id
 +
|
 +
| A unique ID for this object. Globally unique across all objects in this game. Read-only.
 +
|-
 +
| _type
 +
| "jukeboxtrack"
 +
| Can be used to identify the object type or search for the object. Read-only.
 +
|-
 +
| playing
 +
| false
 +
| Boolean used to determine whether or not the track is playing. Setting this to "true" and softstop to "false" plays a track.
 +
|-
 +
| softstop
 +
| false
 +
| Boolean used to determine whether or not a non-looped track has finished at least once. This must be set to "false" to ensure that a track will play.
 +
|-
 +
| title
 +
| ""
 +
| The visible label for the track in the jukebox tab.
 +
|-
 +
| volume
 +
| 30
 +
| The volume level of the track. Note that this must be set to an integer (not a string), or you may break functionality. Values from 0-100 (percentage).
 +
|-
 +
| loop
 +
| false
 +
| Should the track be looped? Set to true if so.
 +
|}
 +
 
 +
 
 +
=== [[Custom FX]] ===
 +
 
 +
{| class="wikitable"
 +
|-
 +
! Property
 +
! Default Value
 +
! Notes
 +
|-
 +
| _id
 +
|
 +
| A unique ID for this object. Globally unique across all objects in this game. Read-only.
 +
|-
 +
| _type
 +
| "custfx"
 +
| Can be used to identify the object type or search for the object. Read-only.
 +
|-
 +
| name
 +
| ""
 +
| The visible name for the FX in the FX Listing.
 +
|-
 +
| definition
 +
| {}
 +
| Javascript object describing the FX.
 +
|}
 +
 
 +
=== [[Door]] ===
 +
Note: Window and Door use an inverted axis compared to other types of objects. For instance, a top variable that would be 100 for another object is y -100 for window or door.
 +
 
 +
{| class="wikitable"
 +
|-
 +
! Property
 +
! Default Value
 +
! Notes
 +
|-
 +
| _id
 +
|
 +
| A unique ID for this object. Globally unique across all objects in this game. Read-only.
 +
|-
 +
| _type
 +
| "door"
 +
| Read-only
 +
|-
 +
| color
 +
|
 +
| A hexadecimal color of the path.
 +
|-
 +
| x
 +
| 0
 +
| Coordinate center of the door on the x axis.
 +
|-
 +
| y
 +
| 0
 +
| Coordinate center of the door on the y axis.
 +
|-
 +
| isOpen
 +
| false
 +
| Determines whether a player can move through this door.
 +
|-
 +
| isLocked
 +
| false
 +
| Prevents players from being able to interact with the door.
 +
|-
 +
| isSecret
 +
| false
 +
| Removes a door icon from player view and functions as a barrier.
 +
|-
 +
| path
 +
|
 +
| Represented as two handles (handle0 and handle1) each with x and y coordinates.
 +
|}
 +
 
 +
=== [[Window]] ===
 +
Note: Window and Door use an inverted axis compared to other types of objects. For instance, a top variable that would be 100 for another object is y -100 for window or door.
 +
 
 +
{| class="wikitable"
 +
|-
 +
! Property
 +
! Default Value
 +
! Notes
 +
|-
 +
| _id
 +
|
 +
| A unique ID for this object. Globally unique across all objects in this game. Read-only.
 +
|-
 +
| _type
 +
| "window"
 +
| Read-only.
 +
|-
 +
| color
 +
|
 +
| A hexadecimal color of the path.
 +
|-
 +
| x
 +
| 0
 +
| Coordinate center of the door on the x axis.
 +
|-
 +
| y
 +
| 0
 +
| Coordinate center of the door on the y axis.
 +
|-
 +
| isOpen
 +
| false
 +
| Determines whether a player can move through this window.
 +
|-
 +
| isLocked
 +
| false
 +
| Prevents players from being able to interact with the window.
 +
|-
 +
| path
 +
|
 +
| Represented as two handles (handle0 and handle1) each with x and y coordinates.
 +
|-
 +
| isSecret
 +
| false
 +
| Removes a door icon from player view and functions as a barrier.
 +
|-
 +
| path
 +
|
 +
| Represented as two handles (handle0 and handle1) each with x and y coordinates.
 +
|}
 +
 
 +
====Example Usage====
 
<pre data-language="javascript">
 
<pre data-language="javascript">
{  
+
on('chat:message', function(msg) {
  name: "Mysterious Note",  
+
    if (msg.type === 'api' && msg.content === '!cw') {
  notes: "",  
+
        const currentPageID = Campaign().get('playerpageid');
  inplayerjournals: "", //Comma-delimited list of Player IDs who can see this Handout in their journal. The GM can always see the Handout. 
+
        const win = createObj('window', {
  archived: false,  
+
            x: 70,
  controlledby: "", //Comma-delimited list of Player IDs who can control (and edit) this Handout. 
+
            y: -70,
  _type: "handout",  
+
            pageid: currentPageID,
  _id: ""
+
            path: {
}
+
        handle0: {
</pre>
+
        x: -70,
 +
        y: 0,
 +
        },
 +
        handle1: {
 +
        x: 35,
 +
        y: 0,
 +
        },
 +
        },
 +
            color: '#000000'
 +
        });
 +
    }
  
==Creating Objects==
+
    if (msg.type === 'api' && msg.content === '!mw') {
 +
        const win = getObj('window', '-NG38yUgghBBoV8YR0y1');
 +
        win.set({
 +
          x: 240,
 +
          y: -139
 +
        });
 +
    }
  
{{mbox | text= Note: Currently only '''characters, handouts, attributes, and abilities''' can be created. Other objects will be supported soon.}}
+
    if (msg.type === 'api' && msg.content === '!dw') {
 +
        const win = getObj('window', '-NG38yUgghBBoV8YR0y1');
 +
        win.remove();
 +
    }
 +
});
 +
</pre>
  
 +
== Creating Objects ==
  
 
'''createObj(type, attributes)'''
 
'''createObj(type, attributes)'''
  
You can create a new object in the game using the <code>createObj</code> function. You must pass in the type of the object (one of the valid <code>_type</code> properties from the objects list above), as well as a an <code>attributes</code> 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 <code>characterid</code> 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.
+
''Note: currently you can create {{creatable objects}} objects.''
 +
 
 +
You can create a new object in the game using the <code>createObj</code> function. You must pass in the type of the object (one of the valid <code>_type</code> properties from the objects list above), as well as an <code>attributes</code> 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, graphics, texts, and paths belong to pages, etc.), you must pass in the ID of the parent in the list of properties (for example, you must include the <code>characterid</code> 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. The one exception to this is when creating a Path, you must include the 'path' property, but it cannot be modified once the path is initially created.
  
 
<code>createObj</code> will return the new object, so you can continue working with it.
 
<code>createObj</code> will return the new object, so you can continue working with it.
Line 336: Line 1,476:
 
</pre>
 
</pre>
  
==Global Objects==
+
== Deleting Objects ==
 +
 
 +
'''object.remove()'''
 +
 
 +
You can delete existing game objects using the <code>.remove()</code> function. The .remove() function works on {{creatable objects}} objects. You call the function directly on the object. For example, <code>mycharacter.remove();</code>.
 +
 
 +
=== Removing Repeating Section Attributes ===
 +
 
 +
As noted above, attribute objects can be removed using this method. To remove items from a repeating section of a Character Sheet, you will need to collect the attributes for that section and remove them all.
 +
 
 +
<pre data-language="javascript">
 +
function deleteRepeatingSectionRow(rowid, characterid) {
 +
  const regex = new RegExp(`^repeating_.*?_${rowid}_.*?$`);
 +
  const attrsInRow = filterObjs(function(obj) {
 +
    if (obj.get('type') !== 'attribute' || obj.get('characterid') !== characterid) return false;
 +
    return regex.test(obj.get('name'));
 +
  });
 +
  _.each(attrsInRow, function (attribute) {
 +
    attribute.remove();
 +
  });
 +
}
 +
</pre>
 +
 
 +
== 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.
  
'''<code>Campaign()</code>''' (function)
+
===Campaign() (function)===
  
 
A function which returns the <code>Campaign</code> 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 <code>Campaign().get("playerpageid")</code>.
 
A function which returns the <code>Campaign</code> 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 <code>Campaign().get("playerpageid")</code>.
  
'''<code>state</code>'''
+
===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 <code>state</code> object is persisted between play sessions, so you can use this object to store long-term information about the state of the game.
+
The <code>state</code> variable is an object in the global scope which is accessible to all scripts running in a game. You can access the <code>state</code> object from any function or callback at any time just by using the global variable named <code>state</code>.   Additionally, the <code>state</code> object is persisted between executions of the [[API:Sandbox_Model|Sandbox]], so you can use it to store information you want to have in future runs of your script.
  
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.
+
'''Note:''' You should use the state object to store information that is only needed by the API, since it is not sent to player computers and does not make your game file larger.  Store values that are needed in-game in the Roll20 objects' properties.
  
 +
====Storable Types====
 +
The <code>state</code> object is only capable of persisting simple data types, as supported by the [http://json.org JSON] standard.
 +
 +
{| class="wikitable"
 +
|-
 +
! Type !! Examples !! Description
 +
|-
 +
| Boolean || <code>true</code> <code>false</code> || The value <code>true</code> or <code>false</code>.
 +
|-
 +
| Number || <code>123.5</code> <code>10</code> <code>1.23e20</code>  || Any number format supported by Javascript.  Floating-Point or Integer.
 +
|-
 +
| String || <code>'Hello Fantasy'</code> <code>"oh, and World"</code>  || A standard string of text.
 +
|-
 +
| Array || <code>[ 1, 2, 3, 4 ]</code> <code>[ 'A','B','C']</code><code>[1, 2, ['bob', 3], 10, 2.5]</code>  || An ordered collection of any of the types, including other arrays.
 +
|-
 +
| Object || <code>{ key: 1, value: 'roll20' }</code> || A simple key/value object with string keys and any of the types as a value, including other objects.
 +
|}
 +
 +
'''Warning:''' While functions will appear to work when stored in the state initially, they will disappear the first time the <code>state</code> is restored from persistence, such as on a sandbox restart. 
 +
* '''Note:''' This includes Roll20 objects which you get from events or the functions <code>findObjs()</code>, <code>getObj()</code>, <code>filterObjs()</code>, <code>createObj()</code>, etc.
 +
 +
====Important Reminders====
 +
The <code>state</code> object is shared between all of the scripts in a sandbox.  To avoid breaking other scripts, it is important to follow a few simple guidelines:
 +
* '''''Never''''' assign directly to the root <code>state</code> object.
 
<pre data-language="javascript">
 
<pre data-language="javascript">
state.numTimesTokensMoved = 0;
+
state = { break: 'all the things' };  // NEVER DO THIS!!!
on("change:graphic", function(obj) {  
+
</pre>
  state.numTimesTokensMoved = state.numTimesTokensMoved + 1;
+
 
 +
* '''''Avoid''''' using local variables named <code>state</code> in your scripts. While this will work, it will be confusing to later users of your scripts and could cause issues if the code is carelessly edited.
 +
<pre data-language="javascript">
 +
function turn(){
 +
    var state = Campaign().get('turnorder');  // Bad Practice, Avoid it!
 +
    // ...
 +
}
 +
</pre>
 +
 
 +
* '''''Always''''' place your properties beneath at least one namespace property.  Be sure to use a sufficiently descriptive namespace property.  Avoid names like <code>script</code> or <code>settings</code>.  It's best to either use the name of your module or your own name or handle.
 +
<pre data-language="javascript">
 +
if( ! state.MyModuleNamespace ) {
 +
    state.MyModuleNamespace = { module: 'my module', ok: 'this is fine!', count: 0 };
 +
}
 +
state.MyModuleNamespace.count++;
 +
</pre>
 +
 
 +
====Example Usage====
 +
This is a working example that uses the <code>state</code> object appropriately.
 +
 
 +
<pre data-language="javascript">
 +
on('ready',function() {
 +
    "use strict";
 +
 
 +
    // Check if the namespaced property exists, creating it if it doesn't
 +
    if( ! state.MyModuleNS ) {
 +
        state.MyModuleNS = {
 +
            version: 1.0,
 +
            config: {
 +
                color1: '#ff0000',
 +
                color2: '#0000ff'
 +
            },
 +
            count: 0
 +
        };
 +
    }
 +
 
 +
    // Using the state properties to configure a message to the chat.  
 +
    sendChat(
 +
        'Test Module',
 +
        '<span style="color: '+state.MyModuleNS.config.color1+';">'+
 +
            'State test'+
 +
        '</span> '+
 +
        '<span style="color: '+state.MyModuleNS.config.color2+';">'+
 +
            'Script v'+state.MyModuleNS.version+' started '+(++state.MyModuleNS.count)+' times!'+
 +
        '</span>'
 +
    );
 
});
 
});
 
</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.
  
'''getObj(type, id)'''
+
===getObj(type, id)===
  
 
This function gets a single object if pass in the <code>_type</code> of the object and the <code>_id</code>. 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.
 
This function gets a single object if pass in the <code>_type</code> of the object and the <code>_id</code>. 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.
Line 373: Line 1,605:
  
  
'''findObjs(attrs)'''
+
===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.
+
Pass this function a list of attributes, and it will return all objects that match as an array. Note that this operates on all objects of all types across all pages -- so you probably want to include at least a filter for <code>_type</code> and <code>_pageid</code> if you're working with tabletop objects.
 
<pre data-language="javascript">
 
<pre data-language="javascript">
 
var currentPageGraphics = findObjs({                               
 
var currentPageGraphics = findObjs({                               
Line 398: Line 1,630:
 
</pre>
 
</pre>
  
 +
===filterObjs(callback)===
  
'''filterObjs(callback)'''
+
Will execute the provided callback function on each object, and if the callback returns true, the object will be included in the result array. Currently, it is inadvisable to use <code>filterObjs()</code> for most purposes – due to the fact that <code>findObjs()</code> has some built-in indexing for better executing speed, it is almost always better to use <code>findObjs()</code> to get objects of the desired type first, then filter them using the native <code>.filter()</code> method for arrays.
 
+
Will execute the provided callback funtion on each object, and if the callback returns true, the object will be included in the result array.
+
 
<pre data-language="javascript">
 
<pre data-language="javascript">
 
var results = filterObjs(function(obj) {     
 
var results = filterObjs(function(obj) {     
Line 410: Line 1,641:
 
</pre>
 
</pre>
  
 +
===getAllObjs()===
  
'''getAllObjs()'''
+
Returns an array of all the objects in the Game (all types). Equivalent to calling filterObjs and just returning <code>true</code> for every object.
  
Returns an array of all the objects in the Campaign (all types). Equivalent to calling filterObjs and just returning <code>true</code> for every object.
+
 
 +
===getAttrByName(character_id, attribute_name, value_type)===
 +
 
 +
Gets the value of an attribute, using the default value from the character sheet if the attribute is not present. <code>value_type</code> is an optional parameter, which you can use to specify "current" or "max".
 +
 
 +
<code>getAttrByName</code> will ''only'' get the value of the attribute, not the attribute object itself. If you wish to reference properties of the attribute other than "current" or "max", or if you wish to change properties of the attribute, you must use one of the other functions above, such as <code>findObjs</code>.
 +
 
 +
For [[Repeating Sections]], you can use the format <code>repeating_section_$n_attribute</code>, where <code>n</code> is the repeating row number([[RowIndex]]) (starting with zero). For example, <code>repeating_spells_$2_name</code> will return the value of <code>name</code> from the third row of <code>repeating_spells</code>.
 +
 
 +
Instead of RowIndex, [[RowID]] can be used instead for referencing(?)
 +
 
 +
You can achieve behavior equivalent to <code>getAttrByName</code>with the following:
 +
<pre data-language="javascript">
 +
// current and max are completely dependent on the attribute and game system
 +
// in question; there is no function available for determining them automatically
 +
function myGetAttrByName(character_id,
 +
                        attribute_name,
 +
                        attribute_default_current,
 +
                        attribute_default_max,
 +
                        value_type) {
 +
    attribute_default_current = attribute_default_current || '';
 +
    attribute_default_max = attribute_default_max || '';
 +
    value_type = value_type || 'current';
 +
 
 +
    var attribute = findObjs({
 +
        type: 'attribute',
 +
        characterid: character_id,
 +
        name: attribute_name
 +
    }, {caseInsensitive: true})[0];
 +
    if (!attribute) {
 +
        attribute = createObj('attribute', {
 +
            characterid: character_id,
 +
            name: attribute_name,
 +
            current: attribute_default_current,
 +
            max: attribute_default_max
 +
        });
 +
    }
 +
 
 +
    if (value_type == 'max') {
 +
        return attribute.get('max');
 +
    } else {
 +
        return attribute.get('current');
 +
    }
 +
}
 +
</pre>
 +
[[Category:API Development]]
 +
[[Category:Repeating Section]]

Latest revision as of 15:07, 10 January 2024

Attention: This page is community-maintained. For the official Roll20 version of this article, see the Help Center for assistance: Here .

[edit] 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).

Contents

[edit] Campaign

Property Default Value Notes
_id "root" A unique ID for this object. Globally unique across all objects in this game. 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 t Turn 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. Players see this page by default, unless overridden by playerspecificpages below.
playerspecificpages false An object (NOT JSON STRING) of the format: {"player1_id": "page_id", "player2_id": "page_id" ... } Any player set to a page in this object will override the playerpageid.
_journalfolder "" A JSON string which contains data about the folder structure of the game. Read-only.
_jukeboxfolder "" A JSON string which contains data about the jukebox playlist structure of the game. Read-only.
token_markers "" A stringified JSON array containing an object for each token marker currently in the game

[edit] Turn Order

The turn order is a JSON string representing the current turn order listing seen on the t Turn Tracker. 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. You must include the Page ID in _pageid property for each item in the turnorder when added or edited.

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".
     "_pageid": Campaign().get("playerpageid")
    },
    {
     "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.
     "_pageid": Campaign().get("playerpageid")
    }
]

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"
    _pageid: Campaign().get("playerpageid")
});
Campaign().set("turnorder", JSON.stringify(turnorder));

[edit] Player

See also: Player

Property Default Value Notes
_id A unique ID for the player (referred to as "player ID" in other parts of the guide). Globally unique across all objects in this game. Read-only. Players will have new player ID for each game they are part of, so does not persist between games. See roll20id below for the permanent ID unique to each account.
_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. Also called roll20id. Read-only.
_displayname "" The player's current display name. May be changed from the user's My Settings-tab. Read-only.
_online false Read-only.
_lastpage "" The page id of the last page the player viewed as a GM. This property is not updated for players or GMs that have joined as players. Read-only.
_macrobar "" Comma-delimited string of the macros in the player's Macro Bar. Read-only.
speakingas "" 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.

[edit] Page

See Also: Page Toolbar

Property Default Value Notes
_id A unique ID for this object. Globally unique across all objects in this game. 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.
width 25 Width in units.
height 25 Height in units.
background_color "#FFFFFF" Hexadecimal color of the map background.
archived false Whether the page has been put into archive storage.
jukeboxtrigger Controls the Page Play on Load. Options include ‘nonestopall’ or the id-of-the-track
showdarkness false Show Fog of War on the map.
fog_opacity 0.35 Opacity of the Fog of War for the GM.
Grid grid-related keys
showgrid true Show the grid on the map.
grid_opacity 0.5 Opacity of the grid lines.
gridcolor "#C0C0C0" Hexadecimal color of the grid lines.
grid_type "square" One of "square", "hex", "hexr" (hex corresponds to Hex(V), and hexr corresponds to Hex(H)), "dimetric", or "isometric".
gridlabels false Show grid labels for hexagonal grid.
snapping_increment 1 Size of a grid space in units.
scale_number 5 The distance of one unit.
scale_units "ft" The type of units to use for the scale.
diagonaltype "foure" One of "foure", "pythagorean" (Euclidean), "threefive", or "manhattan".
Dynamic Lighting keys for Updated DL
dynamic_lighting_enabled Boolean Toggles updated dynamic lighting for the page.
daylight_mode_enabled Boolean Toggles daylight mode for the page. This should not be turned on if dynamic_lighting_enabled is not turned on.
daylightModeOpacity use example(Forum)
explorer_mode String Toggles explorer mode for the page. This should not be turned on if dynamic_lighting_enabled is not turned on.

Use the strings ”basic” to turn on or ”off” to turn off.

force_lighting_refresh Boolean Triggers a refresh of all token lighting/vision on a page. Can be used in a single call after putting multiple tokens onto a page. (Will be deprecated in the coming months!)
fog_opacity Boolean Opacity of the fog of war for the GM.
lightupdatedrop Boolean Only update Dynamic Lighting when an object is dropped.
Legacy DL keys for Legacy Dynamic Lighting. Some are still used with UDL
showlighting false Use dynamic lighting.
lightupdatedrop false Only update Dynamic Lighting when an object is dropped.
lightenforcelos false Enforce Line of Sight for objects.
lightrestrictmove false Don't allow objects that have sight to move through Dynamic Lighting walls.
lightglobalillum false If true anywhere a token can "see" it is assumed there is bright light present.

[edit] Path

Main Page: API:Objects/Path

For more information on the _path data format, see: Objects/Path

Property Default Value Notes
_id A unique ID for this object. Globally unique across all objects in this game. 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 A JSON string describing the lines in the path. Read-only. See Path Property below for more information.
fill "transparent" Fill color. Use the string "transparent" or a hex color as a string, for example "#000000"
stroke "#000000" Stroke (border) color.
rotation 0 Rotation (in degrees).
layer "" Current b 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 between tokens.
stroke_width 5 Width of the path's line in pixels.
width 0 Horizontal dimension of the path.
height 0 Vertical dimension of the path.
top 0 Y-coordinate for the center of the path
left 0 X-coordinate for the center of the path
scaleX 1 Horizontal scale factor for the path.
scaleY 1 Vertical scale factor for the path.
barrierType "wall" 'oneWay' or 'wall' . For creating One-Way Barrier.
oneWayReversed false or true . For One-Way Barrier. helpful in changing the direction the arrows are facing
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.

All Players is represented by having all in the list.

[edit] Text

Property Default Value Notes
_id A unique ID for this object. Globally unique across all objects in this game. 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 "Arial" If this is not set, when later changing the value of the "text" property the font_size will shrink to 8. Possible values (Case is not important):
  • "Arial"
  • "Patrick Hand"
  • "Contrail One"
  • "Shadows Into Light"
  • "Candal"
  • "Tahoma"
  • "Nunito"
  • "Merriweather"
  • "Anton"
  • "Rye"
  • "IM Fell DW Pica"
  • "Montserrat"
  • "Goblin One"
  • "Della Respira"
  • "Crimson Text"
  • "Kaushan Script"

Specifying an invalid name results in an unnamed, monospaced serif font being used.

layer "" gmlayer, objects, map, or walls.
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.

All Players is represented by having 'all' in the list.

[edit] Graphic (Token/Map/Card/Etc.)

For the new UDL support for tokens, see the Help Center's API UDL Support.


[edit] General

Property Default Value Notes
_id A unique ID for this object. Globally unique across all objects in this game. 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.
imgsrc The URL of the graphic's image. More details under #imgsrc and avatar property restrictions
represents ID of the character this token represents.
left 0 Number of pixels from the left edge of the map to the center of the graphic.
top 0 Number of pixels from the top edge of the map to the center of the graphic.
width 0 Width of the graphic, in pixels.
height 0 Height of the graphic, in pixels.
rotation 0 The orientation of the token in degrees.
layer "" gmlayer, objects, map, or walls
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.
tooltip "" The text saved on a token's tootip. (May 2022): API can exceed the 150 character limit when writing to the tooltip.
show_tooltip false (toggle doesn't work yet(2021-10-05)) show or hide the token's tooltip.
controlledby "" Comma-delimited list of player IDs who can control the graphic. Controlling players may delete the graphic. If the graphic was created by a player, that player is automatically included in the list.

All Players is represented by having 'all' in the list.

bar1_link Set to an ID if Bar 1 is linked to a character.
bar2_link
bar3_link
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
bar_location Adjusts the location of the token bars. Options include overlap_top, overlap_bottom, bottom
compact_bar Adjusts whether the bar is compact or not. Other option is compact.
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 true Allow controlling players to edit the token's name. Also shows the nameplate to controlling players, even if showplayers_name is false.
playersedit_bar1 true 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 true
playersedit_bar3 true
playersedit_aura1 true 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 true
lastmove "" The last move of the token. It's a comma-delimited list of coordinates. For example, 300,400 would mean that the token started its last move at left=300, top=400. It's always assumed that the current top + left values of the token are the "ending point" of the last move. Waypoints are indicated by multiple sets of coordinates. For example, 300,400,350,450,400,500 would indicate that the token started at left=300, top=400, then set a waypoint at left=350, top=450, another waypoint at left=400, top=500, and then finished the move at its current top + left coordinates.
sides "" A list of the image URLs for a rollable table token (Multi-sided Token), delimited by pipes |
currentSide 0 The index of the current image displayed by a rollable table token (multi-sided token)
lockMovement false (boolean) If the token's movement is locked or not. A locked token can still be moved by API commands. See also: Token Lock

[edit] Dynamic Lighting

Property Description Type
has_bright_light_vision Toggles vision for the token. Boolean
has_night_vision Toggles night vision for the token. Boolean
night_vision_distance Sets the range of night vision for the token. Integer
emits_bright_light Toggles bright light for the token. Boolean
bright_light_distance Sets the range of the amount of bright light emitting from a token. Integer
emits_low_light Toggles low light for the token. This would be useful for a torch or a source with a low amount of light. Use the booleans true to turn on or false to turn off. Boolean
dim_light_opacity Sets the "opacity" of the dim light. Lower values provide dimmer light, higher values yield brighter dim light. Default on new graphics is 0.75. Decimal from 0.0 to 1.0
low_light_distance Sets the range of the amount of low light emitting from a token. When setting this value, you must include any Bright Light Distance you have set. The reason for this is because Low Light Distance is calculated from the center of the token. So if you have set Bright Light Distance to 10, and you would like an additional 10 feet of Low Light Distance, the value of low_light_distance must be 20. Integer
light_sensitivity_multiplier Multiplier on the effectiveness of light sources. A multiplier of 200 would allow the token to see twice as far as a token with a multiplier of 100, with the same light source. Integer
night_vision_effect Changes the Night Vision Effect. Other options include Dimming and Nocturnal String
has_limit_field_of_vision Toggles limit field of vision for the token. Boolean
limit_field_of_vision_center Sets the value for where the center of the field of vision starts. Integer
limit_field_of_vision_total Set the value for the total size of the field of vision. Integer
has_limit_field_of_night_vision Toggles limit field of night vision for the token. Boolean
limit_field_of_night_vision_center Sets the value for where the center of the field of night vision starts. Integer
limit_field_of_night_vision_total Set the value for the total size of the field of night vision. Integer
has_directional_bright_light Toggles directional bright light for the token. Boolean
directional_bright_light_center Sets the value for where the center of the field of bright light starts. Integer
directional_bright_light_total Set the value for the total size of the field of bright light. Integer
has_directional_dim_light Toggles directional low light for the token. Boolean
directional_dim_light_center Sets the value for where the center of the field of low light starts. Integer
directional_dim_light_total Set the value for the total size of the field of low light. Integer
lightColor Sets color of light. (e.g. #FF0000 for red) hexadecimal

[edit] Legacy Dynamic Lighting

Property Default Value Notes
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.
light_hassight false The light has "sight" for controlling players for the purposes of the "Enforce Line of Sight" setting.
light_angle "360" Angle (in degrees) of the light's angle. For example, 180 means the light would show only for the front "half" of the "field of vision".
light_losangle "360" Angle (in degrees) of the field of vision of the graphic (assuming that light_hassight is set to true)
light_multiplier "1" Multiplier on the effectiveness of light sources. A multiplier of two would allow the token to see twice as far as a token with a multiplier of one, with the same light source.
adv_fow_view_distance "" The radius around a token where Advanced Fog of War is revealed.

[edit] 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.

The statusmarkers property of the Graphic object is (still in 2021?) 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 and will never 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"


[edit] imgsrc and avatar property restrictions

While you can now edit the imgsrc and avatar(Character) properties, in order to provide safety to all Roll20's users we have put the following restrictions in place for those properties:

  • You must use an image file that has been uploaded to your Roll20 Library -- not an external site (such as Imgur), and not the Roll20 Marketplace. It will begin with https://s3.amazonaws.com/files.d20.io/images/ for images uploaded to the Main server, or https://s3.amazonaws.com/files.staging.d20.io/images/ for images uploaded to the Dev Server. You can view an image's source URL using the developer tools of your browser.
  • You must include the query string in the URL -- for example https://s3.amazonaws.com/files.staging.d20.io/images/123456/med.png?12345678, not just https://s3.amazonaws.com/files.staging.d20.io/images/123456/med.png
  • For Graphic objects (tokens), you must use the "thumb" size of the image. It should look like https://s3.amazonaws.com/files.staging.d20.io/images/123456/thumb.png?12345678.


In the future we may add a tool so that images can be uploaded specifically for use with API scripts, but for now just use images uploaded to your own library. Note: If you delete an image from your library, it will be removed from all Games which use that image, including Games using your API scripts.

[edit] Journal

Things in the N Journal, i.e Characters & Handouts.

[edit] Character

See also the imgsrc and avatar property restrictions

Property Default Value Notes
_id A unique ID for this object. Globally unique across all objects in this game. 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. See the note about avatar and imgsrc restrictions below.
name ""
bio "" The character's biography. See the note below about accessing the Notes, GMNotes, and bio fields.
gmnotes "" Notes on the character only viewable by the GM. See the note below about accessing the Notes, GMNotes, and bio fields.
archived false
inplayerjournals "" Comma-delimited list of player ID who can view this character. Use "all" to give all players the ability to view.

All Players is represented by having 'all' in the list.

controlledby "" Comma-delimited list of player IDs who can control and edit this character. Use "all" to give all players the ability to edit.

All Players is represented by having 'all' in the list.

_defaulttoken "" A JSON string that contains the data for the Character's default token if one is set. Note that this is a "blob" similar to "bio" and "notes", so you must pass a callback function to get(). Read-only.
[edit] Attribute
Property Default Value Notes
_id A unique ID for this object. Globally unique across all objects in this game. 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. Mandatory when using createObj.
name "Untitled"
current "" The current value of the attribute can be accessed in chat and macros with the syntax @{Character Name|Attribute Name} or in abilities with the syntax @{Attribute Name}.
max "" The max value of the attribute can be accessed in chat and macros with the syntax @{Character Name|Attribute Name|max} or in abilities with the syntax @{Attribute Name|max}.


Important: See the note below about working with Character Sheets for information on how Character Sheet default values affect the use of Attributes.

[edit] Ability
Property Default Value Notes
_id A unique ID for this object. Globally unique across all objects in this game. 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. Read-only. Mandatory when using createObj.
name "Untitled_Ability"
description "" The description does not appear in the character sheet interface.
action "" The text of the ability.
istokenaction false Is this ability a token action that should show up when tokens linked to its parent Character are selected?


[edit] Working with Character Sheets

The Character Sheets affects the usage of the Attributes object type, because the sheets have the capability of specifying a default value for each attribute on the sheet. However, if the attribute is set to the default value, there is not yet an actual Attribute object created in the game for that Character. We provide a convenience function which hides this complexity from you. You should use this function to get the value of an attribute going forward, especially if you know that a game is using a Character Sheet.

More about editing character sheets and how they work: Building Character Sheets

getAttrByName(character_id, attribute_name, value_type)

Simply specify the character's ID, the name (not ID) of the attribute (e.g. "HP" or "Str"), and then if you want the "current" or "max" for value_type. Here's an example:

var character = getObj("character", "-JMGkBaMgMWiQdNDwjjS");
getAttrByName(character.id, "str"); // the current value of str, for example "12"
getAttrByName(character.id, "str", "max"); //the max value of str, for example "[[floor(@{STR}/2-5)]]"

Note that fields which have auto-calculated values will return the formula rather than the result of the value. You can then pass that formula to sendChat() to use the dice engine to calculate the result for you automatically.

Be sure to also look at the Building Character Sheets documentation for more information on how they interact with the API.

getAttrByName will only get the value of the attribute, not the attribute object itself. If you wish to reference properties of the attribute other than "current" or "max", or if you wish to change properties of the attribute, you must use one of the other functions above, such as findObjs.

In the case that the requested attribute does not exist, getAttrByName() will return undefined.

[edit] Handout

Property Default Value Notes
_id A unique ID for this object. Globally unique across all objects in this game. 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. See the note about avatar and imgsrc restrictions below.
name "Mysterious Note"
notes "" Contains the text in the handout. See the note below about using Notes and GMNotes.
gmnotes "" Contains the text in the handout that only the GM sees. See the note below about using Notes and GMNotes.
inplayerjournals "" Comma-delimited list of player ID who can see this handout. Use "all" to display to all players.

All Players is represented by having 'all' in the list.

archived false
controlledby "" Comma-delimited list of player IDs who can control and edit this handout.

All Players is represented by having 'all' in the list.


Note: The API does not have access to the folder hierarchy. API created handouts will be placed at the root level.

[edit] Using the Notes, GMNotes, and Bio fields [Asynchronous]

In order to access the "notes", "gmnotes", or "bio" fields on Characters and Handouts, you must pass a callback function as the second argument to the get() function. Here's an example:

var character = getObj("character", "-JMGkBaMgMWiQdNDwjjS");
character.get("bio", function(bio) {
    log(bio); //do something with the character bio here.
});

You can set the value of these fields as normal. Note that there is currently (as at 2016/05/09) a bug with these asynchronous fields, whereby setting them by passing values to createObj fails quietly, leaving the object in a strange state. You should only set these values using .set until this issue is resolved. Details on the forum. There is also a bug (as of 2016/11/05) where attempting to set both the notes and gmnotes properties in the same set() call results in the second property in the call being set erroneously. Details on the forum.

Setting the gmnotes does not update the object, only setting notes does - so while the presentation order is notes > gmnotes, it is better to reverse this update order so any notes updates are set asynchronously after any call to set gmnotes, which will update both visually.


[edit] Async/Await solution

Alternatively, you can use modern ES6 javascript Async/Await to streamline the getting of these properties. The below function can be added to any script to provide a quick way to access these properties.

/**
 * Gets the blob info from roll20 objects asynchronously
 * @param {string} prop - the property to get
 * @param {Roll20 Object} obj - the Roll20 object to get the prop from
 * @returns {Promise<string>} - The contents of the blob.
 */
const getNotes = function (prop,obj) {
    return new Promise((resolve, reject) => {
        obj.get(prop, (p) => {
            resolve(p);
        });
    });
};

To use this function, you will need to write an Async function:

const myFunc = async (charObj) => {
  const charBio = await getNotes('bio',charObj);
  // Do something with the bio content
};

You can use this function to get any of the async text values:

  • bio and gmnotes on characters
  • gmnotes and notes on handouts

Simply pass the property you want as the first argument and the object that you want to get it from as the second argument.

[edit] Macro

See also: Macro

Property Default Value Notes
_id A unique ID for this object. Globally unique across all objects in this game. 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.

All Players is represented by having 'all' in the list.

istokenaction false Is this macro a token action that should show up when tokens are selected?

[edit] Rollable Table

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

[edit] Table Item

Property Default Value Notes
_id A unique ID for this object. Globally unique across all objects in this game. 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. See the note about avatar and imgsrc restrictions below.
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.

[edit] Deck

Note there are helper API methods to "draw", "deal", or "shuffle" cards from the Deck. See API Upate forum post from March 2018.

Property Default Value Notes
_id "" id of the deck
_type "deck"
name "" name of the deck
_currentDeck "" a comma-delimited list of cards which are currently in the deck (including those which have been played to the tabletop/hands). Changes when the deck is shuffled.
_currentIndex -1 the current index of our place in the deck, 'what card will be drawn next?'
_currentCardShown true show the current card on top of the deck
showplayers true show the deck to the players
playerscandraw true can players draw cards?
avatar "" the 'back' of the cards for this deck
shown false show the deck on the gameboard (is the deck currently visible?)
players_seenumcards true can players see the number of cards in other player's hands?
players_seefrontofcards false can players see the fronts of cards when looking in other player's hands?
gm_seenumcards true can the GM see the number of cards in each player's hand?
gm_seefrontofcards false can the GM see the fronts of cards when looking in each player's hand?
infinitecards false are there an 'infinite' number of cards in this deck?
_cardSequencer -1 internally used to advance the deck when drawing cards.
cardsplayed "faceup" how are cards from this deck played to the tabletop? 'faceup' or 'facedown'.
defaultheight "" what's the default height for cards played to the tabletop?
defaultwidth ""
discardpilemode "none" what type of discard pile does this deck have? 'none' = no discard pile, 'choosebacks' = allow players to see backs of cards and choose one, 'choosefronts' = see fronts and choose, 'drawtop' = draw the most recently discarded card, 'drawbottom' = draw the oldest discarded card.
_discardPile "" what's the current discard pile for this deck? comma-delimited list of cards. These are cards which have been removed from play and will not be put back into the deck on a shuffle until a recall is performed.
removedcardsmode 'choosefronts'
removedcards 'none'

[edit] Card

See Also: Cards

Property Default Value Notes
name "" Name of the card
avatar "" Front of the card
_deckid "" ID of the deck
_type "card"
_id ""
is_removed "false"
tooltip "" tooltip text
card_back "" Back of the card

[edit] Hand

Note that each player should only have ONE hand.

Property Default Value Notes
currentHand "" comma-delimited list of cards currently in the hand. Note that this is no longer read only. Ideally, it should only be adjusted with the card deck functions.
_type "hand"
_parentid "" ID of the player to whom the hand belongs
_id ""
currentView "bydeck" when player opens hand, is the view 'bydeck' or 'bycard'?

[edit] Jukebox Track

See also: u Jukebox

Property Default Value Notes
_id A unique ID for this object. Globally unique across all objects in this game. Read-only.
_type "jukeboxtrack" Can be used to identify the object type or search for the object. Read-only.
playing false Boolean used to determine whether or not the track is playing. Setting this to "true" and softstop to "false" plays a track.
softstop false Boolean used to determine whether or not a non-looped track has finished at least once. This must be set to "false" to ensure that a track will play.
title "" The visible label for the track in the jukebox tab.
volume 30 The volume level of the track. Note that this must be set to an integer (not a string), or you may break functionality. Values from 0-100 (percentage).
loop false Should the track be looped? Set to true if so.


[edit] Custom FX

Property Default Value Notes
_id A unique ID for this object. Globally unique across all objects in this game. Read-only.
_type "custfx" Can be used to identify the object type or search for the object. Read-only.
name "" The visible name for the FX in the FX Listing.
definition {} Javascript object describing the FX.

[edit] Door

Note: Window and Door use an inverted axis compared to other types of objects. For instance, a top variable that would be 100 for another object is y -100 for window or door.

Property Default Value Notes
_id A unique ID for this object. Globally unique across all objects in this game. Read-only.
_type "door" Read-only
color A hexadecimal color of the path.
x 0 Coordinate center of the door on the x axis.
y 0 Coordinate center of the door on the y axis.
isOpen false Determines whether a player can move through this door.
isLocked false Prevents players from being able to interact with the door.
isSecret false Removes a door icon from player view and functions as a barrier.
path Represented as two handles (handle0 and handle1) each with x and y coordinates.

[edit] Window

Note: Window and Door use an inverted axis compared to other types of objects. For instance, a top variable that would be 100 for another object is y -100 for window or door.

Property Default Value Notes
_id A unique ID for this object. Globally unique across all objects in this game. Read-only.
_type "window" Read-only.
color A hexadecimal color of the path.
x 0 Coordinate center of the door on the x axis.
y 0 Coordinate center of the door on the y axis.
isOpen false Determines whether a player can move through this window.
isLocked false Prevents players from being able to interact with the window.
path Represented as two handles (handle0 and handle1) each with x and y coordinates.
isSecret false Removes a door icon from player view and functions as a barrier.
path Represented as two handles (handle0 and handle1) each with x and y coordinates.

[edit] Example Usage

on('chat:message', function(msg) {
    if (msg.type === 'api' && msg.content === '!cw') {
        const currentPageID = Campaign().get('playerpageid');
        const win = createObj('window', {
            x: 70,
            y: -70,
            pageid: currentPageID,
            path: {
		        handle0: {
        			x: -70,
        			y: 0,
        		},
        		handle1: {
        			x: 35,
        			y: 0,
        		},
        	},
            color: '#000000'
        });
    }

    if (msg.type === 'api' && msg.content === '!mw') {
        const win = getObj('window', '-NG38yUgghBBoV8YR0y1');
        win.set({
           x: 240,
           y: -139
        });
    }

    if (msg.type === 'api' && msg.content === '!dw') {
        const win = getObj('window', '-NG38yUgghBBoV8YR0y1');
        win.remove();
    }
});

[edit] Creating Objects

createObj(type, attributes)

Note: currently you can create 'graphic', 'text', 'path', 'character', 'ability', 'attribute', 'handout', 'rollabletable', 'tableitem', and 'macro' objects.

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 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, graphics, texts, and paths belong to pages, etc.), 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. The one exception to this is when creating a Path, you must include the 'path' property, but it cannot be modified once the path is initially created.

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

[edit] Deleting Objects

object.remove()

You can delete existing game objects using the .remove() function. The .remove() function works on 'graphic', 'text', 'path', 'character', 'ability', 'attribute', 'handout', 'rollabletable', 'tableitem', and 'macro' objects. You call the function directly on the object. For example, mycharacter.remove();.

[edit] Removing Repeating Section Attributes

As noted above, attribute objects can be removed using this method. To remove items from a repeating section of a Character Sheet, you will need to collect the attributes for that section and remove them all.

function deleteRepeatingSectionRow(rowid, characterid) {
  const regex = new RegExp(`^repeating_.*?_${rowid}_.*?$`);
  const attrsInRow = filterObjs(function(obj) {
    if (obj.get('type') !== 'attribute' || obj.get('characterid') !== characterid) return false;
    return regex.test(obj.get('name'));
  });
  _.each(attrsInRow, function (attribute) {
    attribute.remove();
  });
}

[edit] Global Objects

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

[edit] 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").

[edit] state

The state variable is an object in the global scope which is accessible to all scripts running in a game. You can access the state object from any function or callback at any time just by using the global variable named state. Additionally, the state object is persisted between executions of the Sandbox, so you can use it to store information you want to have in future runs of your script.

Note: You should use the state object to store information that is only needed by the API, since it is not sent to player computers and does not make your game file larger. Store values that are needed in-game in the Roll20 objects' properties.

[edit] Storable Types

The state object is only capable of persisting simple data types, as supported by the JSON standard.

Type Examples Description
Boolean true false The value true or false.
Number 123.5 10 1.23e20 Any number format supported by Javascript. Floating-Point or Integer.
String 'Hello Fantasy' "oh, and World" A standard string of text.
Array [ 1, 2, 3, 4 ] [ 'A','B','C'][1, 2, ['bob', 3], 10, 2.5] An ordered collection of any of the types, including other arrays.
Object { key: 1, value: 'roll20' } A simple key/value object with string keys and any of the types as a value, including other objects.

Warning: While functions will appear to work when stored in the state initially, they will disappear the first time the state is restored from persistence, such as on a sandbox restart.

  • Note: This includes Roll20 objects which you get from events or the functions findObjs(), getObj(), filterObjs(), createObj(), etc.

[edit] Important Reminders

The state object is shared between all of the scripts in a sandbox. To avoid breaking other scripts, it is important to follow a few simple guidelines:

  • Never assign directly to the root state object.
state = { break: 'all the things' };  // NEVER DO THIS!!!
  • Avoid using local variables named state in your scripts. While this will work, it will be confusing to later users of your scripts and could cause issues if the code is carelessly edited.
function turn(){
    var state = Campaign().get('turnorder');  // Bad Practice, Avoid it!
    // ...
}
  • Always place your properties beneath at least one namespace property. Be sure to use a sufficiently descriptive namespace property. Avoid names like script or settings. It's best to either use the name of your module or your own name or handle.
if( ! state.MyModuleNamespace ) {
    state.MyModuleNamespace = { module: 'my module', ok: 'this is fine!', count: 0 };
}
state.MyModuleNamespace.count++;

[edit] Example Usage

This is a working example that uses the state object appropriately.

on('ready',function() {
    "use strict";

    // Check if the namespaced property exists, creating it if it doesn't
    if( ! state.MyModuleNS ) {
        state.MyModuleNS = {
            version: 1.0,
            config: {
                color1: '#ff0000',
                color2: '#0000ff'
            },
            count: 0
        };
    }

    // Using the state properties to configure a message to the chat. 
    sendChat(
        'Test Module',
        '<span style="color: '+state.MyModuleNS.config.color1+';">'+
            'State test'+
        '</span> '+
        '<span style="color: '+state.MyModuleNS.config.color2+';">'+
            'Script v'+state.MyModuleNS.version+' started '+(++state.MyModuleNS.count)+' times!'+
        '</span>'
    );
});

[edit] Finding/Filtering Objects

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

[edit] 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"));
    }
});


[edit] findObjs(attrs)

Pass this function a list of attributes, and it will return all objects that match as an array. 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.

[edit] filterObjs(callback)

Will execute the provided callback function on each object, and if the callback returns true, the object will be included in the result array. Currently, it is inadvisable to use filterObjs() for most purposes – due to the fact that findObjs() has some built-in indexing for better executing speed, it is almost always better to use findObjs() to get objects of the desired type first, then filter them using the native .filter() method for arrays.

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.

[edit] getAllObjs()

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


[edit] getAttrByName(character_id, attribute_name, value_type)

Gets the value of an attribute, using the default value from the character sheet if the attribute is not present. value_type is an optional parameter, which you can use to specify "current" or "max".

getAttrByName will only get the value of the attribute, not the attribute object itself. If you wish to reference properties of the attribute other than "current" or "max", or if you wish to change properties of the attribute, you must use one of the other functions above, such as findObjs.

For Repeating Sections, you can use the format repeating_section_$n_attribute, where n is the repeating row number(RowIndex) (starting with zero). For example, repeating_spells_$2_name will return the value of name from the third row of repeating_spells.

Instead of RowIndex, RowID can be used instead for referencing(?)

You can achieve behavior equivalent to getAttrByNamewith the following:

// current and max are completely dependent on the attribute and game system
// in question; there is no function available for determining them automatically
function myGetAttrByName(character_id,
                         attribute_name,
                         attribute_default_current,
                         attribute_default_max,
                         value_type) {
    attribute_default_current = attribute_default_current || '';
    attribute_default_max = attribute_default_max || '';
    value_type = value_type || 'current';

    var attribute = findObjs({
        type: 'attribute',
        characterid: character_id,
        name: attribute_name
    }, {caseInsensitive: true})[0];
    if (!attribute) {
        attribute = createObj('attribute', {
            characterid: character_id,
            name: attribute_name,
            current: attribute_default_current,
            max: attribute_default_max
        });
    }

    if (value_type == 'max') {
        return attribute.get('max');
    } else {
        return attribute.get('current');
    }
}