Hey everyone,
You may have seen our blog post recently announcing some major changes to the Mod Scripts (aka API Scripts) system that are coming this March: https://blog.roll20.net/posts/roll20-mod-scripts-set-for-major-improvements-in-march/
As you may have heard, our very own TheAaron has joined the Roll20 team in an official capacity and is leading the charge on these improvements. We wanted to share a more detailed Change Log of these improvements with you so you can get excited and start asking questions ahead of the full launch. These changes are already in internal testing with a small group of script authors in our staging environment, with an eye toward making sure that we are maintaining backward compatibility with existing scripts.
This is the first major update to this system in quite a while, and I'm very excited both to be working with TheAaron and to deliver these improvements to one of the most exciting (to me) parts of the Roll20 Tabletop. Between this and Jumpgate we're shaping up for a very interesting Spring here at Roll20!
General
Better Mod Output Console messages
Whenever possible, output messages will now list one or more context objects.
When calling toBelow(), with a character object, you might see this error:
ERROR: toBelow() must called with a Roll20 graphic, text, or path Object. Called with [Roll20 character -NM0tVij02hIfnoTdihc].
The context object at the end will show That it's a Roll20 character object, and what its id is. That should help with tracking down errors in scripts.
$20
A version of $20 has been added to the API Server to allow characters sheets making use of its functionality in game to still have their sheet workers run without crashing.
Functions
findObjs(properties, options)
You can now specify the option startsWith in order to match strings that start with the specified value:
// get all knight characters
let knights = findObjs({type: "character", name: "Sir"},{startsWith: true});
toFront(obj)
Should perform quite a bit faster now!
toBack(obj)
Should perform quite a bit faster now!
(New!) toAbove(obj,target)
You can use toAbove(obj,target) to place an object on the VTT just above another object in the sorting. target can be a valid Roll20 object on the table top, or the id of such an object.
(New!) toBelow(obj,target)
You can use toBelow(obj,target) to place an object on the VTT just below another object in the sorting. target can be a valid Roll20 object on the table top, or the id of such an object.
spawnFxBetweenPoints(point1, point2, type, pageid)
A bug in the calculation of the angle between the points has been corrected resulting in beam type fx pointing directly at the specified point2.
Objects
Individual Roll20 Objects now have more capabilities.
.type
Objects now support a property of .type similar to .id. This is identical
to calling obj.get('type') or obj.get('_type'), but now it's even easier.
if('graphic' === obj.type) {
// do something
}campaign
Campaign has two properties on it that can be accessed by scripters:
sheetName— this is the shortname of the currently configured character sheet.nodeVersion— this is the version number for the node backend the API Server is running on.
(New!) pageFolder
The pageFolder object represents page folders in the new page menu. pageFolders have the following properties:
prop | default | note
-----------|--------------|-----
_id | | A unique ID like other Roll20 Objects have.
_type | "pageFolder" | The type for pageFolder.
name | "New Folder" | A freeform text name for the folder, which shows up in the page menu.
_placement | 0 | A positive integer value that is used for ordering items in the page menu.
_path | "," | A comma delimited list of ids representing the path of pageFolders where this pageFolder is stored.
There are new functions for adjusting the page hierarchy:
placeBefore(obj)— Adjusts the_placementof thispageFolderto be immediately before the specified object in the page menu.objmust be apageorpageFolder. This may cause_pathto change if they are at different levels in the hierarchy of the page menu.placeAfter(obj)— Adjusts the_placementof thispageFolderto be immediately after the specified object in the page menu.objmust be apageorpageFolder. This may cause_pathto change if they are at different levels in the hierarchy of the page menu.placeIn(obj)— Adjusts the location of thepageFolderto be in the specifiedobjat the very end of the contents.objmust be apageFolder. This will likely cause_placementto change.
page
The page object has been expanded to support the new page menu with the following new properties and functions:
prop | default | note
-----------|--------------|-----
_placement | 0 | A positive integer value that is used for ordering items in the page menu.
_path | "," | A comma delimited list of ids representing the path of pageFolders where this page is stored.
There are new functions for adjusting the page hierarchy:
placeBefore(obj)— Adjusts the_placementof thispageto be immediately before the specified object in the page menu.objmust be apageorpageFolder. This may cause_pathto change if they are at different levels in the hierarchy of the page menu.placeAfter(obj)— Adjusts the_placementof thispageto be immediately after the specified object in the page menu.objmust be apageorpageFolder. This may cause_pathto change if they are at different levels in the hierarchy of the page menu.placeIn(obj)— Adjusts the location of thepageto be in the specifiedobjat the very end of the contents.objmust be apageFolder. This will likely cause_placementto change.
Additionally, the following properties have been exposed to provide access to the wrapper color that shows around the border of a page:
prop | default | note
------------------|--------------|-----
_wrapperAutoColor | #ffffff | This is the calculated color that hows up based on what graphics are visible on the table top.
useAutoWrapper | true | When this is true, the wrapper color will be the value of _wrapperAutoColor. When it is false, the value in wrapperColor is used instead.
wrapperColor | "" | This is a color that will be used for the wrapper color with useAutoWrapper is false.
graphic
The graphic object has several new functions, and a new behavior for one of it's properties
prop | default | note
------------|--------------|-----
currentSide | 0 | Setting currentSide will now automatically update the imgsrc of a graphic, including switching to Marketplace Images. If you are also setting imgsrc with the same call to .set(), the specified imgsrc will be used instead as long as it is valid.
- (New!)
createCopy(properties)— This function will make a copy of the graphic object as if you passed its properties tocreateObj(). This will allow creating duplicates of Marketplace Images both within theimgsrcandsidesproperties. The newgraphicobject is returned from the function. - (New!)
toFront()— This is identical the passing this object to the globaltoFront(obj)function. - (New!)
toBack()— This is identical the passing this object to the globaltoBack(obj)function. - (New!)
toAbove(target)— This is identical the passing this object to the globaltoAbove(obj,target)function.targetcan be an object on the tabletop, or the ID of such an object. - (New!)
toBelow(target)— This is identical the passing this object to the globaltoBelow(obj,target)function.targetcan be an object on the tabletop, or the ID of such an object.
character
The character object has a new property and a new function.
prop | default | note
------------|--------------|-----
tags | "[]" | This is a JSON encoded array of strings. Valid tags are any string which does not contain whitespace or commas. Invalid tags will be stripped on set and a warning message will be sent to the Mod Output Console.
- (New!)
createToken(properties, options, callback)— This function will create agraphicobject using the_defaulttokenfor the character as a base. If there is no_defaulttoken, theavatarimage from the character will be used. If there is noavatarimage, creation of thegraphicwill fail. This allows the creation ofgraphicswith Marketplace Images. Because getting the_defaulttokenis asynchronous, the createdgraphiccan not be returned directly, but is instead passed to the suppliedcallbackfunction, if it exists.optionsis a JavaScript object with the following optional properties:
prop | default | note
-------------|--------------|-----
preferAvatar | false | When true, the created graphic will use the avatar image as its imgsrc. If there is no avatar image, it will fall back on the imgsrc in the _defaulttoken.
multisided | false | This determines how the sides property of the graphic is configured. See below.
- Multisided determines how the
sidesproperty of thegraphicis constructed or manipulated when thegraphicis created.
multisided option | effect
-----------------------|-------------------
false or undefined | No changes are made to the sides property of the created graphic. If the _defaulttoken has sides, they will be set, otherwise it will be empty.
true or ensure | If the _defaulttoken does not have sides set, sides will be set to imgsrc,avatar and currentSide will be set based on preferAvatar.
replace | As ensure, but will overwrite the sides from the _defaulttoken.
append | Adds imgsrc,avatar to the end of the sides from _defaulttoken. currentSide will be set to point to the index of imgsrc or avatar depending on preferAvatar.
prepend | Adds imgsrc,avatar to the beginning of the sides from _defaulttoken. currentSide will be set to point to the index of imgsrc or avatar depending on preferAvatar.
handout
The handout object has a new property.
prop | default | note
------------|--------------|-----
tags | "[]" | This is a JSON encoded array of strings. Valid tags are any string which does not contain whitespace or commas. Invalid tags will be stripped on set and a warning message will be sent to the Mod Output Console.
card
The card object has a new property and a new function.
prop | default | note
------------|--------------|-----
card_back | "" | This is an alternate card back used for this specific card.
- (New!)
createToken(properties, options)— This function will create agraphicobject as if the card had been drawn and played to the table top. This allows the creation ofgraphicobjects with Marketplace Images. The createdgraphicobject is returned by the function.
prop | default | note
-------------|----------------|-----
asCard | true | If true, the graphic object will be a card with a card_id and relationship to the deck it comes from. If false, it will be a multisided token that looks like the card but can't be "picked up", "discarded", etc.
faceup | (deck default) | This determines if the graphic is created with the face or back showing. currentSide will be set appropriately.
rollabletable
The rollabletable object has a new function.
- (New!)
createToken(properties)— This function will create agraphicobject with sides taken from therollabletable. This allows the creation ofgraphicobjects with Marketplace Images. The createdgraphicobject is returned by the function. If none of thetableitemobjects associated with thisrollabletablecontain anavatar, nographicis created.
path
The path object has some new functions.
- (New!)
toFront()— This is identical the passing this object to the globaltoFront(obj)function. - (New!)
toBack()— This is identical the passing this object to the globaltoBack(obj)function. - (New!)
toAbove(target)— This is identical the passing this object to the globaltoAbove(obj,target)function.targetcan be an object on the tabletop, or the ID of such an object. - (New!)
toBelow(target)— This is identical the passing this object to the globaltoBelow(obj,target)function.targetcan be an object on the tabletop, or the ID of such an object.
text
The text object has some new functions.
- (New!)
toFront()— This is identical the passing this object to the globaltoFront(obj)function. - (New!)
toBack()— This is identical the passing this object to the globaltoBack(obj)function. - (New!)
toAbove(target)— This is identical the passing this object to the globaltoAbove(obj,target)function.targetcan be an object on the tabletop, or the ID of such an object. - (New!)
toBelow(target)— This is identical the passing this object to the globaltoBelow(obj,target)function.targetcan be an object on the tabletop, or the ID of such an object.
