Page Updated:   2021-10-05

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

Campaign

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.

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

See also: Player

Page

See Also: Page Toolbar

Path

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

Text

Graphic (Token/Map/Card/Etc.)

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

General

Dynamic Lighting

Legacy Dynamic Lighting

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"

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 that 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.

Journal

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

Character

See also the imgsrc and avatar property restrictions

Attribute

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

Ability

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.

Handout

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 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.

Macro

See also: Macro

Rollable Table

Table Item

Deck

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

Card

See Also: Cards

Hand

Note that each player should only have ONE hand.

Jukebox Track

See also: u Jukebox

Custom FX

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

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

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

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.

Storable Types

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

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.

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++;

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

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 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.

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.

getAllObjs()

Returns an array of all the objects in the Game (all types). Equivalent to calling filterObjs and just returning true 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. 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 (starting with zero). For example, repeating_spells_$2_name will return the value of name from the third row of repeating_spells.

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