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:Advanced Examples

From Roll20 Wiki

Revision as of 14:50, 25 April 2013 by Eric D. (Talk | contribs)

Jump to: navigation, search

Roll20 API

Getting Started


Cookbook (Examples)

Community Scripts

The Cookboox provides some examples of simple scripts that can help you get started. Feel free to take them and modify them for use in your own campaigns. There's also an API Scripts Forum where you can discuss API Scripting and share your scripts with the community.

Token Status Manager (Contributed by Eric Dalquist)

This script automatically adds status markers based on the bar values. The script can be configured to track any of the three bars, set any of the status markers for any ratio between 0 and 1. The script can manage multiple bars/tokens in a single instance. The example below watches bar 1 and sets the red marker when the value is <= 50% and then sets the dead marker when the value is <= 0.

 * Set various token markers based on bar cur/max ratios
 * The CONFIG array can have any number of configuration objects. These objects
 * are processed in order.
 * barId - The ID of the bar to look at the values for [1, 2, 3]
 * barRatio - The ratio of bar value to max value that triggers setting the status marker [0 - 1]
 * status - The name of the status marker to toggle [redmarker, bluemarker, greenmarker, brownmarker, purplemarker, dead]
 * whenLow - The state of the marker when the bar value is <= the ratio [true, false]
var CONFIG = [
    {barId: 1, barRatio: .5, status: "redmarker", whenLow: true},
    {barId: 1, barRatio: 0, status: "dead", whenLow: true}];

on("change:token", function(obj) {
    CONFIG.forEach(function(opts) {
        var maxValue = parseInt(obj.get("bar" + opts.barId + "_max"));
        var curValue = parseInt(obj.get("bar" + opts.barId + "_value"));
        log(opts.barId + ": " + curValue + "/" + maxValue);
        if (maxValue != NaN && curValue != NaN) {
            var markerName = "status_" + opts.status;
            if (curValue <= (maxValue * opts.barRatio)) {
                obj.set(markerName, opts.whenLow);
            else {
                obj.set(markerName, !opts.whenLow);

For the most recent revision see: