API:Utility Functions
From Roll20 Wiki
Roll20 API Getting Started
Reference
- Objects
- Events
- Chat Events and Functions
- Utility Functions
- Function documentation
- Sandbox Model
- Debugging
- Cookbook
Cookbook (Examples)
Community Scripts
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).
Contents |
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.
Distance Functions
A Note on Distances and Grids in Roll20
In Roll20, a "unit" is always 70 pixels on the screen. The "unit" is the building block that distance and the grid are built on top of. By default:
- 1 unit = 5 ft
- 1 unit = 1 grid square
- Therefore, 5 ft = 1 unit = 1 square
However, the GM can change both the size of the grid, as well as the scale of the distance. 1 unit is always 70 pixels, but the GM could change the settings such that 1 unit is now 10ft (meaning 70 pixels = 10ft), or that each grid space is 2 units (meaning each grid space is now 140 pixels). So it's important to use conversion functions (provided below) to make sure that you're respecting the game's settings.
distanceToPixels(distance) (NOT YET IMPLEMENTED)
returns: Number of pixels (e.g. 70)
This function will take in a distance and convert it to pixels based on the currently active page's settings for scale. It's easiest to think of distance in terms of feet, which is the default distance type. So if you pass in 5 for the distance
parameter, the function would return the number of pixels in 5 feet based on the scale settings (by default this would be 70 pixels).
distanceToPixels(5);//returns 70 distanceToPixels(1);//returns 14 //If the scale is 1 unit = 10ft distanceToPixels(5)//returns 35
pixelsToDistance(pixels) (NOT YET IMPLEMENTED)
returns: Number of distance (e.g. 5)
This function is the opposite of distanceToPixels, and will take in a number of pixels and tell you the distance that those pixels are based on the scale.
on("change:graphic", function(obj, prev) { var pixels_moved_left = obj.get("left") - prev["left"] //How much distance is that? var distance_moved_left = pixelsToDistance(pixels_moved_x); //And what type of distance? getObj("page", Campaign().playerpageid).get("scale_units"); // "ft", "m", "km", etc. });
distanceToUnits(distance) (NOT YET IMPLEMENTED)
returns: Number of units (e.g. 1)
You could use distanceToPixels and do some simple math to figure the number of units (remember: 1 unit is always 70 pixels), but this convenience function is here to help make your life easier.
//Default scale of 1 unit = 5ft distanceToUnits(5);//returns 1 //Modified scale of 1 unit = 10ft distanceToUnits(5);//returns 0.50
unitsToDistance(units) (NOT YET IMPLEMENTED)
returns: Number of distance (e.g. 5)
Opposite of distanceToUnits.