Extended Syntax Roll20 Objects

Extends the syntax for Roll20 objects for use in scripts. This script is not intended to stand alone.

Overridden Functions

Each function you set to be overridden will have the normal Roll20 library function overridden with a custom version in this script's ready event. Any code executed by other scripts prior to this script's ready function completing will not benefit from the change. This is most relevant if you want to make use of the overridden on function, or use other functions inside another script's ready event. Using other overridden functions inside an event other than ready which are themselves bound within a ready event is guaranteed to function as expected regardless of script load order. For example:

// Will not be the overridden `on` function if loaded before ESRO
on('ready', function() {
    // Will not be the overridden `on` function if loaded before ESRO
    on('change:graphic', function(obj, prev) {
        // Guaranteed to be the overridden `getObj` function regardless of load order
        var character = getObj('character', obj.get('represents'));
        ...
    });
});

Direct Function Access

You can access the overridden version of a function directly (whether you have it set to be overridden below or not) from the bshields.esro object. For example, bshields.esro.getObj is the new version of getObj. You can also access the original Roll20 library versions of these functions directly in a similar way, through the bshields.esro.r20 object. For example, bshields.esro.r20.getObj is the original version of getObj. Note that bshields.esro is not defined until this script's ready event completes.

What Do These New Functions Do?

The main purpose of these functions is to wrap objects and enhance their functionality. At this time, that specifically means creating properties that are directly accessible. So, instead of writing token.set('left', token.get('left') + 70), you can write token.left = token.left + 70 or even token.left += 70! Please note that if you wish to set multiple properties at once, it is still recommended that you call the set function, eg token.set({ left: xCoord, top: yCoord }). Read-only properties such as _type cannot have their values set, but you can access them with or without the leading underscore.

The modified versions of the object finding and creation functions (getObj, Campaign, findObjs, filterObjs, getAllObjs, and createObj) will all return appropriately wrapped objects; the functions that return arrays will return arrays of wrapped objects. The modified version of the event registering function (on) will pass wrapped objects to the callbacks of appropriate events. The modified versions of the object layering functions (toFront and toBack) will unwrap the object prior to sending it to Roll20's native toFront and toBack functions. Please Note: if you choose not to override toFront and toBack, but you are manipulating wrapped objects (for example, because you're overriding the object finding and/or creation functions), you must call unwrap() when sending the object to either of these ordering functions. If you are overriding the layering functions, the system will correctly handle passing both wrapped and unwrapped objects to them.

notes, gmnotes, and bio Properties for Characters and Handouts

For these properties on a Character or Handout object, the get function is asynchronous. As such, you must call these properties like a function, instead of just treating them like a value. For example:

var system = findObjs({ type: 'character', name: 'System' })[0];
system.bio(function(text) {
    log(text); // Print the System character's bio to the log
});

Functions of Wrapped Objects

In addition to direct property access, there are some functions available to wrapped objects. The list of available functions includes all functions that are normally available to the Roll20 objects (get, set, remove, etc.) even if some (get and set, specifically) are redundant.

toString(minimal): the toString function has been redefined for wrapped objects. Instead of simply outputting "[object Object]", it will attempt to produce the JSON data for the object. In corner cases where that is not possible, or if you provide true as a parameter to the function, it will return "[object Roll20Object -Abc_123]" (using the object's actual id instead of -Abc_123). In corner cases where it is not possible to include the object's id, the return value will simply be "[object Roll20Object]", which at least is still more descriptive than the standard toString.

unwrap(): the unwrap function is available for all wrapped objects to gain access to the original, unwrapped version of the object. This should not be needed under most circumstances, but it is required for toFront and toBack if you are not overwriting them despite using wrapped objects in your script.

Wrapping Objects Yourself

In addition to overwriting existing Roll20 functions to produce wrapped objects, you can wrap a normal Roll20 object manually by calling bshields.esro.wrap(obj). Assuming no other script has already defined it, this script will also create the function wrap as a shorthand to the fully-qualified version, so you can just use wrap(obj). The wrap function will be available regardless of whether you have any or all of the Roll20 functions being overwritten.