Latest revision as of 14:15, 4 January 2022

ESRO (Extended Syntax Roll20 Objects) wraps normal Roll20 objects (the return values from functions like getObj and findObjs, for example) in order to expand their capabilities. Depending on useroptions selected, it will also overwrite a number of existing Roll20 functions in order to facilitate the use of these wrapped objects.

[edit] Useroptions

ESRO can overwrite nine different Roll20 functions. The useroptions let you disable that capability on a per-function basis:

• getObj
• Campaign
• findObjs
• filterObjs
• getAllObjs
• createObj
• on
• toFront
• toBack

[edit] Syntax

By and large, you do not need to change any of your code in order to get wrapped objects. If all of the script's useroptions are enabled, in fact, every single Roll20 object you get will already be wrapped! That said, you may desire direct access to the new version of a function (if you're not overwriting it by default), or direct access to the original version of a function (if you are overwriting it). All of these can be found in the bshields.esro object:

// New versions of functions
bshields.esro.getObj(type, id)
bshields.esro.Campaign()
bshields.esro.findObjs(attrs, options)
bshields.esro.filterObjs(predicate)
bshields.esro.getAllObjs()
bshields.esro.createObj(type, attrs)
bshields.esro.on(event, callback)
bshields.esro.toFront(obj)
bshields.esro.toBack(obj)

// Original versions of functions
bshields.esro.r20.getObj(type, id)
bshields.esro.r20.Campaign()
bshields.esro.r20.findObjs(attrs, options)
bshields.esro.r20.filterObjs(predicate)
bshields.esro.r20.getAllObjs()
bshields.esro.r20.createObj(type, attrs)
bshields.esro.r20.on(event, callback)
bshields.esro.r20.toFront(obj)
bshields.esro.r20.toBack(obj)

[edit] Load Order Matters!

Roll20 API scripts execute in order. That means an on('ready', ...) event of one script will complete before the same event in another script, depending on the relative order of the two tabs in the API Scripts page of your campaign. This matters for the ESRO script, because it cannot overwrite any functions until its ready event fires. If you are depending on ESRO overwriting the on function, or any function that is not a level deep from your ready event, your script must load after ESRO:

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

[edit] Wrapped Objects

The primary benefit of wrapped objects is to give direct access to property values, instead of requiring the use of get and set functions. Compare the following lines:

// Works with or without ESRO
token.set('left', token.get('left') + 70);

// Only works with ESRO
token.left = token.left + 70;
token.left += 70;

Please note that if you are using the original version of the toFront or toBack functions (whether because you've disabled overwriting them with useroptions, or because you are accessing them directly from bshields.esro.r20), you cannot pass an ESRO to them; you must unwrap it: toFront(myEsro.unwrap()). If you are using the overwritten versions of these two functions, however, you can pass either an ESRO or a normal (unwrapped) Roll20 object.

You can also wrap objects manually with the bshields.esro.wrap(obj) function. Assuming no other script has defined it, you can simply use wrap(obj) as a shorthand version of the same.

[edit] notes, gmnotes, and bio Properties for Characters and Handouts

Getting the value of these properties is an asynchronous operation. As such, you must call these properties like a function, instead of treating them like a value. For example:

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

[edit] Changelog

v0.1 (2016-04-24)

• Release