The events that the API can respond to are
ready,
change:(type), change:(type):(property), add:(type), destroy:(type), and
chat:message. The possible types and their properties are listed on
API:Objects.
The change:X events all have the object's current state and its state prior to the change as parameters in the callback function; the object's previous state is a plain JS object, rather than a Roll20 object. The add:X and destroy:X events all have the object's current state as a parameter to the callback function. The chat:message event has a message object as a parameter to the callback function.
Roll20 objects (the first parameter to change events, the only parameter to add/destroy events, and the return value of the various object-finding functions)
all have an
id property with the object's unique (within the campaign) string id, a
get function to get the value of the object's properties, and a
set function to set the value of the object's (non-read-only) properties. Get expects a string parameter of the property name*; the leading underscore on read-only properties is not required. Set can be called with a single object parameter (with properties matching the Roll20 object's properties and values to be set) or two parameters (the first is a string property name, the second is the value to set). Roll20 objects of the types that can be created (see createObj, below) also have a
remove function with no parameters that deletes the object from the campaign.
* for the properties "notes", "gmnotes" and "bio" of character sheet and handout objects, the get function expects a string property name and a function callback. The callback parameter will be the value of the property, instead of the get function itself returning the value.
You can create new objects with
createObj(string type, object attributes). Only graphic, text, path, character, ability, attribute, handout, rollabletable, tableitem, and macro objects can be created. createObj will return the Roll20 object it has just created.
The
object-finding functions are:
- getObj(string type, string id): gets a Roll20 object of the specified type with the specified unique id
- findObjs(object attrs[, object options]): gets an array of Roll20 objects which have properties matching the supplied attributes. If the options parameter is passed with caseInsensitive:true, string comparisons will be case-insensitive.
- filterObjs(function callback): gets an array of Roll20 objects for which the callback function returns true (the callback will be passed the object as a parameter)
- getAllObjs(): gets an array of every Roll20 object in the campaign
- Campaign(): returns the singleton campaign object
Other library functions available are:
- getAttrByName(string character_id, string attribute_name[, string value_type]): Gets the current or max (if value_type == "max") value of the named attribute for the specified character.
- log(varies message): prints a message to the API console (not the browser console)
- sendChat(string speakingAs, string input[, function callback[, object options]]): If speakingAs is in the format "character|character_id" or "player|player_id", the message will be sent as the specified character or player. If callback is specified, the result of the message will be passed directly to the callback method instead of being posted to the chat. If options has noarchive:true, the message will not be added to the game's chat archive. If options has use3d:true, 3d dice rolls will be used. (Obviously, both available options achieve nothing if there is a callback function.)
- toFront(Roll20 obj) and toBack(Roll20 obj): API functions for the same effect as is available to GMs in a graphic's context menu.
- randomInteger(number max): Produces a random integer between 1 (inclusive) and max (inclusive). This function has better distribution than Math.random().
- playerIsGM(string playerid): returns true if the specified player currently has GM permissions
- spawnFx(number x, number y, string type[, string pageid]): spawns an FX of the chosen type at the location (x, y) on the specified page (if the pageid is omitted, the page where the player ribbon currently is will be used)
- spawnFxBetweenPoints(object point1, object point2, string type[, string pageid]): same as spawnFx, except the FX moves from point1 to point2 (each object should have x and y properties)
- spawnWithDefinition(number x, number y, object definition[, string pageid]): same as spawnFx, except the FX is defined with the definition object instead of being a type of FX saved in the campaign.
- playJukeboxPlaylist(string playlistid): begin playing the specified playlist
- stopJukeboxPlaylist(): stop all currently playing playlists
- sendPing(number left, number top, string pageid[, string playerid[, boolean moveAll]]): pings the screen (equivalent to holding the left mouse button) at location (left, top) on the specified page. If you specify the playerid, it will use that player's color (yellow, otherwise), and if you set moveAll to true, it will center the view of all players on that page (like a GM using shift+ping). Although I think the moveAll parameter is bugged ATM.
You also have access to the
Underscore.js library.
Chris S. said:I'm also curious since it's a node backend does that also mean we have access to some of nodes features, or are our scripts parsed into an API reader. I only ask because I stream my game and wanted to know if I could do a request to a server and pass it player data so I can display it more nicely on the stream.
You don't really have access to any Node features directly, but there are some things you can get indirectly. For example, setInterval normally returns an integer (which you can then later pass to clearInterval). Node's (and thereby Roll20's) version of setInterval returns a Timeout object.
EDIT:
Chris S. said:Is there some resource that goes over the API similar to jsDoc?
I just threw together
https://wiki.roll20.net/API:Function_documentation and
https://wiki.roll20.net/API:Function_documentation/Roll20_object
