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_placement
of thispageFolder
to be immediately before the specified object in the page menu.obj
must be apage
orpageFolder
. This may cause_path
to change if they are at different levels in the hierarchy of the page menu.placeAfter(obj)
— Adjusts the_placement
of thispageFolder
to be immediately after the specified object in the page menu.obj
must be apage
orpageFolder
. This may cause_path
to change if they are at different levels in the hierarchy of the page menu.placeIn(obj)
— Adjusts the location of thepageFolder
to be in the specifiedobj
at the very end of the contents.obj
must be apageFolder
. This will likely cause_placement
to 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_placement
of thispage
to be immediately before the specified object in the page menu.obj
must be apage
orpageFolder
. This may cause_path
to change if they are at different levels in the hierarchy of the page menu.placeAfter(obj)
— Adjusts the_placement
of thispage
to be immediately after the specified object in the page menu.obj
must be apage
orpageFolder
. This may cause_path
to change if they are at different levels in the hierarchy of the page menu.placeIn(obj)
— Adjusts the location of thepage
to be in the specifiedobj
at the very end of the contents.obj
must be apageFolder
. This will likely cause_placement
to 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 theimgsrc
andsides
properties. The newgraphic
object 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.target
can 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.target
can 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 agraphic
object using the_defaulttoken
for the character as a base. If there is no_defaulttoken
, theavatar
image from the character will be used. If there is noavatar
image, creation of thegraphic
will fail. This allows the creation ofgraphics
with Marketplace Images. Because getting the_defaulttoken
is asynchronous, the createdgraphic
can not be returned directly, but is instead passed to the suppliedcallback
function, if it exists.options
is 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
sides
property of thegraphic
is constructed or manipulated when thegraphic
is 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 agraphic
object as if the card had been drawn and played to the table top. This allows the creation ofgraphic
objects with Marketplace Images. The createdgraphic
object 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 agraphic
object with sides taken from therollabletable
. This allows the creation ofgraphic
objects with Marketplace Images. The createdgraphic
object is returned by the function. If none of thetableitem
objects associated with thisrollabletable
contain anavatar
, nographic
is 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.target
can 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.target
can 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.target
can 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.target
can be an object on the tabletop, or the ID of such an object.