Page Updated:   2024-06-09

The following are not full scripts. They are meant to be stitched together along with business logic to assist in the creation of full scripts, not create scripts on their own.

Revealing Module Pattern

The Module Pattern emulates the concept of classes from other languages by encapsulating private and public members within an object. The Revealing Module Pattern improves upon the Module Pattern by making the syntax more consistent.

var myRevealingModule = myRevealingModule || (function() {
    var privateVar = 'This variable is private',
        publicVar  = 'This variable is public';

    function privateFunction() {
        log(privateVar);
    }

    function publicSet(text) {
        privateVar = text;
    }

    function publicGet() {
        privateFunction();
    }

    return {
        setFunc: publicSet,
        myVar: publicVar,
        getFunc: publicGet
    };
}());

log(myRevealingModule.getFunc()); // "This variable is private"
myRevealingModule.setFunc('But I can change its value');
log(myRevealingModule.getFunc()); // "But I can change its value"

log(myRevealingModule.myVar); // "This variable is public"
myRevealingModule.myVar = 'So I can change it all I want';
log(myRevealingModule.myVar); // "So I can change it all I want"

Memoization

Memoization is an optimization technique which stores the result for a given input, allowing the same output to be produced without computing it twice. This is especially useful in expensive computations. Of course, if it is rare that your function will receive the same input, memoization will be of limited utility while the storage requirements for it continue to grow.

var factorialCache = {};
function factorial(n) {
    var x;

    n = parseInt(n || 0);
    if (n < 0) {
        throw 'Factorials of negative numbers are not well-defined';
    }

    if (n === 0) {
        return 1;
    } else if (factorialCache[n]) {
        return factorialCache[n];
    }

    x = factorial(n - 1) * n;
    factorialCache[n] = x;
    return x;
}

In a Roll20 API script, the cached values could potentially be stored in state, which will persist between game sessions. If you have a large number of potential inputs, however, be aware that Roll20 may throttle your use of state.

Asynchronous Semaphore

An asynchronous semaphore allows you to fire a callback method after a set of asynchronous operations (such as calls to sendChat) have completed. While you can't guarantee what order the operations will complete in, you can guarantee that all of them have completed when the semaphore's callback fires.

When using a semaphore, call v() prior to calling each asynchronous operation, and call p() as the last statement of each asynchronous operation. If the number of operations you're going to perform is known ahead of time, you can also supply that number to the semaphore constructor and omit the calls to v.

This particular implementation of an asynchronous semaphore also lets you supply a context for the callback (set the value of this), as well as pass parameters to the callback. The parameters can be given either in the constructor or in the call to p. (Parameters in p take precedence over parameters in the constructor.)

function Semaphore(callback, initial, context) {
    var args = (arguments.length === 1 ? [arguments[0]] : Array.apply(null, arguments));

    this.lock = parseInt(initial, 10) || 0;
    this.callback = callback;
    this.context = context || callback;
    this.args = args.slice(3);
}
Semaphore.prototype = {
    v: function() { this.lock++; },
    p: function() {
        var parameters;

        this.lock--;

        if (this.lock === 0 && this.callback) {
            // allow sem.p(arg1, arg2, ...) to override args passed to Semaphore constructor
            if (arguments.length > 0) { parameters = arguments; }
            else { parameters = this.args; }

            this.callback.apply(this.context, parameters);
        }
    }
};

Example of use:

var sem = new Semaphore(function(lastAsync) {
    log(lastAsync + ' completed last');
    log(this);
}, 2, { foo: 'bar', fizz: 'buzz' }, 'Sir not appearing in this callback');

sendChat('', '/roll d20', function(ops) {
    log('Executing first sendChat');
    sem.p('First sendChat call');
});
sendChat('', '/roll d20', function(ops) {
    log('Executing second sendChat');
    sem.p('Second sendChat call');
});

Example output:

"Executing second sendChat"
"Executing first sendChat"
"First sendChat call completed last"
{ foo: "bar", fizz: "buzz" }

Handouts & Characters

Creating a Handout

Because of the way that Handout text blocks are handled, creating a Handout object needs to be done in two steps: First create the object, then set the text blocks:

    //Create a new Handout available to all players
    var handout = createObj("handout", {
                name: "The name of the handout",
                inplayerjournals: "all",
                archived: false
    });
    handout.set('notes', 'Notes need to be set after the handout is created.');
    handout.set('gmnotes', 'GM notes also need to be set after the handout is created.');

Handling Encoding

The text blocks in Handouts (Notes and GM Notes) and Characters (Bio and GM Notes) are that are set through the User Interface are stored in x-www-form-urlencoded format. You can recognize this by the sequence of %## codes throughout the text:

"Erik%20%28Viking%2BScientist%29%20%5BFighter%3A%203%2C%20Wizard%3A%202%5D"

This text can be sent to the chat and will be translated by the browser, but if you need to make changes to the text, you might want to deal with it as it was entered:

"Erik (Viking+Scientist) [Fighter: 3, Wizard: 2]"

You can decode the encoded text with the following function:

var decodeUrlEncoding = function(t){
  return t.replace(
        /%([0-9A-Fa-f]{1,2})/g,
        function(f,n){
            return String.fromCharCode(parseInt(n,16));
        }
    );
}

Utility Functions

Utility functions complete common tasks that you may want to use throughout many scripts. If you place a function at the outermost scope of a script tab, that function should be available to all of your scripts, reducing your overhead. Below is a selection of such functions.

decodeEditorText

Dependencies: None

The in-game text editor is pretty nice, but comes with a problem for API Scripts that depend on reading information from one of the large text areas in the data set. This function helps with that.

Given the text from a Graphic's gmnotes property, or a Character's bio or gmnotes property, or a Handout's notes or gmnotes property, this will return a version with the auto-inserted editor formatting stripped out.

const decodeEditorText = (t, o) =>{
  let w = t;
  o = Object.assign({ separator: '\r\n', asArray: false },o);
  /* Token GM Notes */
  if(/^%3Cp%3E/.test(w)){
    w = unescape(w);
  }
  if(/^<p>/.test(w)){
    let lines = w.match(/<p>.*?<\/p>/g)
      .map( l => l.replace(/^<p>(.*?)<\/p>$/,'$1'));
    return o.asArray ? lines : lines.join(o.separator);
  }
  /* neither */
  return t;
};

The first argument is the text to process.

const text = decodeEditorText(token.get('gmnotes'));

By default, the lines of text will be separated by \r\n.

The optional second argument is an object with options.

• separator -- specifies what to separate lines of text with. Default: \r\n

const text = decodeEditorText(token.get('gmnotes'),{separator:'<BR>'});

• asArray -- specifies to instead return the lines as an array. Default: false

const text = decodeEditorText(token.get('gmnotes'),{asArray:true});

NOTE: Nested <p> tags will confuse and break the decoding. If you run into that problem and need help, PM The Aaron and he'll be happy to look at it.

getCleanImgsrc

Dependencies: None

Given an image URL taken from a token or other resource, get a clean version of it that can be used to create a token via the API, or undefined if it cannot be created by the API.

var getCleanImgsrc = function (imgsrc) {
   var parts = imgsrc.match(/(.*\/images\/.*)(thumb|med|original|max)([^\?]*)(\?[^?]+)?$/);
   if(parts) {
      return parts[1]+'thumb'+parts[3]+(parts[4]?parts[4]:`?${Math.round(Math.random()*9999999)}`);
   }
   return;
};

Note: The API is only capable of creating images whose source is located in a user library. The imgsrc must also be the thumb version of the image.

getSenderForName

Dependencies: None

Given a string name, this function will return a string appropriate for the first parameter of sendChat. If there is a character that shares a name with a player, the player will be used. You may also pass an options object, which is structured identically to the options parameter of findObjs.

function getSenderForName(name, options) {
    var character = findObjs({
            type: 'character',
            name: name
        }, options)[0],
        player = findObjs({
            type: 'player',
            displayname: name.lastIndexOf(' (GM)') === name.length - 5 ? name.substring(0, name.length - 5) : name
        }, options)[0];
    
    if (player) {
        return 'player|' + player.id;
    }
    if (character) {
        return 'character|' + character.id;
    }
    return name;
}

getWhisperTarget

Dependencies: levenshteinDistance

Given a set of options, this function tries to construct the /w name portion of a whisper for a call to sendChat. The options parameter should contain either player: true or character: true and a value for either id or name. Players are preferred over characters if both are true, and ids are preferred over names if both have a valid value. If a name is supplied, the player or character with the name closest to the supplied string will be sent the whisper.

options is technically optional, but if you omit it (or don't supply a combination of player/character + id/name), the function will return an empty string.

function getWhisperTarget(options) {
    var nameProperty, targets, type;
    
    options = options || {};
    
    if (options.player) {
        nameProperty = 'displayname';
        type = 'player';
    } else if (options.character) {
        nameProperty = 'name';
        type = 'character';
    } else {
        return '';
    }
    
    if (options.id) {
        targets = [getObj(type, options.id)];
        
        if (targets[0]) {
            return '/w ' + targets[0].get(nameProperty).split(' ')[0] + ' ';
        }
    }
    if (options.name) {
        // Sort all players or characters (as appropriate) whose name *contains* the supplied name,
        // then sort them by how close they are to the supplied name.
        targets = _.sortBy(filterObjs(function(obj) {
            if (obj.get('type') !== type) return false;
            return obj.get(nameProperty).indexOf(options.name) >= 0;
        }), function(obj) {
            return Math.abs(levenshteinDistance(obj.get(nameProperty), options.name));
        });
        
        if (targets[0]) {
            return '/w ' + targets[0].get(nameProperty).split(' ')[0] + ' ';
        }
    }
    
    return '';
}

processInlinerolls

This function will scan through msg.content and replace inline rolls with their total result. This is particularly useful for API commands to which the user may want to pass inline rolls as parameters.

function processInlinerolls(msg) {
    if (_.has(msg, 'inlinerolls')) {
        return _.chain(msg.inlinerolls)
                .reduce(function(previous, current, index) {
                    previous['$[[' + index + ']]'] = current.results.total || 0;
                    return previous;
                },{})
                .reduce(function(previous, current, index) {
                    return previous.replace(index, current);
                }, msg.content)
                .value();
    } else {
        return msg.content;
    }
}

Here is a slightly more complicated version which also handles converting tableItems to their text:

function processInlinerolls(msg) {
	if(_.has(msg,'inlinerolls')){
		return _.chain(msg.inlinerolls)
		.reduce(function(m,v,k){
			var ti=_.reduce(v.results.rolls,function(m2,v2){
				if(_.has(v2,'table')){
					m2.push(_.reduce(v2.results,function(m3,v3){
						m3.push(v3.tableItem.name);
						return m3;
					},[]).join(', '));
				}
				return m2;
			},[]).join(', ');
			m['$[['+k+']]']= (ti.length && ti) || v.results.total || 0;
			return m;
		},{})
		.reduce(function(m,v,k){
			return m.replace(k,v);
		},msg.content)
		.value();
	} else {
		return msg.content;
	}
}

statusmarkersToObject

The inverse of objectToStatusmarkers; transforms a string suitable for use as the value of the statusmarkers property of a Roll20 token object into a plain old JavaScript object.

Note that a statusmarker string can contain duplicate statusmarkers, while an object cannot contain duplicate properties.

function statusmarkersToObject(stats) {
    return _.reduce(stats.split(/,/), function(memo, value) {
        var parts = value.split(/@/),
            num = parseInt(parts[1] || '0', 10);

        if (parts[0].length) {
            memo[parts[0]] = Math.max(num, memo[parts[0]] || 0);
        }

        return memo;
    }, {});
}

objectToStatusmarkers

The inverse of statusmarkersToObject; transforms a plain old JavaScript object into a comma-delimited string suitable for use as the value of the statusmarkers property of a Roll20 token object.

Note that a statusmarker string can contain duplicate statusmarkers, while an object cannot contain duplicate properties.

function objectToStatusmarkers(obj) {
    return _.map(obj, function(value, key) {
                return key === 'dead' || value < 1 || value > 9 ? key : key + '@' + parseInt(value);
            })
            .join(',');
}

Underscore.js

Main Page: API:Cookbook/Underscore.js

The Underscore.js website is more of an API reference than a guide to using the library. While useful for looking up what functions are available and what parameters they accept, it doesn't help someone trying to break into using the library's power to its fullest extent.

This article is a stub. You can help the Roll20 Community Wiki by expanding it.

Collections

Writing scripts often involves doing something to a collection of things. When we talk about collections, they can either be arrays: var foo = [0,1,10,"banana"]; or objects: var bar = { one: 1, two: 2, banana: 'fruit' };. Arrays are indexed by numbers (usually starting from 0 and counting up), objects have properties which can be used for indexes: bar['banana'] === 'fruit'; // true!. Objects effectively act like associative arrays from other languages.

Sample Data

// Sample Array:
var foo = [0,1,10,"banana"];

// Sample Object
var bar = { one: 1, two: 2, banana: 'fruit' };

Calling a function with Each Element [ _.each() ]

It's very common to need to perform some operation with each element of a collection. Usually people will use for loops or similar. Underscore provides _.each(), a way to call a function with each element of a collection as the argument.

_.each(foo, function(element){
  log('element is '+element);
});

"element is 0"
"element is 1"
"element is 10"
"element is banana"

What makes this so powerful is that the identical code works regardless of whether you are using an array or object:

_.each(bar, function(element){
  log('element is '+element);
});

"element is 1"
"element is 2"
"element is fruit"

Functions do not need to be inline. They also receive additional parameters. (See documentation fore even more parameters.):

var logKeyValueMapping = function( value, key ) {
    log(key + " :: " + value);
};

log("An Array:");
_.each(foo, logKeyValueMapping);

log("An Object:");
_.each(bar, logKeyValueMapping);

"An Array:"
"0 :: 0"
"1 :: 1"
"2 :: 10"
"3 :: banana"
"An Object:"
"one :: 1"
"two :: 2"
"banana :: fruit"

Transforming Each Element [ _.map() ]

The next most common thing to do with a collection is to transform all of the contained items into items of another type. Often people might do this by making another collection, then using a for loop to iterate across the first collection, transforming the value and pushing it into the new container. That's a lot of code that can be simplified with Underscore's _.map(), a way to apply a function across a collection of elements and get a collection of the results. If that sounds similar to _.each(), that's because it is, in fact, it has the same signature.

var res = _.map(foo, function(element){
  return 'element is '+element;
});
log(res);

"['element is 0','element is 1','element is 10','element is banana']"

The return of _.map() is always an array of the results (see #Converting Collections below for getting objects.) and just like _.each(), the function gets more arguments and can be separately defined.

var  getKeyValueMapping = function( value, key ) {
    return key + " :: " + value;
};

log("An Array:");
var resA = _.map(foo, getKeyValueMapping);
log(resA);

log("An Object:");
var resB_.map(bar, getKeyValueMapping);
log(resB);

"An Array:"
"['0 :: 0', '1 :: 1', '2 :: 10', '3 :: banana']"
"An Object:"
"['one :: 1', 'two :: 2', 'banana :: fruit']"

Converting Collections [ _.reduce() ]