Mod:Function
From Roll20 Wiki
Roll20 makes a number of functions available that are not part of core JavaScript or some other library.
Global variables
| Variable | Description |
|---|---|
_
|
This is the namespace object for the Underscore.js library. |
state
|
Properties of the state object will persist between game sessions. |
_ (Underscore)
This is the namespace object for the Underscore.js library. Underscore has many functions for collection manipulation.
state
Properties of the state object will persist between game sessions. The same state object is also shared between all API scripts in a campaign, so it is strongly recommended that when writing values to state, you minimize your footprint as much as possible in order to avoid name collisions. Note: state gets serialized with JSON, so you cannot store functions or objects with cyclical references.
Global functions
| Return type | Function | Description |
|---|---|---|
| Roll20 object | Campaign
|
Gets the singleton Campaign Roll20 object. |
| Roll20 object | createObj
|
Creates a new Roll20 object. |
| Array of Roll20 objects | filterObjs
|
Gets all Roll20 objects which pass a predicate test. |
| Array of Roll20 objects | findObjs
|
Gets all Roll20 objects with properties that match a given set of attributes. |
| Array of Roll20 objects | getAllObjs
|
Gets all Roll20 objects in the campaign. |
| varies | getAttrByName
|
Gets the current or max value of an attribute Roll20 object. |
| Roll20 object | getObj
|
Gets a specific Roll20 object. |
log
|
Logs a message to the API console. | |
on
|
Registers an event handler. | |
| Boolean | playerIsGM
|
Checks whether a player currently has GM privileges. |
playJukeboxPlaylist
|
Start playing a jukebox playlist. | |
| Number | randomInteger
|
Generates a random integer value. |
sendChat
|
Sends a chat message. | |
sendPing
|
Sends a ping similar to holding the left mouse button. | |
spawnFx
|
Spawns a particle emitter. | |
spawnFxBetweenPoints
|
Spawns a particle emitter that moves from one point to another. | |
spawnWithDefinition
|
Spawns a particle emitter that is not represented by an FX Roll20 object. | |
stopJukeboxPlaylist
|
Stops all currently playing jukebox playlits. | |
toBack
|
Moves a graphic Roll20 object below all of the other graphics on the same tabletop layer. | |
toFront
|
Moves a graphic Roll20 object above all of the other graphics on the same tabletop layer. |
Campaign
Parameters
No parameters
Returns
The singleton campaign Roll20 object.
Examples
var currentPageID = Campaign().get('playerpageid'),
currentPage = getObj('page', currentPageID);
createObj
Parameters
- type
- (String) The type of Roll20 object to create. Only 'graphic', 'text', 'path', 'character', 'ability', 'attribute', 'handout', 'rollabletable', 'tableitem', and 'macro' may be created.
- attributes
- (Object) The initial values to use for the Roll20 object's properties.
Returns
The Roll20 object that was created.
Examples
When creating a Roll20 object that has a parent object (such as creating an attribute Roll20 object, which is a child of a character Roll20 object), you must supply the id of the parent in attributes.
on('add:character', function(obj) {
createObj('attribute', {
name: 'Strength',
current: 0,
max: 30,
characterid: obj.id
});
});
When creating a path Roll20 object, you must supply a value for the read-only property _path. This is an exception to the rule that prevents you from setting the value of read-only properties when creating Roll20 objects.
createObj('path', {
left: 7000,
top: 140,
width: 140,
height: 140,
layer: 'objects',
path: JSON.stringify([['M', 0, 0], ['L', 70, 0], ['L', 0, 70], ['L', 0, 0]])
});
When creating a handout Roll20 object, you cannot set the text or gmnotes at the time of creation.
var handout = createObj('handout', {
name: 'A Letter Addressed to You',
inplayerjournals: 'all',
archived: false
});
handout.set({
notes: 'Notes can only be set after the handout is created',
gmnotes: 'GM Notes can only be set after the handout is created'
});
