Difference between revisions of "API:Objects"
From Roll20 Wiki
(→Graphic (Token/Map/Card/Etc.)) |
(→Graphic (Token/Map/Card/Etc.)) |
||
Line 112: | Line 112: | ||
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''' | ||
+ | |||
+ | 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"> | ||
+ | //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" | ||
+ | </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: | ||
+ | |||
+ | <pre 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_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", "2"); //would set a badge of "2" on the red marker, and add it to the token if it's not already active. | ||
+ | </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. | ||
+ | |||
+ | The full list of status markers that are available (in the same order they appear in the marker tray): | ||
+ | |||
+ | <code>"red", "blue", "green", "brown", "purple", "pink", "yellow", "dead", "skull", "sleepy", "half-heart", "half-haze", "interdiction", "snail", "lightning-helix", "spanner", "chained-heart", "chemical-bolt", "death-zone", "drink-me", "edge-crack", "ninja-mask", "stopwatch", "fishing-net", "overdrive", "strong", "fist", "padlock", "three-leaves", "fluffy-wing", "pummeled", "tread", "arrowed", "aura", "back-pain", "black-flag", "bleeding-eye", "bolt-shield", "broken-heart", "cobweb", "broken-shield", "flying-flag", "radioactive", "trophy", "broken-skull", "frozen-orb", "rolling-bomb", "white-tower", "grab", "screaming", "grenade", "sentry-gun", "all-for-one", "angel-outfit", "archery-target"</code> | ||
===Page (Read Only)=== | ===Page (Read Only)=== |
Revision as of 14:43, 5 August 2013
Roll20 Mod
Use Mods
- Use & Install
- Mod:Script Index & Suggestions
- Short Community Scripts
- Meta Scripts
- User Documentation
- Mod Scripts(Forum)
- Mod Update 2024🆕
- Macro Guide
Mod Development
Reference
- Objects
- Events
- Chat Events & Functions
- Utility Functions
- Function documentation
- Roll20 object
- Token Markers
- Sandbox Model
- Debugging
Cookbook
Contents |
Types of Objects
There are several different types of objects that are used throughout the Roll20 API. Here's a quick listing of each, what it is, and what properties it contains (along with the default values). As a general rule of thumb, properties that begin with an underscore (_) are read-only and cannot be changed. You must access properties on objects using obj.get("property")
and set new values using obj.set("property", newvalue)
or obj.set({property: newvalue, property2: newvalue2})
.
Note: The id
property of an object is a globally-unique ID: no two objects should have the same one, even across different types of objects. In addition, since an object's id is frequently-accessed and never changes, there is a shortcut available where you can access it by using obj.id
instead of obj.get("_id")
if you wish (either will work).
Path
{ _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 }
Text
{ _id: "-Abc123", top: 0, left: 0, width: 0, height: 0, text: "", font_size: 16, //for best results stick to the pre-sets in the text editing menu rotation: 0, color: "#000000", font_family: "unset", //see values of select element in text editing menu layer: "", controlledby: "", //Comma-delimited list of Player IDs who can control (including delete) this text object. Automatically set to the player who created it if created by a player. _type: "text", //identifies the object is text. read-only. _pageid: "-Abc123" }
Graphic (Token/Map/Card/Etc.)
{ _id: "-Abc123", left: 0, top: 0, width: 0, height: 0, rotation: 0.0, layer: "", isdrawing: false, //advanced -> is drawing? flipv: false, //flip vertically fliph: false, //flip horizontally name: "", //Token Name gmnotes: "", //GM Notes 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: "" }
Important Notes About Linked Characters + Tokens
Note that for tokens that are linked to Characters, the controlledby
field on the token is overridden by the controlledby
field on the Character.
For token bars (e.g. bar1_value
and bar1_max
) where the token is linked to an Attribute (e.g. bar1_link
is set), setting a value to the bar will automatically update the underlying Attribute's current
and/or max
values as well, so you don't have to set both manually.
In addition, when the Attribute (or token bar) is modified in-game, you will hear a change:attribute
(and property-specific, e.g. change:attribute:current
) event, followed by a change:graphic
(and change:graphic:bar1_value
) event. You can choose to respond to either event, but the underlying bar values will not yet be updated when the attribute event fires, since it fires first.
Important Notes About Status Markers
As of August 6, 2013 the way that status markers on tokens are handled has changed. The "statusmarkers" property of the Graphic object is now a comma-delimited list of all status marker colors/icons that should be active on the token. The format is as follows:
//Comma-delimited (use join to create or split to turn into an array). If a status icon/color is followed by an "@" symbol, the number after "@" will be shown as the badge on the icon statusmarkers = "red,blue,skull,dead,brown@2,green@6"
While you can access the statusmarkers
property directly, to maintain backward-compatibility with existing scripts, and to provide an easy way to work with the status markers without needing to write code to handle splitting up and parsing the string yourself, we provide a set of "virtual" properties on the object that you can set/get to work with the status markers. Each status marker has a "status_<markername>" property. For example:
obj.get("status_red"); //Will return false if the marker is not active, true if it is, and a string (e.g. "2" or "5") if there is currently a badge set on the marker obj.get('status_bluemarker'); //Is still supported for backwards compatability, and is equivalent to doing obj.get("status_blue"); obj.set("status_red", false); //would remove the marker obj.set("status_red", "2"); //would set a badge of "2" on the red marker, and add it to the token if it's not already active.
Note that these virtual properties do not have events, so you must use change:graphic:statusmarkers
to listen for changes to the status markers of a token, and for example change:graphic:status_red
is NOT a valid event that will ever fire.
The full list of status markers that are available (in the same order they appear in the marker tray):
"red", "blue", "green", "brown", "purple", "pink", "yellow", "dead", "skull", "sleepy", "half-heart", "half-haze", "interdiction", "snail", "lightning-helix", "spanner", "chained-heart", "chemical-bolt", "death-zone", "drink-me", "edge-crack", "ninja-mask", "stopwatch", "fishing-net", "overdrive", "strong", "fist", "padlock", "three-leaves", "fluffy-wing", "pummeled", "tread", "arrowed", "aura", "back-pain", "black-flag", "bleeding-eye", "bolt-shield", "broken-heart", "cobweb", "broken-shield", "flying-flag", "radioactive", "trophy", "broken-skull", "frozen-orb", "rolling-bomb", "white-tower", "grab", "screaming", "grenade", "sentry-gun", "all-for-one", "angel-outfit", "archery-target"
Page (Read Only)
{ _id: "-Abc123", name: "", //Page's title showgrid: true, //are we showing the grid? showdarkness: false, //Is the Fog of War active? showlighting: false, //Is Dynamic Lighting active? width: 25, //width in units height: 25, //height in units snapping_increment: 1.0, //the size of a grid space in units grid_opacity: 0.50, //opacity of the grid fog_opacity: 0.35, //opacity of the fog of war for the GM background_color: "#ffffff", //background color (HEX) gridcolor: "#C0C0C0", //grid color (HEX) grid_type: "square", //eitehr "square", "hexv", or "hexh" scale_number: 5, //1 unit = how much distance scale_units: "ft", //scale is in these units gridlabels: false, //show grid labels for hex grid diagonaltype: "foure", //one of "foure", "pythagorean" (Euclidean), "threefive", or "manhattan" }
Campaign
{ _type: "campaign", turnorder: "", // a JSON string, 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 }
Turn Order
The turn order is a JSON string representing the current turn order listing. It is an array of objects. Currently, the turn order can only contain objects from one page at a time -- the current Page ID for the turn order is the "initiativepage" attribute. Be sure to keep them both in-sync or you may end up with strange results.
To work with the turn order, you will want to use JSON.parse()
to get an object representing the current turn order state (NOTE: Check to make sure it's not an empty string ""
first...if it is, initialize it yourself with an empty array). Here's an example turn order object:
[ { "id":"36CA8D77-CF43-48D1-8682-FA2F5DFD495F", //The ID of the Graphic object. If this is set, the turn order list will automatically pull the name and icon for the list based on the graphic on the tabletop. "pr":"0", //The current value for the item in the list. Can be a number or text. "custom":"" //Custom title for the item. Will be ignored if ID is set to a value other than "-1". }, { "id":"-1", //For custom items, the ID MUST be set to "-1" (note that this is a STRING not a NUMBER. "pr":"12", "custom":"Test Custom" //The name to be displayed for custom items. } ]
To modify the turn order, edit the current turn order object and then use JSON.stringify()
to change the attribute on the Campaign. Note that the ordering for the turn order in the list is the same as the order of the array, so for example push()
adds an item onto the end of the list, unshift()
adds to the beginning, etc.
var turnorder; if(Campaign().get("turnorder") == "") turnorder = []; //NOTE: We check to make sure that the turnorder isn't just an empty string first. If it is treat it like an empty array. else turnorder = JSON.parse(Campaign().get("turnorder")); //Add a new custom entry to the end of the turn order. turnorder.push({ id: "-1", pr: "15", custom: "Turn Counter" }); Campaign().set("turnorder", JSON.stringify(turnorder));
Player
{ _d20userid: "", //The site-wide unique ID of the user. _displayname: "", //Current display name _online: false, color: "#13B9F0", _macrobar: "", //Comma-delimited string of the macros in the player's macro bar. showmacrobar: false, //Show macro bar? _id: "", _type: "player" }
Macro
{ name: "", action: "", visibleto: "", //Comma-delimited list of additional Player IDs this macro is visible to. _id: "", _type: "macro", _playerid: "" //Player this macro belongs to }
Rollable Table
{ name: "new-table", showplayers: true, _type: "rollabletable", _id: "" }
Table Item
{ name: "", weight: 1, _type: "tableitem", _id: "", _rollabletableid: "" //ID of the rollable table this item belongs to }
Character
{ name: "", bio: "", gmnotes: "", archived: false, inplayerjournals: "", //Comma-deliminted list of player IDs 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" }
Attribute
{ name: "Untitled", current: "", max: "", _id: "", _type: "attribute", _characterid: "" }
Ability
{ name: "Untitled_Ability", description: "", action: "", _id: "", _characterid: "", _type: "ability" }
Handout
{ name: "Mysterious Note", notes: "", inplayerjournals: "", //Comma-delimited list of Player IDs who can see this Handout in their journal. The GM can always see the Handout. archived: false, controlledby: "", //Comma-delimited list of Player IDs who can control (and edit) this Handout. _type: "handout", _id: "" }
Creating Objects
![]() | Note: Currently only characters, handouts, attributes, and abilities can be created. Other objects will be supported soon. |
createObj(type, attributes)
You can create a new object in the game using the createObj
function. You must pass in the type of the object (one of the valid _type
properties from the objects list above), as well as a an attributes
object containing a list of properties for the object. Note that if the object is has a parent object (for example, attributes and abilities belong to characters), you must pass in the ID of the parent in the list of properties (for example, you must include the characterid
property when creating an attribute). Also note that even when creating new objects, you can't set read-only properties, they will automatically be set to their default value.
createObj
will return the new object, so you can continue working with it.
//Create a new Strength attribute on any Characters that are added to the game. on("add:character", function(obj) { createObj("attribute", { name: "Strength", current: 0, max: 30, characterid: obj.id }); });
Global Objects
There are several objects that are globally available anywhere in your script.
Campaign()
(function)
A function which returns the Campaign
object. Since there is only one campaign, this global always points to the only campaign in the game. Useful for doing things like checking to see if an object is on the active page using Campaign().get("playerpageid")
.
state
This is an object that is initialized as a blank object whenver your script is loaded. You can set whatever properties you want on this object, and they are available to all of your event callbacks, and persist between callbacks. In addition, the state
object is persisted between play sessions, so you can use this object to store long-term information about the state of the game.
You should use the state object to store information that is only related to the API, since it is not sent to player computers and does not make your campaign file larger, and store properties that are needed in-game in the objects themselves.
state.numTimesTokensMoved = 0; on("change:graphic", function(obj) { state.numTimesTokensMoved = state.numTimesTokensMoved + 1; });
Finding/Filtering Objects
The API provides several helper functions which can be used to find objects.
getObj(type, id)
This function gets a single object if pass in the _type
of the object and the _id
. It's best to use this function over the other find functions whenever possible, as its the only one that doesn't have to iterate through the entire collection of objects.
on("change:graphic:represents", function(obj) { if(obj.get("represents") != "") { var character = getObj("character", obj.get("represents")); } });
findObjs(attrs)
Pass this function a list of attributes, and it will return all objects that match. Note that this operates on all objects of all types across all pages -- so you probably want to include at least a filter for _type and _pageid if you're working with tabletop objects.
var currentPageGraphics = findObjs({ _pageid: Campaign().get("playerpageid"), _type: "graphic", }); _.each(currentPageGraphics, function(obj) { //Do something with obj, which is in the current page and is a graphic. });
You can also pass in an optional second argument which contains an object with a list of options, including:
- caseInsensitive (true/false): If true, string properties will be compared without regard for the case of the string.
var targetTokens = findObjs({ name: "target" }, {caseInsensitive: true}); //Returns all tokens with a name of 'target', 'Target', 'TARGET', etc.
filterObjs(callback)
Will execute the provided callback funtion on each object, and if the callback returns true, the object will be included in the result array.
var results = filterObjs(function(obj) { if(obj.get("left") < 200 && obj.get("top") < 200) return true; else return false; }); //Results is an array of all objects that are in the top-left corner of the tabletop.
getAllObjs()
Returns an array of all the objects in the Campaign (all types). Equivalent to calling filterObjs and just returning true
for every object.