Mod:Objects
From Roll20 Wiki
Roll20 Mod
Use Mods
- Use & Install
- Mod:Script Index & Suggestions
- Short Community Scripts
- Meta Scripts
- User Documentation
- Mod Scripts(Forum)
- Mod Update 2024🆕
- Macro Guide
Mod Development
Reference
- Objects
- Events
- Chat Events & Functions
- Utility Functions
- Function
- Roll20 object
- Token Markers
- Sandbox Model
- Debugging
Cookbook
There are several different types of objects that are used throughout the Roll20 API. 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.
Contents |
Path
{ _id: "-Abc123", //unique ID for this object. globally unique across all objects in this campaign fill: "transparent", //fill color. "transparent" or a color HEX stroke: "#000000", // stroke color rotation: 0, //rotation (in degrees) layer: "", //current layer, one of "gmlayer", "objects", "map", "walls" (dynamic lighting) -- Paths on the "walls" layer are automatically used to block light. stroke_width: 5, width: 0, height: 0, top: 0, left: 0, scaleX: 1, scaleY: 1, _type: "path", //can be used to identify the object as a Path. read-only. _pageid: "-Abc123" //The ID of the page this object is in }
Text
{ _id: "-Abc123", top: 0, left: 0, width: 0, height: 0, text: "", font_size: 16, //for best results stick to the pre-sets in the text editing menu rotation: 0, color: "#000000", font_family: "unset", //see values of select element in text editing menu layer: "", _type: "text", //identifies the object is text. read-only. _pageid: "-Abc123" }
Graphic (Token/Map/Card/Etc.)
{ _id: "-Abc123", left: 0, top: 0, width: 0, height: 0, rotation: 0.0, layer: "", isdrawing: false, //advanced -> is drawing? flipv: false, //flip vertically fliph: false, //flip horizontally name: "", //Token Name gmnotes: "", //GM Notes bar1_value: "", //Current value of Bar 1 (number OR text) bar1_max: "", //Max value of Bar 1 _bar1_link: "", //Set to an ID if Bar 1 is linked to a Character Attrbute. read-only. bar2_value: "", bar2_max: "", _bar2_link: "", bar3_value: "", bar3_max: "", _bar3_link: "", aura1_radius: "", //Radius (integer or float) of the aura. Set to empty string ("") for none. aura1_color: "#FFFF99", //HEX color aura1_square: false, //Is the aura square? aura2_radius: "", aura2_color: "#59E594", aura2_square: false, tint_color: "transparent", //HEX color or "transparent" status_redmarker: false, //show the red marker on the token status_bluemarker: false, status_greenmarker: false, status_brownmarker: false, status_purplemarker: false, status_dead: false, showname: false, //show the nameplate showplayers_name: false, //show the name to all players showplayers_bar1: false, showplayers_bar2: false, showplayers_bar3: false, showplayers_aura1: false, showplayers_aura2: false, playersedit_name: false, // allow controlling players to edit the name. also show the name to controlling players even if showplayers_name is false playersedit_bar1: false, playersedit_bar2: false, playersedit_bar3: false, playersedit_aura1: false, playersedit_aura2: false, light_radius: "", //dynamic lighting radius light_dimradius: "", //dim radius light_otherplayers: false, //show light to all players _type: "graphic", //identifies the object as a graphic. read-only. _subtype: "token", //"token" (tokens and maps) or "card" _cardid: "", //set to a value if the graphic represents a card. _pageid: "" }
Page (Read Only)
{ _id: "-Abc123", name: "", //Page's title showgrid: true, //are we showing the grid? showdarkness: false, //Is the Fog of War active? showlighting: false, //Is Dynamic Lighting active? width: 25, //width in units height: 25, //height in units snapping_increment: 1.0, //the size of a grid space in units grid_opacity: 0.50, //opacity of the grid fog_opacity: 0.35, //opacity of the fog of war for the GM background_color: "#ffffff", //background color (HEX) gridcolor: "#C0C0C0", //grid color (HEX) grid_type: "square", //eitehr "square", "hexv", or "hexh" scale_number: 5, //1 unit = how much distance scale_units: "ft", //scale is in these units gridlabels: false, //show grid labels for hex grid diagonaltype: "foure", //one of "foure", "pythagorean" (Euclidean), "threefive", or "manhattan" }
Campaign
{ _type: "campaign", _turnorder: "", // a JSON string initiativepage: false, //ID of the page that is currently used for the tracker when turn window is open. Set to false and window will close. playerpageid: false //ID of the page that the player bookmark is set to }
Player
{ _d20userid: "", //The site-wide unique ID of the user. _displayname: "", //Current display name _online: false, color: "#13B9F0", _macrobar: "", //Comma-delimited string of the macros in the player's macro bar. showmacrobar: false, //Show macro bar? _id: "", _type: "player" }
Macro
{ name: "", action: "", visibleto: "", //Comma-delimited list of additional players this macro is visible to. _id: "", _type: "macro", _playerid: "" //Player this macro belongs to }
Rollable Table
{ name: "new-table", showplayers: true, _type: "rollabletable", _id: "" }
Table Item
{ name: "", weight: 1, _type: "tableitem", _id: "", _rollabletableid: "" //ID of the rollable table this item belongs to }
Character
{ name: "", bio: "", gmnotes: "", archived: false, _inplayerjournals: "", //Comma-deliminted list of player IDs _controlledby: "", //Comma-delimited list of player IDs _id: "", _type: "character" }
Attribute
{ name: "Untitled", current: "", max: "", _id: "", _type: "attribute", _characterid: "" }
Ability
{ name: "Untitled_Ability", description: "", action: "", _id: "", _characterid: "", _type: "ability" }
Handout
{ name: "Mysterious Note", notes: "", _inplayerjournals: "", archived: false, _controlledby: "", _type: "handout", _id: "" }
Global Objects
There are several objects that are globally available anywhere in your script.
activePage
(Page object) (Read only) (UNIMP)
A Page
object that points to the page that is currently active for players of the campaign. Note that the GM may be on a different page.
state
This is an object that is initialized as a blank object whenver your script is loaded. You can set whatever properties you want on this object, and they are available to all of your event callbacks, and persist between callbacks.
Note: Eventually this object will be persisted between play sessions, but right now it's not.
state.numTimesTokensMoved = 0; on("change:graphic", function(obj) { state.numTimesTokensMoved = state.numTimesTokensMoved + 1; });