Mod Scripts: Objects

There are several different types of objects that are used throughout Mod Scripts. Here’s a quick listing of each, what it is, and what properties it contains (along with the default values). As a general rule of thumb, properties that begin with an underscore (_) are read-only and cannot be changed. You must access properties on objects using obj.get("property") and set new values using obj.set("property", newvalue) or obj.set({property: newvalue, property2: newvalue2}).

Note: The id property of an object is a globally-unique ID: no two objects should have the same one, even across different types of objects. In addition, since an object’s id is frequently-accessed and never changes, there is a shortcut available where you can access it by using obj.id instead of obj.get("_id") if you wish (either will work).

Mod Script Sandbox v1.5 only. Objects also support obj.type, equivalent to obj.get("type") or obj.get("_type").

if ('graphic' === obj.type) {
  // do something
}

Pathv2 (Available on the Latest VTT Engine)

Property	Default Value	Notes
_id		A unique ID for this object. Globally unique across all objects in this game. Read-only.
_type	"pathv2"	Can be used to identify the object type or search for the object. Read-only.
_pageid		ID of the page the object is in. Read-only.
shape	""	pol, free, eli, or rec Determines if the path is displayed as a polyline, freehand, ellipse, or rectangle.
points		A JSON string containing and array of x,y points used to create the path.
fill	"transparent"	Fill color. Use the string transparent or a hex color as a string, for example #000000
stroke	"#000000"	Stroke (border) color.
rotation	0	Rotation (in degrees).
layer	""	Current layer, one of gmlayer, objects, map, walls, or foreground. Paths on the walls layer block light.
stroke_width	5
y	0	Y-coordinate for the center of the path
x	0	X-coordinate for the center of the path
controlledby	""	Comma-delimited list of player IDs who can control the path. Controlling players may delete the path. If the path was created by a player, that player is automatically included in the list. All Players is represented by having all in the list.
barrierType	"wall"	Dynamic Lighting Barrier type options include wall, oneWay, and transparent
oneWayReversed	false	boolean
fadeOnOverlap	true	When true, the overlapping of a object layer graphic’s inner bound with the foreground layer object will cause its opacity to become the value in fadeOpacity. When false, it will remain at full opacity regardless of overlap
fadeOpacity	0.3	This value dictates the opacity of the object when it is overlapped by a graphic on the object layer, and fadeOnOverlap is set to true
renderAsScenery	false	When true, this object will be obscured by dynamic lighting and the Hide/Reveal Mask
interactionManualReset	false	When this is set to true it will reset interactions on the object
interactionTriggered	false	Will get set to true when an interaction is triggered

The shape property has the following values:

• pol- Polyline. A straight line is drawn between each consecutive point. If the starting point and ending point are the same, it creates a closed shape.
• free- Freehand. A curve is drawn using the points as guides. If the starting point and ending point are the same, it creates a closed shape.
• eli - Ellipse. An ellipse is draw using the points to set a bounding box. Only the first two points are used.
• rec - Rectangle. A rectangle is draw using the points to set a bounding box. Only the first two points are used.

The points property is a JSON string containing an array of points. Points are represented as a two position array of an x and y location. A triangle from (0,0) to (0,70) to (70,0), and back to (0,0) would be represented as [[0,0],[0,70],[70,0],[0,0]]. The x and y properties position the PathV2 object on the page. They specify where the center of the drawing should be. For some shapes (ellipses and rectangles), that is pretty easy to figure out. For more complex shapes (polylines and freehands), you will need to find the minimum and maximum values from the points property and use the point equidistant between them.

Mod Script Sandbox v1.5 only. Instance methods: toFront(), toBack(), toAbove(target), toBelow(target). target may be a graphic, text, path, or pathv2 object, or the id of such an object.

Path (Classic Tabletop)

Property	Default Value	Notes
_id		A unique ID for this object. Globally unique across all objects in this game. Read-only.
_type	"path"	Can be used to identify the object type or search for the object. Read-only.
_pageid		ID of the page the object is in. Read-only.
_path		JSON array of drawing commands. Each command is ["M", x, y] or ["L", x, y] (move or line), or ["C", ...] for a curve. x and y are offsets from the path’s top-left. Pass path when creating. Read-only afterward.
fill	"transparent"	Fill color. Use the string transparent or a hex color as a string, for example #000000
stroke	"#000000"	Stroke (border) color.
rotation	0	Rotation (in degrees).
layer	""	Current layer, one of gmlayer, objects, map, walls, or foreground. Paths on the walls layer block light.
stroke_width	5
width	0
height	0
top	0	Y-coordinate for the center of the path
left	0	X-coordinate for the center of the path
scaleX	1
scaleY	1
controlledby	""	Comma-delimited list of player IDs who can control the path. Controlling players may delete the path. If the path was created by a player, that player is automatically included in the list. All Players is represented by having all in the list.
barrierType	"wall"	Dynamic Lighting Barrier type options include wall, oneWay, and transparent
oneWayReversed	false	boolean
fadeOnOverlap	true	When true, the overlapping of a object layer graphic’s inner bound with the foreground layer object will cause its opacity to become the value in fadeOpacity. When false, it will remain at full opacity regardless of overlap
fadeOpacity	0.3	This value dictates the opacity of the object when it is overlapped by a graphic on the object layer, and fadeOnOverlap is set to true
renderAsScenery	false	When true, this object will be obscured by dynamic lighting and the Hide/Reveal Mask
interactionManualReset	false	When this is set to true it will reset interactions on the object
interactionTriggered	false	Will get set to true when an interaction is triggered

Pass path (stored as _path) when creating a classic path. The format is described on the _path row above.

Mod Script Sandbox v1.5 only. Instance methods: toFront(), toBack(), toAbove(target), toBelow(target). target may be a graphic, text, path, or pathv2 object, or the id of such an object.

Window

Note: Window and Door use an inverted axis compared to other types of objects. For instance, a top variable that would be 100 for another object is y -100 for window or door.

Property	Default Value	Notes
_id		A unique ID for this object. Globally unique across all objects in this game. Read-only.
_type	"window"	Read-only.
_pageid		Page this window belongs to. Pass pageid when creating. Read-only afterward.
color	"#ff0000"	A hexadecimal color of the window.
x	0	Coordinate center of the window on the x axis.
y	0	Coordinate center of the window on the y axis.
isOpen	false	Determines whether a player can move through this window.
isLocked	false	Prevents players from being able to interact with the window.
path		Two handles, handle0 and handle1, each with x and y. Those coordinates are offsets from this object’s x/y, in the same inverted y-axis.

Example

on('chat:message', function(msg) {
  if (msg.type === 'api' && msg.content === '!cw') {
    const currentPageID = Campaign().get('playerpageid');
    const win = createObj('window', {
      x: 70,
      y: -70,
      pageid: currentPageID,
      path: {
        handle0: {
          x: -70,
          y: 0,
        },
        handle1: {
          x: 35,
          y: 0,
        },
      },
      color: '#000000'
    });
  }
  if (msg.type === 'api' && msg.content === '!mw') {
    const win = getObj('window', '-NG38yUgghBBoV8YR0y1');
    win.set({
      x: 240,
      y: -139
    });
  }
  if (msg.type === 'api' && msg.content === '!dw') {
    const win = getObj('window', '-NG38yUgghBBoV8YR0y1');
    win.remove();
  }
});

Door

Note: Window and Door use an inverted axis compared to other types of objects. For instance, a top variable that would be 100 for another object is y -100 for window or door.

Property	Default Value	Notes
_id		A unique ID for this object. Globally unique across all objects in this game. Read-only.
_type	"door"	Read-only.
_pageid		Page this door belongs to. Pass pageid when creating. Read-only afterward.
color	""	A hexadecimal color of the door.
x	0	Coordinate center of the door on the x axis.
y	0	Coordinate center of the door on the y axis.
isOpen	false	Determines whether a player can move through this door.
isLocked	false	Prevents players from being able to interact with the door.
isSecret	false	Removes a door icon from player view and functions as a barrier.
path		Two handles, handle0 and handle1, each with x and y. Those coordinates are offsets from this object’s x/y, in the same inverted y-axis.

Text

Property	Default Value	Notes
_id		A unique ID for this object. Globally unique across all objects in this game. Read-only.
_type	"text"	Can be used to identify the object type or search for the object. Read-only.
_pageid		ID of the page the object is in. Read-only.
top	0
left	0
width	0
height	0
text	""
font_size	16	For best results, stick to the preset sizes in the editing menu: 8, 10, 12, 14, 16, 18, 20, 22, 26, 32, 40, 56, 72, 100, 200, 300.
rotation	0
color	"rgb(0, 0, 0)"
stroke	"transparent"
font_family	"Arial"	If this is not set, when later changing the value of the text property the font_size will shrink to 8. Possible values (Case is not important): Arial, Patrick Hand, Contrail One, Shadows Into Light, and Candal. Specifying an invalid name results in an unnamed, monospaced serif font being used.
layer	""	Current layer, one of gmlayer, objects, map, walls, or foreground.
controlledby	""	Comma-delimited list of player IDs who can control the text. Controlling players may delete the text. If the text was created by a player, that player is automatically included in the list. All Players is represented by having all in the list.
fadeOnOverlap	true	When true, the overlapping of a object layer graphic’s inner bound with the foreground layer object will cause its opacity to become the value in fadeOpacity. When false, it will remain at full opacity regardless of overlap
fadeOpacity	0.3	This value dictates the opacity of the object when it is overlapped by a graphic on the object layer, and fadeOnOverlap is set to true
renderAsScenery	false	When true, this object will be obscured by dynamic lighting and the Hide/Reveal Mask
interactionManualReset	false	When this is set to true it will reset interactions on the object
interactionTriggered	false	Will get set to true when an interaction is triggered

Mod Script Sandbox v1.5 only. Instance methods: toFront(), toBack(), toAbove(target), toBelow(target). target may be a graphic, text, path, or pathv2 object, or the id of such an object.

Pins

The pin object represents Map Pins, interactive markers that appear directly on the map. Pins can display images, show tooltips, contain GM notes, and can be linked to handouts in your journal. They can be visible or hidden, allowing for dramatic reveals, shedding light on a discovered location, or can be used as information markers for more interactive play. Additional information on pins can be found in the Help Center.

Property	Default Value	Notes
_id		A unique ID like other Roll20 Objects have. Read-only.
_type	"pin"	The type for pin. Read-only.
_pageid	""	The ID of the page this pin belongs to. Read-only.
x	0	The X coordinate of the pin on the page.
y	0	The Y coordinate of the pin on the page.
bgColor	"#242424"	Pin background color (hex or transparent). Supports HTML color strings of either #RRGGBB or #RRGGBBAA (translucence)
shape	"teardrop"	Pin shape. Valid values are teardrop, circle, diamond, square
icon	"base-dot"	Built-in icon when customizationType is icon
pinImage	""	Image URL shown when customizationType is image
customizationType	"icon"	Determines whether the pin displays the icon or the pinImage. Set pinImage to a valid image URL when using customizationType: image. Toggling customizationType between icon and image does not clear pinImage; the URL is preserved
useTextIcon	false	When useTextIcon is true, the pin displays a text label instead of an icon or image. That label is taken from iconText; only the first 3 characters are shown
iconText	""	Text label (first 3 characters used) when useTextIcon is true
tooltipImageSize	"medium"	Size of the image in the pin’s tooltip. Valid values are small, medium, large, xl
link	""	ID of the handout this pin links to. linkType only accepts handout or "".
linkType	""	The type of object linked. Valid values: handout, "" (empty string).
subLink	""	Header text to scroll to in the linked handout. Used with subLinkType (headerPlayer or headerGM).
subLinkType	""	The type of sub-link. Valid values: headerPlayer, headerGM, "" (empty string).
title	""	The title text displayed on the pin.
notes	""	Ordinary string. Not one of the character or handout blob fields.
gmNotes	""	Ordinary string, GM-only. Not one of the character or handout blob fields.
tooltipImage	""	Roll20 image identifier for the tooltip image displayed on the pin.
visibleTo	""	all shows the pin to everyone. "" hides it from players.
autoNotesType	""	Format for automatically generated notes. Valid values: "" (empty string), blockquote.
tooltipVisibleTo	"all"	Controls who can see the tooltip. Valid values: all, "" (empty string).
tooltipTitleVisibleTo	"all"	Controls who can see the tooltip title. Valid values: all, "" (empty string).
nameplateVisibleTo	"all"	Controls who can see the nameplate. Valid values: all, "" (empty string).
imageVisibleTo	"all"	Controls who can see the image. Valid values: all, "" (empty string).
notesVisibleTo	"all"	Controls who can see the notes. Valid values: all, "" (empty string).
gmNotesVisibleTo	"all"	Controls who can see GM notes. Valid values: all, "" (empty string).
scale	1.0	Scale factor for the pin. Must be between 0.25 and 2.0.
imageDesynced	false	Whether the pin’s image is desynced from its linked object. Setting any desynced property sets all three to the same value.
notesDesynced	false	Whether the pin’s notes are desynced from its linked object. Setting any desynced property sets all three to the same value.
gmNotesDesynced	false	Whether the pin’s GM notes are desynced from its linked object. Setting any desynced property sets all three to the same value.

Note1: If you intend to use custom content in pins (to override Handout’s image, notes and GM Notes), you must set at least one of the desynced properties to true (which will set all of them).

Note2: Valid Icon Values: base-dot, base-castle, base-skullSimple, base-spartanHelm, base-radioactive, base-heart, base-star, base-starSign, base-pin, base-speechBubble, base-file, base-plus, base-circleCross, base-dartBoard, base-badge, base-flagPin, base-crosshair, base-scrollOpen, base-diamond, base-photo, base-fourStarShort, base-circleStar, base-lock, base-crown, base-leaf, base-signpost, base-beer, base-compass, base-video, base-key, base-chest, base-village, base-swordUp, base-house, base-house2, base-church, base-government, base-blacksmith, base-stable, base-gear, base-bridge, base-mountain, base-exclamation, base-question.

Graphic (Token/Map/Card/Etc.)

Property	Default Value	Notes
_id		A unique ID for this object. Globally unique across all objects in this game. Read-only.
_type	"graphic"	Can be used to identify the object type or search for the object. Read-only.
_subtype	"token"	May be token (tokens and maps), card, or dicetoken. Read-only.
_cardid		Set to an ID if the graphic is a card. Read-only.
_pageid		ID of the page the object is in. Read-only.
imgsrc		The URL of the graphic’s image. See the note about imgsrc and avatar restrictions below.
bar1_link		Set to an ID if Bar 1 is linked to a character.
bar2_link
bar3_link
bar4_link
represents		ID of the character this token represents.
left	0	Number of pixels from the left edge of the map to the center of the graphic.
top	0	Number of pixels from the top edge of the map to the center of the graphic.
width	0	Width of the graphic, in pixels.
height	0	Height of the graphic, in pixels.
rotation	0	The orientation of the token in degrees.
layer	""	Current layer, one of gmlayer, objects, map, walls, or foreground.
isdrawing	false	This property is changed from the Advanced context menu.
disableSnapping	false	Disable graphic snapping to grid.
disableTokenMenu	false	Disable graphic token menu settings (token bubbles and radial menu).
flipv	false	Flip vertically.
fliph	false	Flip horizontally.
name	""	The token’s name.
gmnotes	""	GM-only notes. A synchronous string, often URL-encoded HTML (it may start with %3Cp%3E). This is not a character or handout blob field.
controlledby	""	Comma-delimited list of player IDs who can control the graphic. Controlling players may delete the graphic. If the graphic was created by a player, that player is automatically included in the list. All Players is represented by having all in the list.
bar1_value	""	Current value of Bar 1. This may be a number or text.
bar2_value	""
bar3_value	""
bar4_value	""
bar1_max	""	Maximum value of Bar 1. If _value and _max are both set, a bar may be displayed above the token showing the percentage of Bar 1.
bar2_max	""
bar3_max	""
bar4_max	""
aura1_radius	""	Radius of the aura, using the units set in the page’s settings. May be an integer or a float. Set to the empty string to clear the aura.
aura2_radius	""
aura1_color	"#FFFF99"	A hexadecimal color of the aura.
aura2_color	"#59E594"
aura1_options	"circle"	Sets the shape of an aura. Valid options are circle or square Note: Kept in sync with aura1_square
aura2_options	"circle"	Sets the shape of an aura. Valid options are circle or square Note: Kept in sync with aura2_square
aura1_square	false	Is the aura a circle or a square?
aura2_square	false
tint_color	"transparent"	Hexadecimal color, or transparent. Will tint the color of the graphic.
statusmarkers	""	A comma-delimited list of currently active status markers. Custom markers use the name::id tag from Campaign _token_markers. See the notes below.
showname	false	Whether the token’s nameplate is shown.
showplayers_name	false	Show the nameplate to all players.
showplayers_bar1	false	Show Bar 1 to all players.
showplayers_bar2	false
showplayers_bar3	false
showplayers_bar4	false
showplayers_aura1	false	Show Aura 1 to all players.
showplayers_aura2	false
playersedit_name	true	Allow controlling players to edit the token’s name. Also shows the nameplate to controlling players, even if showplayers_name is false.
playersedit_bar1	true	Allow controlling players to edit the token’s Bar 1. Also shows Bar 1 to controlling players, even if showplayers_bar1 is false.
playersedit_bar2	true
playersedit_bar3	true
playersedit_bar4	true
bar1_num_permission	""	Set how bar1 overlay is displayed. Valid values: everyone, hidden. "" means only editors will see value
bar2_num_permission	""
bar3_num_permission	""
bar4_num_permission	""
playersedit_aura1	true	Allow controlling players to edit the token’s Aura 1. Also shows Aura 1 to controlling players, even if showplayers_aura1 is false.
playersedit_aura2	true
light_radius	""	DEPRECATED Legacy Dynamic Lighting: bright light radius. See bright_light_distance.
light_dimradius	""	DEPRECATED Legacy Dynamic Lighting: Start of dim light radius. If light_dimradius is the empty string, the token will emit bright light out to the light_radius distance. If light_dimradius has a value, the token will emit bright light out to the light_dimradius value, and dim light from there to the light_radius value. See low_light_distance in the Dynamic Lighting documentation
light_otherplayers	false	DEPRECATED Legacy Dynamic Lighting: show this token’s light to all players. This is not has_night_vision.
light_hassight	false	DEPRECATED Legacy Dynamic Lighting: this light gives controlling players sight for Enforce Line of Sight. See has_bright_light_vision.
light_angle	"360"	DEPRECATED Legacy Dynamic Lighting: angle in degrees. 180 shows light across the front half of the field. See has_directional_bright_light, directional_bright_light_center, and directional_bright_light_total.
light_losangle	"360"	DEPRECATED Legacy Dynamic Lighting: Angle (in degrees) of the field of vision of the graphic (assuming that light_hassight is set to true) See has_limit_field_of_vision, limit_field_of_vision_center, limit_field_of_vision_total in the Dynamic Lighting documentation
sides	""	Pipe-delimited list of side images. Each entry is URL-encoded. Split on |, then decode with decodeURIComponent.
currentSide	0	Index into sides. Mod Script Sandbox v1.5 only. Setting currentSide automatically updates imgsrc, including Marketplace images. If the same .set() also includes a valid imgsrc, that imgsrc is used instead.
lastmove	""	The last move of the token. It’s a comma-delimited list of coordinates. For example,”300,400” would mean that the token started its last move at left=300, top=400. It’s always assumed that the current top + left values of the token are the “ending point” of the last move. Waypoints are indicated by multiple sets of coordinates. For example, “300,400,350,450,400,500” would indicate that the token started at left=300, top=400, then set a waypoint at left=350, top=450, another waypoint at left=400, top=500, and then finished the move at its current top + left coordinates.
light_multiplier	"1"	DEPRECATED Legacy Dynamic Lighting multiplier. 1 is normal sight. Current Dynamic Lighting uses light_sensitivity_multiplier, where 100 is normal.
adv_fow_view_distance	""	The radius around a token where Advanced Fog of War is revealed.
light_sensitivity_multiplier	100	Multiplier on the effectiveness of light sources. A multiplier of 200 would allow the token to see twice as far as a token with a multiplier of 100, with the same light source.
night_vision_effect	null	Night vision effect. null is the standard effect. Other values include Dimming and Nocturnal.
bar_location	null	Where the token bars sit. null is the default placement. Other values: overlap_top, overlap_bottom, bottom.
compact_bar	null	Bar style. null is the default. compact uses the compact bar.
lockMovement	false	An option to lock a Graphic in place. Boolean true or false value
fadeOnOverlap	true	When true, the overlapping of a object layer graphic’s inner bound with the foreground layer object will cause its opacity to become the value in fadeOpacity . When false, it will remain at its set baseOpacity regardless of overlap.
fadeOpacity	.3	This value dictates the opacity of the object when it is overlapped by a graphic on the object layer, and fadeOnOverlap is set to true
renderAsScenery	false	When true, this object will be obscured by dynamic lighting and the Hide/Reveal Mask
baseOpacity	1.0	Initial opacity of the graphic, on any layer.
interactionManualReset	false	When this is set to true it will reset interactions on the object
interactionTriggered	false	Will get set to true when an interaction is triggered

Current Dynamic Lighting properties (in addition to the legacy light_* fields above):

Property	Default
has_bright_light_vision	false
has_night_vision	false
night_vision_tint	null
night_vision_distance	0
emits_bright_light	false
bright_light_distance	0
emits_low_light	false
low_light_distance	0
dim_light_opacity	0
lightColor	"transparent"
has_limit_field_of_vision	false
limit_field_of_vision_center	0
limit_field_of_vision_total	0
has_limit_field_of_night_vision	false
limit_field_of_night_vision_center	0
limit_field_of_night_vision_total	0
has_directional_bright_light	false
directional_bright_light_center	0
directional_bright_light_total	0
has_directional_dim_light	false
directional_dim_light_center	0
directional_dim_light_total	0
tooltip	""
show_tooltip	false
gm_only_tooltip	false
renderAsDarkness	false

Mod Script Sandbox v1.5 only. Setting currentSide automatically updates imgsrc:

const setRandomSide = (obj) => {
  if ('graphic' === obj.type) {
    obj.set({
      currentSide: randomInteger(obj.get('sides')?.split('|').length ?? 1) - 1
    });
  }
};

Mod Script Sandbox v1.5 only. Methods on graphic:

• createCopy(properties) — copy as createObj would, including Marketplace imgsrc/sides. Returns the new graphic.
• toFront(), toBack(), toAbove(target), toBelow(target) — same as the global functions. target may be an object or id.

obj.createCopy({ pageid, layer, left: x, top: y });

Token Markers Example

The game-wide list of available markers is Campaign().get('_token_markers'). Each entry looks like:

{
  "id":59, // the database id for the
  "name":"Bane", // the name (non-unique) of the marker
  "tag":"Bane::59", // how the token is actually referenced
  // this will include the id for custom markers, but not
  // for default markers.
  "url":"https://s3.amazonaws.com/files.d20.io/images/59/yFnKXmhLTtbMtaq-Did1Yg/icon.png?1575153187"
  // ^the url for the token marker's image
}

Important Notes About Linked Characters + Tokens Note that for tokens that are linked to Characters, the controlledby field on the token is overridden by the controlledby field on the Character. For token bars (e.g. bar1_value and bar1_max) where the token is linked to an Attribute (e.g. bar1_link is set), setting a value to the bar will automatically update the underlying Attribute’s current and/or max values as well, so you don’t have to set both manually. In addition, when the Attribute (or token bar) is modified in-game, you will hear a change:attribute (and property-specific, e.g. change:attribute:current) event, followed by a change:graphic (and change:graphic:bar1_value) event. You can choose to respond to either event, but the underlying bar values will not yet be updated when the attribute event fires, since it fires first.

Important Notes About Status Markers As of August 6, 2013 the way that status markers on tokens are handled has changed. The statusmarkers property of the Graphic object is now a comma-delimited list of all status marker colors/icons that should be active on the token. The format is as follows:

//Comma-delimited (use join to create or split to turn into an array).
//If a status icon/color is followed by an "@" symbol, the number after
//"@" will be shown as the badge on the icon
statusmarkers = "red,blue,skull,dead,brown@2,green@6"

While you can access the statusmarkers property directly, to maintain backward-compatibility with existing scripts, and to provide an easy way to work with the status markers without needing to write code to handle splitting up and parsing the string yourself, we provide a set of virtual properties on the object that you can set/get to work with the status markers. Each status marker has a status_<markername> property. For example:

obj.get("status_red"); //Will return false if the marker is not active, true if it is, and a string (e.g. "2" or "5") if there is currently a badge set on the marker
obj.get('status_bluemarker'); //Is still supported for backwards compatability, and is equivalent to doing obj.get("status_blue");
obj.set("status_red", false); //would remove the marker
obj.set("status_skull", "2"); //would set a badge of "2" on the skull icon, and add it to the token if it's not already active.

Note that these virtual properties do not have events, so you must use change:graphic:statusmarkers to listen for changes to the status markers of a token, and for example change:graphic:status_red is NOT a valid event and will never fire. The full list of status markers that are available (in the same order they appear in the marker tray):

"red", "blue", "green", "brown", "purple", "pink", "yellow", "dead", "skull", "sleepy", "half-heart", "half-haze", "interdiction", "snail", "lightning-helix", "spanner", "chained-heart", "chemical-bolt", "death-zone", "drink-me", "edge-crack", "ninja-mask", "stopwatch", "fishing-net", "overdrive", "strong", "fist", "padlock", "three-leaves", "fluffy-wing", "pummeled", "tread", "arrowed", "aura", "back-pain", "black-flag", "bleeding-eye", "bolt-shield", "broken-heart", "cobweb", "broken-shield", "flying-flag", "radioactive", "trophy", "broken-skull", "frozen-orb", "rolling-bomb", "white-tower", "grab", "screaming", "grenade", "sentry-gun", "all-for-one", "angel-outfit", "archery-target"

Page

Property	Default Value	Notes
_id		A unique ID for this object. Globally unique across all objects in this game. Read-only.
_type	"page"	Can be used to identify the object type or search for the object. Read-only.
_zorder	""	Comma-delimited list of IDs specifying the ordering of objects on the page. The stored string often has a trailing comma; drop empty segments when you split it. toFront and toBack rewrite this list. Read-only.
name	""	Page’s title.
showgrid	true	Show the grid on the map.
showdarkness	false	Show fog of war on the map.
showlighting	false	DEPRECATED Legacy Dynamic Lighting: To use dynamic lighting, See dynamic_lighting_enabled in the Dynamic Lighting documentation
width	25	Width in units.
height	25	Height in units.
snapping_increment	1	Size of a grid space in units.
grid_opacity	0.5	Opacity of the grid lines.
fog_opacity	0.35	Opacity of the fog of war for the GM.
background_color	"#ffffff"	Hexadecimal color of the map background. Stored lowercase.
gridcolor	"#C0C0C0"	Hexadecimal color of the grid lines.
grid_type	"square"	One of square, hex (Hex V), hexr (Hex H), dimetric, or isometric.
scale_number	5	The distance of one unit.
scale_units	"ft"	The type of units to use for the scale.
gridlabels	false	Show grid labels for hexagonal grid.
diagonaltype	"foure"	One of foure, pythagorean (Euclidean), threefive, or manhattan.
archived	false	Whether the page has been put into archive storage.
lightupdatedrop	false	Only update Dynamic Lighting when an object is dropped.
lightenforcelos	false	DEPRECATED Legacy Dynamic Lighting: Enforce Line of Sight for objects.
lightrestrictmove	false	Don’t allow objects that have sight to move through Dynamic Lighting walls.
lightglobalillum	false	DEPRECATED Legacy Dynamic Lighting: If true anywhere a token can “see” it is assumed there is bright light present. See daylight_mode_enabled in the Dynamic Lighting documentation
adv_fow_enabled	false	DEPRECATED Legacy Advanced Fog of War.
adv_fow_dim_reveals	false	DEPRECATED Legacy Advanced Fog of War: dim light reveals fog.
adv_fow_show_grid	false	DEPRECATED Legacy Advanced Fog of War: show the grid through fog.
grid_offset_x	0	Horizontal grid offset.
grid_offset_y	0	Vertical grid offset.
force_lighting_refresh	null	Set to request a Dynamic Lighting refresh. Default is null, not a boolean.
jukeboxtrigger	null	Page Play on Load. Options include none, stop, all, or a track id.
dynamic_lighting_enabled	false	Use Dynamic Lighting
daylight_mode_enabled	false	Use Daylight Mode
daylightModeOpacity	1	sets the intensity of the light in Daylight Mode
explorer_mode	"off"	Options: off, basic
darknessEffect	"none"	Options: none, darkfog, lightfog
_placement	0	Mod Script Sandbox v1.5 only. Sort key in the page menu. Existing pages use sparse values (for example 2000). Sort by this number; do not use it as an array index. Read-only except through the placement methods.
_path	","	Mod Script Sandbox v1.5 only. Comma-delimited pageFolder ids. Values usually start with a comma and may end with extra commas. Drop empty segments when you split. Read-only except through the placement methods.
_wrapperAutoColor	#ffffff	Mod Script Sandbox v1.5 only. Calculated wrapper color. Read-only.
useAutoWrapper	true	Mod Script Sandbox v1.5 only. When true, use _wrapperAutoColor.
wrapperColor	null	Mod Script Sandbox v1.5 only. Used when useAutoWrapper is false.

Mod Script Sandbox v1.5 only. Methods: placeBefore(obj), placeAfter(obj) (obj is a page or pageFolder), placeIn(obj) (obj is a pageFolder). Moving between folder levels updates _path.

PageFolder

Mod Script Sandbox v1.5 only.

pageFolder objects are folders in the page menu. You can create and remove them. Removing a folder moves its children up one level in the menu.

Property	Default Value	Notes
_id		A unique ID for this object. Globally unique across all objects in this game. Read-only.
_type	"pageFolder"	Read-only.
name	"New Folder"	Shown in the page menu.
_placement	0	Order in the page menu.
_path	","	Comma-delimited parent pageFolder ids.

Methods: placeBefore(obj), placeAfter(obj) (page or pageFolder), placeIn(obj) (pageFolder). Changing folders updates _path for this folder and its descendants. remove() moves children up, then deletes the folder.

var folder = createObj('pageFolder', { name: 'Dungeons' });

Campaign

Property	Default Value	Notes
_id	"root"	A unique ID for this object. Globally unique across all objects in this game. Read-only.
_type	"campaign"	Can be used to identify the object type or search for the object — however, note that there is only one Campaign object, and it can be accessed via Campaign(). Read-only.
turnorder	""	A JSON string of the turn order. See below.
initiativepage	false	ID of the page used for the tracker when the turn order window is open. When set to false, the turn order window closes.
playerpageid	false	ID of the page the player bookmark is set to. Players see this page by default, unless overridden by playerspecificpages below.
playerspecificpages	false	An object (NOT JSON STRING) of the format: {player1_id: page_id, player2_id: page_id … } Any player set to a page in this object will override the playerpageid.
_journalfolder	""	A JSON string which contains data about the folder structure of the game. Read-only.
_jukeboxfolder	""	A JSON string which contains data about the jukebox playlist structure of the game. Read-only.
_token_markers	"[]"	JSON array of token markers available in the game (built-in and custom). Read-only. See the Token Markers Example under Graphic.
foregroundLayerVisible	true	When true , players will see objects on the foreground layer. When false , they will not. Note: this is a global setting that affects all pages.
tokenBubbleMax	3	Valid values are 3 or 4 representing the number of token bubbles. Available in the upgraded VTT Engine.

These extra properties are read on the object returned by Campaign(), not via get:

Property	Sandbox	Notes
sandboxVersion	both	"1.0" or "1.5"
nodeVersion	both	Node.js version string for the sandbox process
sheetName	v1.5 only	Short name of the configured character sheet
computedSummary	v1.5 only	Available Beacon computed property names
actionSummary	v1.5 only	Available Beacon sheet actions

log(Campaign().sandboxVersion);

Turn Order The turn order is a JSON string representing the current turn order listing. It is an array of objects. Currently, the turn order can only contain objects from one page at a time – the current Page ID for the turn order is the initiativepage attribute. Be sure to keep them both in-sync or you may end up with strange results. To work with the turn order, you will want to use JSON.parse() to get an object representing the current turn order state (NOTE: Check to make sure it’s not an empty string "" first…if it is, initialize it yourself with an empty array). Here’s an example turn order object:

[
  {
    "id":"36CA8D77-CF43-48D1-8682-FA2F5DFD495F", //The ID of the Graphic object. If this is set, the turn order list will automatically pull the name and icon for the list based on the graphic on the tabletop.
    "pr":"0", //The current value for the item in the list. Can be a number or text.
    "custom":"" //Custom title for the item. Will be ignored if ID is set to a value other than "-1".
  },
  {
    "id":"-1", //For custom items, the ID MUST be set to "-1" (note that this is a STRING not a NUMBER.
    "pr":"12",
    "custom":"Test Custom" //The name to be displayed for custom items.
  }
]

To modify the turn order, edit the current turn order object and then use JSON.stringify() to change the attribute on the Campaign. Note that the ordering for the turn order in the list is the same as the order of the array, so for example push() adds an item onto the end of the list, unshift() adds to the beginning, etc.

var turnorder;
if(Campaign().get("turnorder") == "") turnorder = []; //NOTE: We check to make sure that the turnorder isn't just an empty string first. If it is treat it like an empty array.
else turnorder = JSON.parse(Campaign().get("turnorder"));
//Add a new custom entry to the end of the turn order.
turnorder.push({
  id: "-1",
  pr: "15",
  custom: "Turn Counter"
});
Campaign().set("turnorder", JSON.stringify(turnorder));

Player

Property	Default Value	Notes
_id		A unique ID for this object. Globally unique across all objects in this game. Read-only.
_type	"player"	Can be used to identify the object type or search for the object. Read-only.
_d20userid		User ID — site-wide. For example, the player’s user page on the wiki is /User:ID, where ID is the same value stored in _d20userid. Read-only.
_displayname	""	The player’s current display name. May be changed from the user’s settings page. Read-only.
_online	false	Read-only.
_lastpage	""	The page id of the last page the player viewed as a GM. This property is not updated for players or GMs that have joined as players. Read-only.
_macrobar	""	Comma-delimited string of the macros in the player’s macro bar. Read-only.
speakingas	""	The player or character ID of who the player has selected from the As dropdown. When set to the empty string, the player is speaking as him- or herself. When set to a character, the value is character|<ID> where <ID> is the ID of the character.
color	"#13B9F0"	The color of the square by the player’s name, as well as the color of their measurements on the map, their ping circles, etc.
showmacrobar	false	Whether the player’s macro bar is showing.

Macro

Property	Default Value	Notes
_id		A unique ID for this object. Globally unique across all objects in this game. Read-only.
_type	"macro"	Can be used to identify the object type or search for the object. Read-only.
_playerid		The ID of the player that created this macro. Read-only.
name	""	The macro’s name.
action	""	The text of the macro.
visibleto	""	Comma-delimited list of player IDs who may view the macro in addition to the player that created it. All Players is represented by having all in the list.
istokenaction	false	Is this macro a token action that should show up when tokens are selected?

Rollable Table

Property	Default Value	Notes
_id		A unique ID for this object. Globally unique across all objects in this game. Read-only.
_type	"rollabletable"	Can be used to identify the object type or search for the object. Read-only.
name	"new-table"
showplayers	true

Mod Script Sandbox v1.5 only. createToken(properties) creates a graphic whose sides come from table item avatars (Marketplace images allowed). Returns the graphic. If no table item has an avatar, nothing is created.

Table Item

Property	Default Value	Notes
_id		A unique ID for this object. Globally unique across all objects in this game. Read-only.
_type	"tableitem"	Can be used to identify the object type or search for the object. Read-only.
_rollabletableid	""	ID of the table this item belongs to. Read-only.
avatar	""	URL to an image used for the table item. See the note about avatar and imgsrc restrictions below.
name	""
weight	1	Weight of the table item compared to the other items in the same table. Simply put, an item with weight 3 is three times more likely to be selected when rolling on the table than an item with weight 1.

Character

Property	Default Value	Notes
_id		A unique ID for this object. Globally unique across all objects in this game. Read-only.
_type	"character"	Can be used to identify the object type or search for the object. Read-only.
avatar	""	URL to an image used for the character. See the note about avatar and imgsrc restrictions below.
name	""
bio	""	The character’s biography. See the note below about accessing the Notes, GMNotes, and bio fields.
gmnotes	""	Notes on the character only viewable by the GM. See the note below about accessing the Notes, GMNotes, and bio fields.
archived	false
inplayerjournals	""	Comma-delimited list of player ID who can view this character. Use all to give all players the ability to view. All Players is represented by having all in the list.
controlledby	""	Comma-delimited list of player IDs who can control and edit this character. Use all to give all players the ability to edit. All Players is represented by having all in the list.
_defaulttoken	""	A JSON string for the character’s default token, if one is set. This is a blob, like bio and notes, so get() takes a callback. Do not set() it. Write it with setDefaultTokenForCharacter.
inParty	false	Whether the character is in the party.
tags	"[]"	JSON array of strings. No whitespace or commas. Invalid tags are stripped; a warning is sent to the Mod Output Console. Available on both sandbox versions.

Mod Script Sandbox v1.5 only. sheetEnvironment is "legacy" or "beacon". Read it as character.sheetEnvironment (not via get).

Mod Script Sandbox v1.5 only. createToken(properties, options, callback) creates a graphic from the character’s default token. If there is no default token, the character avatar is used. If there is no avatar either, creation fails. Marketplace images are allowed. Because _defaulttoken is async, the graphic is passed to callback rather than returned.

Option	Default	Notes
preferAvatar	false	Prefer the character avatar as imgsrc.
multisided	false	How sides are built: false leaves sides as on the default token; true/ensure adds imgsrc and avatar if there are no sides; replace overwrites existing sides; append / prepend add imgsrc/avatar.

obj.createToken({ pageid, layer, left: x, top: y }, { multisided: 'ensure' }, function (token) {
  token.set('status_green', 5);
});

Attribute

Property	Default Value	Notes
_id		A unique ID for this object. Globally unique across all objects in this game. Read-only.
_type	"attribute"	Can be used to identify the object type or search for the object. Read-only.
_characterid	""	ID of the character this attribute belongs to. Read-only. Mandatory when using createObj.
name	"Untitled"
current	""	The current value of the attribute can be accessed in chat and macros with the syntax @{Character Name|Attribute Name} or in abilities with the syntax @{Attribute Name}.
max	""	The max value of the attribute can be accessed in chat and macros with the syntax @{Character Name|Attribute Name|max} or in abilities with the syntax @{Attribute Name|max}.

Important: See the note below about working with Character Sheets for information on how Character Sheet default values affect the use of Attributes.

Ability

Property	Default Value	Notes
_id		A unique ID for this object. Globally unique across all objects in this game. Read-only.
_type	"ability"	Can be used to identify the object type or search for the object. Read-only.
_characterid	""	The character this ability belongs to. Read-only. Mandatory when using createObj.
name	"Untitled_Ability"
description	""	The description does not appear in the character sheet interface.
action	""	The text of the ability.
istokenaction	false	Is this ability a token action that should show up when tokens linked to its parent Character are selected?

Handout

Property	Default Value	Notes
_id		A unique ID for this object. Globally unique across all objects in this game. Read-only.
_type	"handout"	Can be used to identify the object type or search for the object. Read-only.
_pins	"[]"	A JSON string containing an array of objects that represent each of the pins associated with parts of this handout.
avatar	""	URL to an image used for the handout. See the note about avatar and imgsrc restrictions below.
name	"Mysterious Note"
notes	""	Contains the text in the handout. See the note below about using Notes and GMNotes.
gmnotes	""	Contains the text in the handout that only the GM sees. See the note below about using Notes and GMNotes.
inplayerjournals	""	Comma-delimited list of player ID who can see this handout. Use all to display to all players. All Players is represented by having all in the list.
archived	false
controlledby	""	Comma-delimited list of player IDs who can control and edit this handout. All Players is represented by having all in the list.
tags	"[]"	JSON array of strings. Same rules as character tags. Available on both sandbox versions.

Note: Campaign().get("_journalfolder") is readable. Scripts cannot write the journal folder. Handouts created by scripts are placed at the root.

Deck

There are helper Mod Script functions to draw, deal, shuffle, recall, pick up, take, play, and give cards: shuffleDeck, cardInfo, recallCards, dealCardsToTurn, drawCard, pickUpCard, takeCardFromPlayer, playCardToTable, giveCardToPlayer. They are available on both sandbox versions. See Function Documentation.

Property	Default Value	Notes
_id	""	id of the deck
_type	"deck"
name	""	name of the deck
_currentDeck	""	a comma-delimited list of cards which are currently in the deck (including those which have been played to the tabletop/hands). Changes when the deck is shuffled.
_currentIndex	-1	the current index of our place in the deck, ‘what card will be drawn next?’
_currentCardShown	true	show the current card on top of the deck
showplayers	true	show the deck to the players
playerscandraw	true	can players draw cards?
avatar	""	the back of the cards for this deck
shown	false	show the deck on the gameboard (is the deck currently visible?)
players_seenumcards	true	can players see the number of cards in other player’s hands?
players_seefrontofcards	false	can players see the fronts of cards when looking in other player’s hands?
gm_seenumcards	true	can the GM see the number of cards in each player’s hand?
gm_seefrontofcards	false	can the GM see the fronts of cards when looking in each player’s hand?
infinitecards	false	are there an infinite number of cards in this deck?
_cardSequencer	-1	internally used to advance the deck when drawing cards.
cardsplayed	"faceup"	how are cards from this deck played to the tabletop? faceup or facedown.
defaultheight	""	what’s the default height for cards played to the tabletop?
defaultwidth	""
discardpilemode	"none"	what type of discard pile does this deck have? none = no discard pile, choosebacks = allow players to see backs of cards and choose one, choosefronts = see fronts and choose, drawtop = draw the most recently discarded card, drawbottom = draw the oldest discarded card.
_discardPile	""	what’s the current discard pile for this deck? comma-delimited list of cards. These are cards which have been removed from play and will not be put back into the deck on a shuffle until a recall is performed.

Card

Property	Default Value	Notes
name	""	Name of the card
avatar	""	Front of the card
card_back	""	Override card back image
_deckid	""	ID of the deck
_type	"card"
_id	""

Mod Script Sandbox v1.5 only. createToken(properties, options) creates a graphic as if the card were played to the table (Marketplace images allowed). Returns the graphic.

Option	Default	Notes
asCard	true	If true, the graphic is a card. If false, a multisided token that only looks like the card.
faceup	deck default	Face or back showing; sets currentSide.

Hand

Note that each player should only have ONE hand.

Property	Default Value	Notes
currentHand	""	comma-delimited list of cards currently in the hand. Note that this is no longer read only. Ideally, it should only be adjusted with the card deck functions.
_type	"hand"
_parentid	""	ID of the player to whom the hand belongs
_id	""
currentView	"bydeck"	when player opens hand, is the view bydeck or bycard?

Jukebox Track

Property	Default Value	Notes
_id		A unique ID for this object. Globally unique across all objects in this game. Read-only.
_type	"jukeboxtrack"	Can be used to identify the object type or search for the object. Read-only.
playing	false	Boolean used to determine whether or not the track is playing. Setting this to true and softstop to false plays a track.
softstop	false	Boolean used to determine whether or not a non-looped track has finished at least once. This must be set to false to ensure that a track will play.
title	""	The visible label for the track in the jukebox tab.
volume	30	The volume level of the track. Note that this must be set to an integer (not a string), or you may break functionality. Values from 0-100 (percentage).
loop	false	Should the track be looped? Set to true if so.

Custom FX

Property	Default Value	Notes
_id		A unique ID for this object. Globally unique across all objects in this game. Read-only.
_type	"custfx"	Can be used to identify the object type or search for the object. Read-only.
name	""	The visible name for the FX in the FX Listing.
definition	{}	Javascript object describing the FX.

imgsrc and avatar property restrictions

While you can now edit the imgsrc and avatar properties, in order to provide safety to all Roll20’s users we have put the following restrictions in place for those properties:

• You must use an image file that has been uploaded to your Roll20 Library – not an external site (such as Imgur), and not the Roll20 Marketplace. Stored URLs are rewritten onto the Roll20 CDN (often https://files.d20.io/images/...). Do not require an s3.amazonaws.com prefix, and do not expect get("imgsrc") to match the URL you passed in.
• Include the query string in the URL you pass in.
• Graphic imgsrc values are no longer required to use the thumb size name. Image URLs are adjusted to a corrected storage format and CDN location; do not expect obj.get('imgsrc') to match the URL you passed at create time. findObjs() normalizes and matches URLs, so you can still search with any valid URL.

If you delete an image from your library, it is removed from every game that uses it, including games using your Mod Scripts.

Mod Script Sandbox v1.5 only. createCopy and createToken can create graphics that use Marketplace images by copying from an existing object.

Using the Notes, GMNotes, and Bio fields Asynchronous

In order to access the notes, gmnotes, or bio fields on Characters and Handouts, you must pass a callback function as the second argument to the get() function. Here’s an example:

var character = getObj("character", "-JMGkBaMgMWiQdNDwjjS");
character.get("bio", function(bio) {
  log(bio); //do something with the character bio here.
});

Set these fields with set() after the object exists. Do not pass bio, notes, or gmnotes to createObj. Set notes and gmnotes in separate set() calls. Graphic gmnotes is a normal string and is not part of this list. Character _defaulttoken is a blob: read it with a callback, and write it with setDefaultTokenForCharacter.

Working with Character Sheets

The Character Sheets feature affects the usage of the Attributes object type, because the sheets have the capability of specifying a default value for each attribute on the sheet. However, if the attribute is set to the default value, there is not yet an actual Attribute object created in the game for that Character. We provide a convenience function which hides this complexity from you. You should use this function to get the value of an attribute going forward, especially if you know that a game is using a Character Sheet. getAttrByName(character_id, attribute_name, value_type) Simply specify the character’s ID, the name (not ID) of the attribute (e.g. HP or Str), and then if you want the current or max for value_type. Here’s an example:

var character = getObj("character", "-JMGkBaMgMWiQdNDwjjS");
getAttrByName(character.id, "str"); // the current value of str, for example "12"
getAttrByName(character.id, "str", "max"); //the max value of str, for example "[[floor(@{STR}/2-5)]]"

Note that fields which have auto-calculated values will return the formula rather than the result of the value. You can then pass that formula to sendChat() to use the dice engine to calculate the result for you automatically. Be sure to also look at the Character Sheet documentation for more information on how the Character Sheets interact with Mod Scripts. Also see setAttrs, getSheetDefaultValue, getSheetItem, and setSheetItem (both sandboxes). Mod Script Sandbox v1.5 only. getComputed, setComputed, performAction. See Function Documentation.

getAttrByName will only get the value of the attribute, not the attribute object itself. If you wish to reference properties of the attribute other than current or max, or if you wish to change properties of the attribute, you must use one of the other functions above, such as findObjs. If the attribute object does not exist, getAttrByName() returns the character sheet’s default for that name when the sheet defines one, and undefined otherwise.

Creating Objects

createObj(type, attributes)

You can create 'graphic', 'text', 'path', 'pathv2', 'character', 'ability', 'attribute', 'handout', 'rollabletable', 'tableitem', 'macro', 'card', 'deck', 'custfx', 'window', 'door', and 'pin' objects. Mod Script Sandbox v1.5 only. 'pageFolder'. You can create a new object in the game using the createObj function. You must pass in the type of the object (one of the valid _type properties from the objects list above), as well as an attributes object containing a list of properties for the object. Note that if the object is has a parent object (for example, attributes and abilities belong to characters, graphics, texts, and paths belong to pages, etc.), you must pass in the ID of the parent in the list of properties (for example, you must include the characterid property when creating an attribute). Also note that even when creating new objects, you can’t set read-only properties, they will automatically be set to their default value. The one exception to this is when creating a Path, you must include the path property, but it cannot be modified once the path is initially created. createObj will return the new object, so you can continue working with it.

// Create a Strength attribute on characters added after the sandbox is ready.
// Binding add:character before ready also fires for characters that already exist.
on("ready", function() {
  on("add:character", function(obj) {
    createObj("attribute", {
      name: "Strength",
      current: 0,
      max: 30,
      characterid: obj.id
    });
  });
});

Deleting Objects

object.remove()

You can delete 'graphic', 'text', 'path', 'pathv2', 'character', 'ability', 'attribute', 'handout', 'rollabletable', 'tableitem', 'macro', 'card', 'deck', 'custfx', 'window', 'door', and 'pin' objects. Mod Script Sandbox v1.5 only. 'pageFolder'.

You can delete existing game objects using the .remove() function. The .remove() function works on all of the objects you can create with the createObj function. You call the function directly on the object. For example, mycharacter.remove();.

Global Objects

There are several objects that are globally available anywhere in your script.

Campaign() (function)

A function which returns the Campaign object. Since there is only one campaign, this global always points to the only campaign in the game. Useful for doing things like checking to see if an object is on the active page using Campaign().get("playerpageid").

state

The state variable is an object in the global scope which is accessible to all scripts running in a game. You can access the state object from any function or callback at any time just by using the global variable named state. Additionally, the state object is persisted between executions of the Mod Script Sandbox, so you can use it to store information you want to have in future runs of your script. Note: You should use the state object to store information that is only needed by Mod Scripts, since it is not sent to player computers and does not make your game file larger. Store values that are needed in-game in the Roll20 objects’ properties.

Storable Types

The state object is only capable of persisting simple data types, as supported by the JSON standard.

Type	Examples	Description
Boolean	true false	The value true or false.
Number	123.5 10 1.23e20	Any number format supported by Javascript. Floating-Point or Integer.
String	'Hello Fantasy' "oh, and World"	A standard string of text.
Array	[ 1, 2, 3, 4 ] [ 'A','B','C'][1, 2, ['bob', 3], 10, 2.5]	An ordered collection of any of the types, including other arrays.
Object	{ key: 1, value: 'roll20' }	A simple key/value object with string keys and any of the types as a value, including other objects.

Warning: While functions will appear to work when stored in the state initially, they will disappear the first time the state is restored from persistence, such as on a sandbox restart.

• Note: This includes Roll20 objects which you get from events or the functions findObjs(), getObj(), filterObjs(), createObj(), etc.

Important Reminders

The state object is shared between all of the scripts in a sandbox. To avoid breaking other scripts, it is important to follow a few simple guidelines:

• Never assign directly to the root state object.

state = { break: 'all the things' }; // NEVER DO THIS!!!

• Avoid using local variables named state in your scripts. While this will work, it will be confusing to later users of your scripts and could cause issues if the code is carelessly edited.

function turn(){
  var state = Campaign().get('turnorder'); // Bad Practice, Avoid it!
  // ...
}

• Always place your properties beneath at least one namespace property. Be sure to use a sufficiently descriptive namespace property. Avoid names like script or settings. It’s best to either use the name of your module or your own name or handle.

if( ! state.MyModuleNamespace ) {
  state.MyModuleNamespace = { module: 'my module', ok: 'this is fine!', count: 0 };
}
state.MyModuleNamespace.count++;

Example Usage

This is a working example that uses the state object appropriately.

on('ready',function() {
  "use strict";
  // Check if the namespaced property exists, creating it if it doesn't
  if( ! state.MyModuleNS ) {
    state.MyModuleNS = {
      version: 1.0,
      config: {
        color1: '#ff0000',
        color2: '#0000ff'
      },
      count: 0
    };
  }
  // Using the state properties to configure a message to the chat.
  sendChat(
    'Test Module',
    '<span style="color: '+state.MyModuleNS.config.color1+';">'+
    'State test'+
    '</span> '+
    '<span style="color: '+state.MyModuleNS.config.color2+';">'+
    'Script v'+state.MyModuleNS.version+' started '+(++state.MyModuleNS.count)+' times!'+
    '</span>'
  );
});

Finding/Filtering Objects

Mod Scripts provide several helper functions which can be used to find objects.

getObj(type, id)
This function gets a single object if pass in the _type of the object and the _id. It's best to use this function over the other find functions whenever possible, as its the only one that doesn't have to iterate through the entire collection of objects.
on("change:graphic:represents", function(obj) {
  if(obj.get("represents") != "") {
    var character = getObj("character", obj.get("represents"));
  }
});

findObjs(attrs)

Pass this function a list of attributes, and it will return all objects that match as an array. Note that this operates on all objects of all types across all pages – so you probably want to include at least a filter for _type and _pageid if you’re working with tabletop objects.

var currentPageGraphics = findObjs({
  _pageid: Campaign().get("playerpageid"),
  _type: "graphic",
});
_.each(currentPageGraphics, function(obj) {
  //Do something with obj, which is in the current page and is a graphic.
});

You can also pass in an optional second argument which contains an object with a list of options, including:

• caseInsensitive (true/false): If true, string properties will be compared without regard for the case of the string

var targetTokens = findObjs({
  name: "target"
}, {caseInsensitive: true});
//Returns all tokens with a name of 'target', 'Target', 'TARGET', etc.

• startsWith (true/false): If true, string properties match as a prefix.
• tagMatch: When matching tags: 'all' (default; object has every listed tag), 'any' (at least one), 'only' (exactly the listed set).

var knights = findObjs({ type: 'character', name: 'Sir' }, { startsWith: true });

filterObjs(callback)

Will execute the provided callback function on each object, and if the callback returns true, the object will be included in the result array. Currently, it is inadvisable to use filterObjs() for most purposes – due to the fact that findObjs() has some built-in indexing for better executing speed, it is almost always better to use findObjs() to get objects of the desired type first, then filter them using the native .filter() method for arrays.

var results = filterObjs(function(obj) {
  if(obj.get("left") < 200 && obj.get("top") < 200) return true;
  else return false;
});
//Results is an array of all objects that are in the top-left corner of the tabletop.

getAllObjs()

Returns an array of all the objects in the Game (all types). Equivalent to calling filterObjs and just returning true for every object.

getAttrByName(character_id, attribute_name, value_type)

Gets the value of an attribute, using the default value from the character sheet if the attribute is not present. value_type is an optional parameter, which you can use to specify current or max. getAttrByName will only get the value of the attribute, not the attribute object itself. If you wish to reference properties of the attribute other than current or max, or if you wish to change properties of the attribute, you must use one of the other functions above, such as findObjs. For repeating sections, you can use the format repeating_section_$n_attribute, where n is the repeating row number (starting with zero). For example, repeating_spells_$2_name will return the value of name from the third row of repeating_spells. You can achieve behavior equivalent to getAttrByNamewith the following:

// current and max are completely dependent on the attribute and game system
// in question; there is no function available for determining them automatically
function myGetAttrByName(character_id,
  attribute_name,
  attribute_default_current,
  attribute_default_max,
  value_type) {
  attribute_default_current = attribute_default_current || '';
  attribute_default_max = attribute_default_max || '';
  value_type = value_type || 'current';
  var attribute = findObjs({
    type: 'attribute',
    characterid: character_id,
    name: attribute_name
  }, {caseInsensitive: true})[0];
  if (!attribute) {
    attribute = createObj('attribute', {
      characterid: character_id,
      name: attribute_name,
      current: attribute_default_current,
      max: attribute_default_max
    });
  }
  if (value_type == 'max') {
    return attribute.get('max');
  } else {
    return attribute.get('current');
  }
}