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:Use Guide

From Roll20 Wiki

Revision as of 17:58, 18 February 2020 by Drespar (Talk | contribs)

Jump to: navigation, search


Roll20 API

Getting Started


Cookbook (Examples)

Community Scripts


The Script Editor

To edit your game scripts, click on the "API Scripts" link on the Game Details page for your game (the same place where options such as the "Chat Log" and "Copy/Extend Game" are located). You will be presented with a page with several features:

  • A list of tabs along the top. Your game can have multiple scripts for ease of organization. Note that all scripts will still run in the same context, meaning that you shouldn't have multiple scripts trying to overwrite the same values at the same time or you could get unintended results.

Whenever you click the "Save Scripts" button, the sandbox for your game will be restarted (losing any in-memory data which hasn't been persisted in the state object or in Roll20 objects) and use the new script modifications you just made. This also applies if you add a new script, delete a script, or toggle a script to enable/disable it.

The API Console


Reactive Scripts: Listen to Events, Modify Objects



on("change:graphic", function(obj) {
    left: obj.get("left") + 70    



A Note on Utility Functions


on("change:graphic", function(obj) {    



Proactive Scripts: Do Things Without User Intervention


Note: Although this type of script is not dependent on user interaction, the API scripts for your game will still only run when at least one person is connected to your game.

on("ready", function() {
   //Wait until the ready event fires so we know the game is completely loaded.
   //Get a reference to our patrolling token.
   var patroltoken = findObjs({_type: "graphic", name: "Guard A"})[0]; //We know there is a token in the Game called "Guard A".
   var direction = -1*distanceToPixels(5); //Walk left 70 pixels.
   setInterval(function() {
     if(stepstaken > 3) {
       //Switch directions!
       stepstaken = 0; //reset steps back to 0.

A Treatise on Asynchronous Functions

An asynchronous function is one that returns the thread of control to the calling scope immediately and performs some duty in the background. Here's a very simple and easy to understand example which you can paste in an API scripts tab:

  log('Parent Scope - Before call to asynchronous function.');

    log('Asynchronous Function Scope - Doing the Asynchronous function work.');
  },10 /* 10 milliseconds */);

  log('Parent Scope - after call to asynchronous function.');

In the API log, you'll see something like this:

"Parent Scope - Before call to asynchronous function."
"Parent Scope - after call to asynchronous function."
"Asynchronous Function Scope - Doing the Asynchronous function work."

Looking at that code, you think "Of course it will happen later, you told it to run in 10 milliseconds, duh?". Here is a less obvious example that will have the same log messages:


  sendChat('Async Function','Evaluate this: [[1d6]]',function(msg){


Asynchronous functions are necessary to prevent the API from hanging all the time. If every dice roll was handled synchronously, the API would be super sluggish and unresponsive. Almost any function you see that takes a callback is asynchronous. (Exception for some of the, _.reduce, etc functions, these are examples of functional programming in contrast to the procedural programming most people are used to.)