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

API:Use Guide

From Roll20 Wiki

Revision as of 20:24, 23 April 2013 by Riley D. (Talk | contribs)

Jump to: navigation, search

Roll20 API

Getting Started


Reference


Cookbook (Examples)


Community Scripts

Contents

The Script Editor

To edit your campaign scripts, go to the My Settings tab on the right sidebar, and scroll all the way down to the bottom. There you'll find a button titled "Manage API Scripts". Clicking that button will open up a dialog box with a script editor. You can create multiple scripts for your campaign, but they will all run in the same "environment", meaning that you shouldn't have multiple scripts trying to overwrite the same values or you could get unintended results.

Reactive Scripts: Listen to Events, Modify Objects

The first (and most simple type) of API usage is to react to changes on the tabletop, and then respond by making additional changes to the changed objects. This type of script is composed of a number of functions which listen to events that happen during the game. Then it will modify objects that are passed during those events, which will change what happens on the tabletop.

The most basic script which would simply move any piece which moved an additional 5 feet (assuming default page settings) would be:

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

As you can see, we created a simple function using on which will be executed anytime the change:graphic event is heard. The function is passed the graphic object obj. To make a change, we just modify obj using the set function -- whatever properties we change will be detected and changed on the tabletop.

Important Note: You must use set and get to set and get current values on objects or your changes will not be saved. (See below for a listing of object types and their properties, as well as a listing of all events and what arguments each event is passed.)

A Note on Utility Functions

Of course, the previous example isn't incredibly helpful because it always adds 70 pixels to the location of the token. But what if the user has changed their scale so that 5ft is 140 pixels? The Roll20 API provides several handy utility functions to help with this (and other) common scenarios. Let's modify our previous example to use the distanceToPixelsfunction, which will tell us how many pixels "five feet" (or inches, or meters, or whatever other distance type has been set) on the tabletop is.

on("change:graphic", function(obj) {    
  obj.set({        
    left: obj.get("left") + distanceToPixels(5);    
  });
}

Now if the current page is setup to use the default grid sizing, distanceToPixels(5); will still return 70 pixels, but if the page is setup to have a scale twice the size of normal, it would return 140.

It's always a good idea to use utility functions whenever they're available to help keep your script from breaking if the settings of a page or a token change.

Proactive Scripts: Do Things Without User Intervention

In addition to reacting to user events, you can also do things with the API automatically that aren't tied to a specific event from the players. For example, let's have a token that patrols back and forth on the map.

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

on("ready", function() {
   //Wait until the ready event fires so we know the campaign 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 Campaign called "Guard A".
   var direction = -70; //Walk left 70 pixels.
   var stepstaken = 0; //How many steps have we walked in the current direction?
   setInterval(function() {
     if(stepstaken > 5) {
       //Switch directions!
       direction = direction * -1; //will "flip" the direction we're walking
       stepstaken = 0; //reset steps back to 0.
     }
     patroltoken.set("left", patroltoken.get("left") + direction); //walk!
     stepstaken++;
   }, 5000); //take an action every 5 seconds
});