Great points. We really should rename it to something more appropriate. This is a case of the development name seeping over into the public eye. I need to rework the documentation, but I'll post some of what is new in Experimental below. Some callouts I'd make are the ability to place a canvas object directly above or below another canvas object, being able to create graphic objects from characters, rollable tables, and existing graphics directly (with Marketplace content if it's already there), sorting and organizing pages in folders, currentside property on graphics changes the image correctly, tag support for characters and handouts, etc. Ulti said: Also, could I find somewhere the differences between the exprimental ad the default sandbox? I must say the the word "experimental" is not very reassuring, for something that could affect my whole game... I would only use that to experiment, not on actual games. 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! toAbove(obj,target) [ New! ] 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. toBelow(obj,target) [ New! ] 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 . getComputed({ characterId, property, args?, playerId? }) When using a Beacon character sheet, gets the value of a computed property.
You can get a list of available computed attributes with Campaign().computedSummary .
Player id is optional, but some Beacon functionality (example, roll queries) requires it. setComputed({ characterId, property, args?, playerId? }) When using a Beacon character sheet, sets the value of a writeable computed property.
You can get a list of available computed attributes with Campaign().computedSummary .
Player id is optional, but some Beacon functionality (example, roll queries) requires it. performAction({ characterId, action, args?, playerId? }) When using a Beacon character sheet, performs a sheet action.
You can get a list of available actions with Campaign().actionSummary .
Player id is optional, but some Beacon functionality (example, roll queries) requires it. 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. computedSummary -- When using a Beacon sheet, this is a list of available computed attributes actionSummary -- When using a Beacon sheet, this is a list of available sheet actions pageFolder [ New! ] 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 pageFolder s 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 pageFolder s 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 its 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. const setRandomSide = (obj) => {
if('graphic' === obj.type){
obj.set({
currentSide: randomInteger(obj.get('sides')?.split(/|/).length??1)-1
});
}
}; createCopy(properties) [ New! ] -- 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. const teleport = (obj,pageid,layer,x,y) => {
if(obj?.type === 'graphic'){
obj.createCopy({pageid,layer,left:x,top:y});
}
}; toFront() [ New! ] -- This is identical the passing this object to the global toFront(obj) function. let boom = createFireball();
boom?.toBack(); toBack() [ New! ] -- This is identical the passing this object to the global toBack(obj) function. let mist = createFogCloud();
mist?.toFront(); toAbove(target) [ New! ] -- 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. let rider = getRider();
let house = getHorse();
rider?.toAbove(horse); toBelow(target) [ New! ] -- 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. let rider = getRider();
let house = getHorse();
horse?.toBelow(rider); 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. createToken(properties, options, callback) [ New! ] -- 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 . const spawn = (obj,pageid,layer,x,y)=>{
if(obj?.type === 'character'){
obj.createToken({pageid,layer,left:x,top:y},{multisided:'ensure'},(token)=>{
token.set('status_green':5);
});
}
}; 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. createToken(properties, options) [ New! ] -- 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. createToken(properties) [ New! ] -- 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. toFront() [ New! ] -- This is identical the passing this object to the global toFront(obj) function. toBack() [ New! ] -- This is identical the passing this object to the global toBack(obj) function. toAbove(target) [ New! ] -- 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. toBelow(target) [ New! ] -- 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. toFront() [ New! ] -- This is identical the passing this object to the global toFront(obj) function. toBack() [ New! ] -- This is identical the passing this object to the global toBack(obj) function. toAbove(target) [ New! ] -- 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. toBelow(target) [ New! ] -- 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.
