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: <a href="https://blog.roll20.net/posts/roll20-mod-scripts-set-for-major-improvements-in-march/" rel="nofollow">https://blog.roll20.net/posts/roll20-mod-scripts-set-for-major-improvements-in-march/</a> 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 this pageFolder to be immediately before the specified object in the page menu. obj must be a page or pageFolder . 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 this pageFolder to be immediately after the specified object in the page menu. obj must be a page or pageFolder . 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 the pageFolder to be in the specified obj at the very end of the contents. obj must be a pageFolder . 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 this page to be immediately before the specified object in the page menu. obj must be a page or pageFolder . 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 this page to be immediately after the specified object in the page menu. obj must be a page or pageFolder . 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 the page to be in the specified obj at the very end of the contents. obj must be a pageFolder . 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 to createObj() . This will allow creating duplicates of Marketplace Images both within the imgsrc and sides properties. The new graphic object is returned from the function. (New!) toFront() — This is identical the passing this object to the global toFront(obj) function. (New!) toBack() — This is identical the passing this object to the global toBack(obj) function. (New!) toAbove(target) — This is identical the passing this object to the global toAbove(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 global toBelow(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 a graphic object using the _defaulttoken for the character as a base. If there is no _defaulttoken , the avatar image from the character will be used. If there is no avatar image, creation of the graphic will fail. This allows the creation of graphics with Marketplace Images. Because getting the _defaulttoken is asynchronous, the created graphic can not be returned directly, but is instead passed to the supplied callback 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 the graphic is constructed or manipulated when the graphic 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 a graphic object as if the card had been drawn and played to the table top. This allows the creation of graphic objects with Marketplace Images. The created graphic 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 a graphic object with sides taken from the rollabletable . This allows the creation of graphic objects with Marketplace Images. The created graphic object is returned by the function. If none of the tableitem objects associated with this rollabletable contain an avatar , no graphic is created. path The path object has some new functions. (New!) toFront() — This is identical the passing this object to the global toFront(obj) function. (New!) toBack() — This is identical the passing this object to the global toBack(obj) function. (New!) toAbove(target) — This is identical the passing this object to the global toAbove(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 global toBelow(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 global toFront(obj) function. (New!) toBack() — This is identical the passing this object to the global toBack(obj) function. (New!) toAbove(target) — This is identical the passing this object to the global toAbove(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 global toBelow(obj,target) function. target can be an object on the tabletop, or the ID of such an object.
