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

Personal tools

API:Function documentation

From Roll20 Wiki

Revision as of 06:23, 29 July 2016 by Brian (Talk | contribs)

Jump to: navigation, search

Roll20 makes a number of functions available that are not part of core JavaScript or some other library.

Global variables

Variable Description
_ This is the namespace object for the Underscore.js library.
state Properties of the state object will persist between game sessions.

_ (Underscore)

This is the namespace object for the Underscore.js library. Underscore has many functions for collection manipulation.


Properties of the state object will persist between game sessions. The same state object is also shared between all API scripts in a campaign, so it is strongly recommended that when writing values to state, you minimize your footprint as much as possible in order to avoid name collisions. Note: state gets serialized with JSON, so you cannot store functions or objects with cyclical references.

Global functions

Return type Function Description
Roll20 object Campaign Gets the singleton Campaign Roll20 object.
Roll20 object createObj Creates a new Roll20 object.
Array of Roll20 objects filterObjs Gets all Roll20 objects which pass a predicate test.
Array of Roll20 objects findObjs Gets all Roll20 objects with properties that match a given set of attributes.
Array of Roll20 objects getAllObjs Gets all Roll20 objects in the campaign.
varies getAttrByName Gets the current or max value of an attribute Roll20 object.
Roll20 object getObj Gets a specific Roll20 object.
log Logs a message to the API console.
on Registers an event handler.
Boolean playerIsGM Checks whether a player currently has GM privileges.
playJukeboxPlaylist Start playing a jukebox playlist.
Number randomInteger Generates a random integer value.
sendChat Sends a chat message.
sendPing Sends a ping similar to holding the left mouse button.
spawnFx Spawns a particle emitter.
spawnFxBetweenPoints Spawns a particle emitter that moves from one point to another.
spawnWithDefinition Spawns a particle emitter that is not represented by an FX Roll20 object.
stopJukeboxPlaylist Stops all currently playing jukebox playlits.
toBack Moves a graphic Roll20 object below all of the other graphics on the same tabletop layer.
toFront Moves a graphic Roll20 object above all of the other graphics on the same tabletop layer.



No parameters


The singleton campaign Roll20 object.


var currentPageID = Campaign().get('playerpageid'),
    currentPage = getObj('page', currentPageID);



(String) The type of Roll20 object to create. Only 'graphic', 'text', 'path', 'character', 'ability', 'attribute', 'handout', 'rollabletable', 'tableitem', and 'macro' may be created.
(Object) The initial values to use for the Roll20 object's properties.


The Roll20 object that was created.


When creating a Roll20 object that has a parent object (such as creating an attribute Roll20 object, which is a child of a character Roll20 object), you must supply the id of the parent in attributes.

on('add:character', function(obj) {
    createObj('attribute', {
        name: 'Strength',
        current: 0,
        max: 30,

When creating a path Roll20 object, you must supply a value for the read-only property _path. This is an exception to the rule that prevents you from setting the value of read-only properties when creating Roll20 objects.

createObj('path', {
    left: 7000,
    top: 140,
    width: 140,
    height: 140,
    layer: 'objects',
    path: JSON.stringify([['M', 0, 0], ['L', 70, 0], ['L', 0, 70], ['L', 0, 0]])

When creating a handout Roll20 object, you cannot set the text or gmnotes at the time of creation.

var handout = createObj('handout', {
    name: 'A Letter Addressed to You',
    inplayerjournals: 'all',
    archived: false
    notes: 'Notes can only be set after the handout is created',
    gmnotes: 'GM Notes can only be set after the handout is created'



(Function) A predicate function to test all Roll20 objects against. The callback function receives a Roll20 object as a parameter, and should return either true (for Roll20 objects that will be included in the filterObjs return value) or false (for all other Roll20 objects).


An array of Roll20 objects which passed the predicate test.


var tokenName = getMyTokenName(),
    duplicateTokens = filterObjs(function(obj) {
        if (obj.get('type') !== 'graphic' || obj.get('subtype') !== 'token' || obj.get('name') === tokenName) return false;
        return obj.get('name').indexOf(tokenName) === 0 && /\d+$/.text(obj.get('name'));



(Object) A collection of key:value pairs to match with Roll20 objects in the campaign.
(Object, optional) If options.caseInsensitive is true, string comparisons between Roll20 objects and attributes will be case-insensitive.


An array of Roll20 objects with properties that match attributes.


var npcs = findObjs({ type: 'character', controlledby: '' });



No parameters


An array of all Roll20 objects in the campaign.


var everything = getAllObjs();



(String) The id of the character Roll20 object that is the parent of the attribute Roll20 object you want the value of.
(String) The name of the attribute Roll20 object you want the value of.
(String, optional) Either "current" or "max" (defaults to "current" if omitted).


The current or max property of the appropriate attribute. If the desired property is not set, the default value specified by the character sheet (if there is a default) will be used instead.


var character = getMyCharacter(),
    strength = getAttrByName(, 'strength'),
    strength_max = getAttrByName(, 'strength', 'max');



(String) The type of Roll20 object to get.
(String) The unique id for the Roll20 object to get.


The specified Roll20 object.


on('chat:message', function(msg) {
    var sendingPlayer = getObj('player', msg.playerid);



(varies) The message to post to the API console. The message parameter will be transformed into a String with JSON.stringify.




on('chat:message', function(msg) {
    log('Message received from:');
    log(getObj('player', msg.playerid));
"Message received from:"
{"_d20userid":"123456","_displayname":"John Doe","speakingas":"","_online":true,"color":"#885b68","_macrobar":"-J16Z-dRU5tleKiKOg0X|-K3F_4q_b1p-Vdiwgn1t","showmacrobar":true,"_id":"-J16Z-dRU5tleKiKOc0X","_type":"player","_lastpage":""}



(String) There are five types of event:
  • ready
  • change
  • add
  • destroy
  • chat
With the exception of ready, all event types must also be paired with an object type. For chat, this is always message. For everything else, this is the type property of a Roll20 object. In addition to the object type, change events can also optionally specify a property of the specified Roll20 object to watch.
The 2-3 parts of the event (type, object, and optionally property) are separated by colons. So, valid event strings include but are not limited to "ready", "chat:message", "change:graphic", "change:campaign:playerpageid", "add:character", and "destroy:handout".
(Function) The function that will be called when the specified event fires. The parameters passed depend on the event type:
  • ready events have no callback parameters.
  • change events have an obj parameter, which is a reference to the Roll20 object as it exists after the change, and a prev parameter, which is a plain old JavaScript object with properties matching the Roll20 object prior to the change event.
  • add events have an obj parameter, which is a reference to the new Roll20 object.
  • destroy events have an obj parameter, which is a reference to the no-longer existing Roll20 object.
  • chat events have a msg parameter, which contains the details of the message that was sent to the chat.


Events are fired in the order they were registered, and from most to least specific. In this example, a change to a graphic Roll20 object's left property will result in function3 getting called, followed by function1 and then function2.

on('change:graphic', function1);
on('change:graphic', function2);
on('change:graphic:left', function3);

add events will attempt to fire for Roll20 objects that are already in the campaign when a new session starts. In order to prevent this behavior, you can wait to register your add event until the ready event fires.

on('add:graphic', function(obj) {
    // When the session begins, this function will be called for every graphic in the campaign
    // This function will also be called whenever a new graphic Roll20 object is created

on('ready', function() {
    on('add:graphic', function(obj) {
        // This function will *only* be called when a new graphic Roll20 object is created, not for ones that already exist

The pre parameter for change events is not a Roll20 object, it is a plain old JavaScript object. As such, you cannot use the get or set functions, and you cannot omit the leading underscores on read-only properties.

on('change:graphic', function(obj, prev) {
    var id1 =,         // all three are equivalent
        id2 = obj.get('id'),
        id3 = obj.get('_id'),

        id4 =,        // undefined
        id5 = prev.get('id'), // undefined is not a function
        id6 = prev._id;       // correct

    // both are equivalent
    obj.set('left', 70);
        left: 70

    prev.set('left', 70); // undefined is not a function
    prev.set({            // undefined is not a function
        left: 70
    prev.left = 70;       // correct, although it won't change anything on the tabletop



(String) The id of the player Roll20 object to check.


true if the player currently has GM permissions, or false otherwise.


This function is especially useful for limiting API commands to GM use.

on('chat:message', function(msg) {
    if (msg.type !== 'api') return;

    if (msg.content.indexOf('!playercommand') === 0) {
        // ...
    } else if (msg.content.indexOf('!gmcommand') === 0) {
        if (!playerIsGM(msg.playerid)) return;
        // ...