Revision as of 19:49, 31 January 2016

Utility functions are provided to help you work with the Roll20 game space consistently. You can call a utility function from anywhere in your scripts (inside any event callback, for example).

Underscore.js

You have access to the Underscore.js library (via the _ global object) to help make things easier. Underscore provides helper functions for things like _.each (to iterate through an array of objects). Check out the Underscore documentation for more information.

Logging

log(message)

You can use this function to log output to the API console on the Script Editor page. Useful for debugging your scripts and getting a better handle on what's going on inside the API sandbox.

on("change:graphic", function(obj) {    
  log("Heard change for object ID: " + obj.id);
});

Object Ordering

toFront(obj) and toBack(obj)

These two functions will move an object on the tabletop to the front (or back) of layer it is currently on. Note that you must pass in an actual object, such as one you receive in an event callback or by calling getObj or findObjs.

Random Numbers

randomInteger(max)

Use This Function For Dice! This function accounts for Modulo Bias which ensures that the resulting random numbers are also evenly distributed between 1 and MAX.

Returns a random integer, with the lowest value being 1, and the highest value being max. This is the same functionality that Roll20 uses to power its dice rolls, and these numbers have been statistically and rigorously proven to be random.

Math.random()

You can call Math.random() like normal in your API scripts, trusting that the results will be random, because the "default" Math.random() in Javascript has been replaced with the cryptographically-secure PRNG that powers Roll20. So existing scripts that use Math.random() can be used with knowing that the results really are as close to random as it's possible to get on a computer.

Do not use Math.random() if even distribution of numbers in a range are desired. While Math.random() gives you as good of a random number as Roll20 can manage the math to turn that random number into a range with even distribution (like a dice roll) is not as straight forward as multiplication with a modulo or a floor call. Use randomInteger(max) for those cases.

Player Is GM

playerIsGM(playerid)

The Player Is GM function returns a boolean response on whether a player in the game is a GM or not. The function will always return the correct answer depending on the current moment, so even if a GM chooses to re-join as a player or a player is promoted to a GM mid-game, playerIsGM() will respond accordingly without any need to clear a cache or restart the API sandbox.

Jukebox Playlists

playJukeboxPlaylist(playlistid)

The play function takes in the Folder ID (get it from the "_jukeboxfolder" property in the Campaign object) of the playlist, and will begin playing that playlist for everyone in the game.

stopJukeboxPlaylist()

The stop function does not require any arguments, and will stop any playlist that is currently playing.

Miscellaneous

sendPing(left, top, pageid, (optional) playerid, (optional) moveAll)

Sends a "ping" the tabletop (the same as if a player holds down their mouse button). You must specify the top/left coordinates, and the pageid of the page to be pinged. You can optionally specify the ID of a player who performed the ping -- if you don't "api" will be assumed and the ping will be yellow. You can also pass in "true" for the moveAll option if you want to move the player's screens to that location as well.

//Example:
on('ready', function() {
   sendPing(500, 500, Campaign().get('playerpageid'), null, true); //Sends a ping to 500,500 on the page players are currently on, using the yellow color and moving the player's screens.
});