Roll20 Wiki

{{apibox}}
Roll20 makes a number of functions available that are not part of core JavaScript or some other library.
{{toclimit|3|clear=none}}

== Global variables ==
{| class="wikitable"
|-
! Variable
! Description
|-
| <code>[[#_ (Underscore)|_]]</code>
| This is the namespace object for the [http://underscorejs.org/ Underscore.js] library.
|-
| <code>[[#state|state]]</code>
| Properties of the state object will persist between game sessions.
|}

=== <code>_</code> (Underscore) ===
This is the namespace object for the [http://underscorejs.org/ Underscore.js] library. Underscore has many functions for collection manipulation.

=== <code>state</code> ===
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 ==
{| class="wikitable"
|-
! Return type
! Function
! Description
|-
| [[API:Function documentation/Roll20 object|Roll20 object]]
| <code>[[#Campaign|Campaign]]</code>
| Gets the singleton Campaign [[API:Function documentation/Roll20 object|Roll20 object]].
|-
| [[API:Function documentation/Roll20 object|Roll20 object]]
| <code>[[#createObj|createObj]]</code>
| Creates a new [[API:Function documentation/Roll20 object|Roll20 object]].
|-
| Array of [[API:Function documentation/Roll20 object|Roll20 objects]]
| <code>[[#filterObjs|filterObjs]]</code>
| Gets all [[API:Function documentation/Roll20 object|Roll20 objects]] which pass a predicate test.
|-
| Array of [[API:Function documentation/Roll20 object|Roll20 objects]]
| <code>[[#findObjs|findObjs]]</code>
| Gets all [[API:Function documentation/Roll20 object|Roll20 objects]] with properties that match a given set of attributes.
|-
| Array of [[API:Function documentation/Roll20 object|Roll20 objects]]
| <code>[[#getAllObjs|getAllObjs]]</code>
| Gets all [[API:Function documentation/Roll20 object|Roll20 objects]] in the campaign.
|-
| ''varies''
| <code>[[#getAttrByName|getAttrByName]]</code>
| Gets the current or max value of an attribute [[API:Function documentation/Roll20 object|Roll20 object]].
|-
| [[API:Function documentation/Roll20 object|Roll20 object]]
| <code>[[#getObj|getObj]]</code>
| Gets a specific [[API:Function documentation/Roll20 object|Roll20 object]].
|-
|
| <code>[[#log|log]]</code>
| Logs a message to the API console.
|-
|
| <code>[[#on|on]]</code>
| Registers an event handler.
|-
|
| <code>[[#onSheetWorkerCompleted|onSheetWorkerCompleted]]</code>
| Registers a one-time event handler to run after a full stack of [[Sheet Worker Scripts]] completes.
|-
| Boolean
| <code>[[#playerIsGM|playerIsGM]]</code>
| Checks whether a player currently has GM privileges.
|-
|
| <code>[[#playJukeboxPlaylist|playJukeboxPlaylist]]</code>
| Start playing a jukebox playlist.
|-
| Number
| <code>[[#randomInteger|randomInteger]]</code>
| Generates a random integer value.
|-
|
| <code>[[#sendChat %5BAsynchronous%5D|sendChat]]</code>
| Sends a chat message.
|-
|
| <code>[[#sendPing|sendPing]]</code>
| Sends a ping similar to holding the left mouse button.
|-
|
| <code>[[#spawnFx|spawnFx]]</code>
| Spawns a particle emitter.
|-
|
| <code>[[#spawnFxBetweenPoints|spawnFxBetweenPoints]]</code>
| Spawns a particle emitter that moves from one point to another.
|-
|
| <code>[[#spawnFxWithDefinition|spawnFxWithDefinition]]</code>
| Spawns a particle emitter that is not represented by an FX [[API:Function documentation/Roll20 object|Roll20 object]].
|-
|
| <code>[[#stopJukeboxPlaylist|stopJukeboxPlaylist]]</code>
| Stops all currently playing jukebox playlits.
|-
|
| <code>[[#toBack|toBack]]</code>
| Moves a graphic [[API:Function documentation/Roll20 object|Roll20 object]] below all of the other graphics on the same tabletop layer.
|-
|
| <code>[[#toFront|toFront]]</code>
| Moves a graphic [[API:Function documentation/Roll20 object|Roll20 object]] above all of the other graphics on the same tabletop layer.
|}

=== <code>Campaign</code> ===
{{function parameters}}
{{returns|The singleton campaign [[API:Function documentation/Roll20 object|Roll20 object]].}}
==== Examples ====
<pre data-language="javascript">var currentPageID = Campaign().get('playerpageid'),
    currentPage = getObj('page', currentPageID);</pre>

=== <code>createObj</code> ===
{{function parameters
|type
|''(String)'' The type of [[API:Function documentation/Roll20 object|Roll20 object]] to create. Only {{creatable objects}} may be created.
|attributes
|''(Object)'' The initial values to use for the [[API:Function documentation/Roll20 object|Roll20 object's]] properties.}}
{{returns|The [[API:Function documentation/Roll20 object|Roll20 object]] that was created.}}
==== Examples ====
When creating a [[API:Function documentation/Roll20 object|Roll20 object]] that has a parent object (such as creating an attribute [[API:Function documentation/Roll20 object|Roll20 object]], which is a child of a character [[API:Function documentation/Roll20 object|Roll20 object]]), you must supply the id of the parent in <code>attributes</code>.
<pre data-language="javascript">on('add:character', function(obj) {
    createObj('attribute', {
        name: 'Strength',
        current: 0,
        max: 30,
        characterid: obj.id
    });
});</pre>

When creating a path [[API:Function documentation/Roll20 object|Roll20 object]], you must supply a value for the read-only property <code>_path</code>. This is an exception to the rule that prevents you from setting the value of read-only properties when creating [[API:Function documentation/Roll20 object|Roll20 objects]].
<pre data-language="javascript">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]])
});</pre>

When creating a handout [[API:Function documentation/Roll20 object|Roll20 object]], you cannot set the text or gmnotes at the time of creation.
<pre data-language="javascript">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'
});</pre>

=== <code>filterObjs</code> ===
{{function parameters
|callback
|''(Function)'' A predicate function to test all [[API:Function documentation/Roll20 object|Roll20 objects]] against. The callback function receives a [[API:Function documentation/Roll20 object|Roll20 object]] as a parameter, and should return either <code>true</code> (for [[API:Function documentation/Roll20 object|Roll20 objects]] that will be included in the filterObjs return value) or <code>false</code> (for all other [[API:Function documentation/Roll20 object|Roll20 objects]]).}}
{{returns|An array of [[API:Function documentation/Roll20 object|Roll20 objects]] which passed the predicate test.}}
==== Examples ====
<pre data-language="javascript">var tokenName = getMyTokenName(),
    duplicateTokens = filterObjs(function(obj) {
        if (obj.get('type') !== 'graphic' || obj.get('subtype') !== 'token' || obj.get('name') === tokenName) return false;
        return obj.get('name').indexOf(tokenName) === 0 && /\d+$/.text(obj.get('name'));
    });</pre>

=== <code>findObjs</code> ===
{{function parameters
|attributes
|''(Object)'' A collection of key:value pairs to match with [[API:Function documentation/Roll20 object|Roll20 objects]] in the campaign.
|options
|''(Object, optional)'' If <code>options.caseInsensitive</code> is <code>true</code>, string comparisons between [[API:Function documentation/Roll20 object|Roll20 objects]] and <code>attributes</code> will be case-insensitive.}}
{{returns|An array of [[API:Function documentation/Roll20 object|Roll20 objects]] with properties that match <code>attributes</code>.}}
==== Examples ====
<pre data-language="javascript">var npcs = findObjs({ type: 'character', controlledby: '' });</pre>

=== <code>getAllObjs</code> ===
{{function parameters}}
{{returns|An array of all [[API:Function documentation/Roll20 object|Roll20 objects]] in the campaign.}}
==== Examples ====
<pre data-language="javascript">var everything = getAllObjs();</pre>

=== <code>getAttrByName</code> ===
{{function parameters
|character_id
|''(String)'' The id of the character [[API:Function documentation/Roll20 object|Roll20 object]] that is the parent of the attribute [[API:Function documentation/Roll20 object|Roll20 object]] you want the value of.
|attribute_name
|''(String)'' The name of the attribute [[API:Function documentation/Roll20 object|Roll20 object]] you want the value of.
|value_type
|''(String, optional)'' Either <code>"current"</code> or <code>"max"</code> (defaults to "current" if omitted).}}
{{returns|The <code>current</code> or <code>max</code> property of the appropriate attribute. If the desired property is not set, the default value specified by the character sheet (if there is a default) will be used instead.}}
==== Examples ====
<pre data-language="javascript">var character = getMyCharacter(),
    strength = getAttrByName(character.id, 'strength'),
    strength_max = getAttrByName(character.id, 'strength', 'max');</pre>

=== <code>getObj</code> ===
{{function parameters
|type
|''(String)'' The type of [[API:Function documentation/Roll20 object|Roll20 object]] to get.
|id
|''(String)'' The unique id for the [[API:Function documentation/Roll20 object|Roll20 object]] to get.}}
{{returns|The specified [[API:Function documentation/Roll20 object|Roll20 object]].}}
==== Examples ====
<pre data-language="javascript">on('chat:message', function(msg) {
    var sendingPlayer = getObj('player', msg.playerid);
});</pre>

=== <code>log</code> ===
{{function parameters
|message
|''(varies)'' The message to post to the API console. The <code>message</code> parameter will be transformed into a String with <code>JSON.stringify</code>.}}
{{returns}}
==== Examples ====
<pre data-language="javascript">on('chat:message', function(msg) {
    log('Message received from:');
    log(getObj('player', msg.playerid));
});</pre>
<div style="margin:1em;margin-bottom:20px;padding:6px 10px;font-family:Consolas, 'Liberation Mono', Courier, monospace;font-size:13px;border:1px solid #ccc;border-radius:3px;background-color:#272822;color:#e6db74">"Message received from:"<br>
<span style="color:#f8f8f2">{</span>"_d20userid"<span style="color:#f8f8f2">:</span>"123456"<span style="color:#f8f8f2">,</span>"_displayname"<span style="color:#f8f8f2">:</span>"John Doe"<span style="color:#f8f8f2">,</span>"speakingas"<span style="color:#f8f8f2">:</span>""<span style="color:#f8f8f2">,</span>"_online"<span style="color:#f8f8f2">:</span><span style="color:#ae81ff">true</span><span style="color:#f8f8f2">,</span>"color"<span style="color:#f8f8f2">:</span>"#885b68"<span style="color:#f8f8f2">,</span>"_macrobar"<span style="color:#f8f8f2">:</span>"-J16Z-dRU5tleKiKOg0X|-K3F_4q_b1p-Vdiwgn1t"<span style="color:#f8f8f2">,</span>"showmacrobar"<span style="color:#f8f8f2">:</span><span style="color:#ae81ff">true</span><span style="color:#f8f8f2">,</span>"_id"<span style="color:#f8f8f2">:</span>"-J16Z-dRU5tleKiKOc0X"<span style="color:#f8f8f2">,</span>"_type"<span style="color:#f8f8f2">:</span>"player"<span style="color:#f8f8f2">,</span>"_lastpage"<span style="color:#f8f8f2">:</span>""<span style="color:#f8f8f2">}</span></div>

=== <code>on</code> ===
{{function parameters
|event
|''(String)'' There are five types of event:
:* ready
:* change
:* add
:* destroy
:* chat
: With the exception of ''ready'', all event types must also be paired with an object type. For ''chat'', this is always ''message''. For everything else, this is the <code>type</code> property of a [[API:Function documentation/Roll20 object|Roll20 object]]. In addition to the object type, ''change'' events can also optionally specify a property of the specified [[API:Function documentation/Roll20 object|Roll20 object]] to watch.
: The 2-3 parts of the event (type, object, and optionally property) are separated by colons. So, valid <code>event</code> strings include but are not limited to "ready", "chat:message", "change:graphic", "change:campaign:playerpageid", "add:character", and "destroy:handout".
|callback
|''(Function)'' The function that will be called when the specified event fires. The parameters passed depend on the event type:
:* ''ready'' events have no callback parameters.
:* ''change'' events have an <code>obj</code> parameter, which is a reference to the [[API:Function documentation/Roll20 object|Roll20 object]] as it exists after the change, and a <code>prev</code> parameter, which is a plain old JavaScript object with properties matching the [[API:Function documentation/Roll20 object|Roll20 object]] prior to the change event.
:* ''add'' events have an <code>obj</code> parameter, which is a reference to the new [[API:Function documentation/Roll20 object|Roll20 object]].
:* ''destroy'' events have an <code>obj</code> parameter, which is a reference to the no-longer existing [[API:Function documentation/Roll20 object|Roll20 object]].
:* ''chat'' events have a <code>msg</code> parameter, which contains the details of the message that was sent to the chat.}}
{{returns}}
==== Examples ====
Events are fired in the order they were registered, and from most to least specific. In this example, a change to a graphic [[API:Function documentation/Roll20 object|Roll20 object's]] <code>left</code> property will result in <code>function3</code> getting called, followed by <code>function1</code> and then <code>function2</code>.
<pre data-language="javascript">on('change:graphic', function1);
on('change:graphic', function2);
on('change:graphic:left', function3);</pre>

''add'' events will attempt to fire for [[API:Function documentation/Roll20 object|Roll20 objects]] that are already in the campaign when a new session starts. In order to prevent this behavior, you can wait to register your ''add'' event until the ''ready'' event fires.
<pre data-language="javascript">on('add:graphic', function(obj) {
    // When the session begins, this function will be called for every graphic in the campaign
    // This function will also be called whenever a new graphic Roll20 object is created
});

on('ready', function() {
    on('add:graphic', function(obj) {
        // This function will *only* be called when a new graphic Roll20 object is created, not for ones that already exist
    });
});</pre>

The <code>pre</code> parameter for ''change'' events is not a [[API:Function documentation/Roll20 object|Roll20 object]], it is a plain old JavaScript object. As such, you cannot use the <code>get</code> or <code>set</code> functions, and you cannot omit the leading underscores on read-only properties.
<pre data-language="javascript">on('change:graphic', function(obj, prev) {
    var id1 = obj.id,         // all three are equivalent
        id2 = obj.get('id'),
        id3 = obj.get('_id'),

        id4 = prev.id,        // undefined
        id5 = prev.get('id'), // undefined is not a function
        id6 = prev._id;       // correct

    // both are equivalent
    obj.set('left', 70);
    obj.set({
        left: 70
    });

    prev.set('left', 70); // undefined is not a function
    prev.set({            // undefined is not a function
        left: 70
    });
    prev.left = 70;       // correct, although it won't change anything on the tabletop
});</pre>

For the async fields of character and handout [[API:Function documentation/Roll20 object|Roll20 objects]] (<code>notes</code>, <code>gmnotes</code>, and <code>bio</code>), the <code>prev</code> parameter will not hold the data you need. (It will have a numeric identifier used by the system instead.) If you need to access the previous value of one of these fields, you will have to keep track of it yourself:
<pre data-language="javascript">on('ready', function() {
    if (!state.example) state.example = { bioCache: {} };
});

on('change:character:bio', function(obj, prev) {
    obj.get('bio', function(text) {
        state.example.bioCache[obj.id] = text;

        // do stuff...

        if (shouldRevertBio()) {
            obj.set('bio', state.example.bioCache[obj.id]);
        }
    });
});</pre>

=== <code>onSheetWorkerCompleted</code> ===
{{function parameters
|callback
|''(Function)'' The function that will be called when the current 'stack' of [[Sheet Worker Scripts]] completes.}}
{{returns}}
==== Examples ====
This function is intended to be called prior to [[API:Function documentation/Roll20 object#setWithWorker|setWithWorker]]. The <code>callback</code> function will be called only once.
<pre data-language="javascript">var myCharacter = ...,
    mySourceAttr = findObjs({ type: 'attribute', characterid: myCharacter.id, name: 'mySourceAttribute' })[0];

onSheetWorkerCompleted(function() {
    var calculatedAttr = findObjs({ type: 'attribute', characterid: myCharacter.id, name: 'myCalculatedAttribute' })[0];
    // do something with calculatedAttr.get('current');
});

mySourceAttr.setWithWorker({ current: 5 });</pre>

=== <code>playerIsGM</code> ===
{{function parameters
|player_id
|''(String)'' The id of the player [[API:Function documentation/Roll20 object|Roll20 object]] to check.}}
{{returns|<code>true</code> if the player currently has GM permissions, or <code>false</code> otherwise.}}
==== Examples ====
This function is especially useful for limiting API commands to GM use.
<pre data-language="javascript">on('chat:message', function(msg) {
    if (msg.type !== 'api') return;

    if (msg.content.indexOf('!playercommand') === 0) {
        // ...
    } else if (msg.content.indexOf('!gmcommand') === 0) {
        if (!playerIsGM(msg.playerid)) return;
        // ...
    }
});</pre>

=== <code>playJukeboxPlaylist</code> ===
'''Note:''' Using Jukebox/SoundCloud functions will not throw errors, but they no longer do anything.
[http://blog.roll20.net/post/150968376980/in-regards-to-soundcloud "In Regards to SoundCloud"]

{{function parameters
|playlist_id
|''(String)'' The id of the playlist to start playing.}}
{{returns}}
==== Examples ====
<pre data-language="javascript">var playlists = JSON.parse(Campaign().get('jukeboxfolder')),
    myPlaylist = _.find(playlists, (folder) => _.isObject(folder) && folder.n === myPlaylistName);
playJukeboxPlaylist(myPlaylist.id);</pre>

=== <code>randomInteger</code> ===
{{function parameters
|max
|''(Number)'' The maximum number to return, inclusive.}}
{{returns|A random integer between 1 (inclusive) and <code>max</code> (inclusive). This function has better distribution than <code>Math.random()</code>, and is recommended over it. This function doesn't make use of the [[Quantum Roll]] feature used by the dice engine, but it does use the same pseudorandom algorithm that the dice engine will fall back on if Quantum Roll is unavailable.}}
==== Examples ====
Because this function returns an integer from 1 to <code>max</code>, it is ideal for quickly generating a dice roll outcome if you don't need the full strength of Roll20's [[Dice Reference|dice engine]].
<pre data-language="javascript">var d20Result = randomInteger(20); // roughly equivalent to rolling a 20-sided die</pre>

=== <code>sendChat</code> {{asynchronous}} ===
{{function parameters
|speakingAs
|''(String)'' The name to attach to the message being sent. If <code>speakingAs</code> is in the format <code>player{{!}}player_id</code> or <code>character{{!}}character_id</code>, the message will be sent as that player or character. Otherwise, the message will use the given name as though a GM had used the '''/as''' command.
|message
|''(String)'' The message to send to the chat.
|callback
|''(Function, optional)'' If <code>callback</code> is specified, the result of the chat message will be passed to it instead of appearing in the chat. The parameter of the callback method is an array of message objects.
|options
|''(Object, optional)'' If <code>options.noarchive</code> is <code>true</code>, the message will not be added to the chat archive. If <code>options.use3d</code> is <code>true</code>, dice rolls in the message will use the 3D dice feature. Options are not applicable if <code>callback</code> is specified.}}
{{returns}}
==== Examples ====
<pre data-language="javascript">sendChat('Example', 'This is a simple example.');</pre>

You can easily write code to send a message as the same player or character that triggered a ''chat:message'' event.
<pre data-language="javascript">on('chat:message', function(msg) {
    var character = findObjs({ type: 'character', name: msg.who })[0],
        player = getObj('player', msg.playerid),
        message = ' said something';

    if (character) sendChat('character|'+character.id, character.get('name')+message);
    else sendChat('player|'+player.id, player.get('displayname')+message);
});</pre>

The <code>callback</code> parameter is useful if you need to leverage Roll20's [[Dice Reference|dice engine]]. There is no particular need for a <code>speakingAs</code> value when using the <code>callback</code>, since the message won't appear in the chat anyway.
<pre data-language="javascript">sendChat('', '/r 2d20k1+'+strengthMod, function(ops) {
    var msg = ops[0];
    // ...
});</pre>

<code>options.noarchive</code> is primarily designed for sending players menus made from [[API:Chat#API Command Buttons|API Command buttons]] without clogging their chat history.
<pre data-language="javascript">sendChat('System', '[Clear changes](!clear)\n[Add tile](!add)\n[View sample](!view)\n[Save layout](!save)', null, { noarchive: true });</pre>

=== <code>sendPing</code> ===
{{function parameters
|left
|''(Number)'' The x-coordinate to place the ping at.
|top
|''(Number)'' The y-coordinate to place the ping at.
|page_id
|''(String)'' The id of the page [[API:Function documentation/Roll20 object|Roll20 object]] to place the ping on.
|player_id
|''(String, optional)'' The ping will use the specified player's color. If <code>player_id</code> is omitted, the ping will be yellow.
|moveAll
|''(Boolean, optional)'' If <code>moveAll</code> is <code>true</code>, all of the players on the appropriate page will have their views centered on the ping. If no value is provided for moveAll, it defaults to false; when it is false, no players are moved, but the ping is visible to everyone.
|visibleTo
|''(String, Array, Variable, optional)'' Specifies one or more players that will receive the ping. If at least one player is specified, no other players will see the ping or be moved.

Note: If sending to a single player, you can include their player ID as a string or variable.

If sending multiple IDs, they can be included either as an array, or as a comma-delimited text string.

The player ID [[API:Utility_Functions|can be obtained using the findObjs() function]] and you can then use playerIsGM(playerID) to determine if an individual player ID is a GM. In this way, you should be able to find and pass in the player IDs of GMs into the sendPing function.


}}
{{returns}}

==== Examples ====
<pre data-language="javascript">on('chat:message', function(msg) {
    var obj;
    if (msg.type === 'api' && msg.content.indexOf('!ping') === 0) {
        if (!msg.selected) return;
        obj = getObj(msg.selected[0]._type, msg.selected[0]._id);
        sendPing(obj.get('left'), obj.get('top'), obj.get('pageid'), msg.playerid, true); // center everyone on the selected token
    }
});</pre>

<pre data-language="javascript">const getGMPlayers = (pageid) => findObjs({type:'player'})
    .filter((p)=>playerIsGM(p.id))
    .filter((p)=>undefined === pageid || p.get('lastpage') === pageid)
    .map(p=>p.id)
    ;

const sendGMPing = (left, top, pageid, playerid=null, moveAll=false) => {
    let players = getGMPlayers(pageid);
    if(players.length){
        sendPing(left,top,pageid,playerid,moveAll,players);
    }
};</pre>

=== <code>spawnFx</code> ===
{{function parameters
|left
|''(Number)'' The x-coordinate to place the particle emitter.
|top
|''(Number)'' The y-coordinate to place the particle emitter.
|type
|''(String)'' The type of particle emitter to place. For built-in effects, this should be <code>"type-color"</code>, where ''type'' is one of <code>bomb</code>, <code>bubbling</code>, <code>burn</code>, <code>burst</code>, <code>explode</code>, <code>glow</code>, <code>missile</code>, or <code>nova</code> and ''color'' is one of <code>acid</code>, <code>blood</code>, <code>charm</code>, <code>death</code>, <code>fire</code>, <code>frost</code>, <code>holy</code>, <code>magic</code>, <code>slime</code>, <code>smoke</code>, or <code>water</code>. For custom effects, this should be the <code>id</code> of the FX [[API:Function documentation/Roll20 object|Roll20 object]].
: ''Note: <code>beam</code>, <code>breath</code>, and <code>splatter</code> types cannot be used with <code>spawnFx</code>. See <code>[[#spawnFxBetweenPoints|spawnFxBetweenPoints]]</code> instead.''
|page_id
|''(String, optional)'' The id of the page [[API:Function documentation/Roll20 object|Roll20 object]] to place the particle emitter on. If omitted, <code>Campaign().get('playerpageid')</code> will be used instead.}}
{{returns}}
==== Examples ====
<pre data-language="javascript">spawnFx(1400, 1400, 'bubbling-acid');</pre>

=== <code>spawnFxBetweenPoints</code> ===
{{function parameters
|start
|''(Object)'' The starting point for the particle emitter. The point should be in the format <code>{ x: ''number'', y: ''number'' }</code>.
|end
|''(Object)'' The ending point for the particle emitter. The point should be in the format <code>{ x: ''number'', y: ''number'' }</code>.
|type
|''(String)'' The type of particle emitter to place. For built-in effects, this should be <code>"type-color"</code>, where ''type'' is one of <code>beam</code>, <code>bomb</code>, <code>breath</code>, <code>bubbling</code>, <code>burn</code>, <code>burst</code>, <code>explode</code>, <code>glow</code>, <code>missile</code>, <code>nova</code>, or <code>splatter</code> and ''color'' is one of <code>acid</code>, <code>blood</code>, <code>charm</code>, <code>death</code>, <code>fire</code>, <code>frost</code>, <code>holy</code>, <code>magic</code>, <code>slime</code>, <code>smoke</code>, or <code>water</code>. For custom effects, this should be the <code>id</code> of the FX [[API:Function documentation/Roll20 object|Roll20 object]].
|page_id
|''(String, optional)'' The id of the page [[API:Function documentation/Roll20 object|Roll20 object]] to place the particle emitter on. If omitted, <code>Campaign().get('playerpageid')</code> will be used instead.}}
{{returns}}
==== Examples ====
<pre data-language="javascript">spawnFxBetweenPoints({ x: 1400, y: 1400 }, { x: 2100, y: 2100 }, 'beam-acid');</pre>

=== <code>spawnFxWithDefinition</code> ===
{{function parameters
|left
|''(Number)'' The x-coordinate to place the particle emitter.
|top
|''(Number)'' The y-coordinate to place the particle emitter.
|definition
|''(Object)'' The characteristics of the particle emitter to place. See [[Custom FX]] for a list of possible properties and the properties of the default particle emitter types and colors. See [[FX Library]] for some custom effects Roll20 users have come up with.
|page_id
|''(String, optional)'' The id of the page [[API:Function documentation/Roll20 object|Roll20 object]] to place the particle emitter on. If omitted, <code>Campaign().get('playerpageid')</code> will be used instead.}}
{{returns}}
==== Examples ====
<pre data-language="javascript">// these two are equivalent
spawnFx(1400, 1400, 'bubbling-acid');
spawnFxWithDefinition(1400, 1400, {
    maxParticles: 200,
    size: 15,
    sizeRandom: 3,
    lifeSpan: 20,
    lifeSpanRandom: 5,
    speed: 7,
    speedRandom: 2,
    gravity: { x: 0.01, y: 0.65 },
    angle: 270,
    angleRandom: 35,
    emissionRate: 1,
    startColour:       [0, 35, 10, 1],
    startColourRandom: [0, 10, 10, 0.25],
    endColour:         [0, 75, 30, 0],
    endColourRandom:   [0, 20, 20, 0]
});</pre>

=== <code>stopJukeboxPlaylist</code> ===
{{function parameters}}
{{returns}}
==== Examples ====
<pre data-language="javascript">stopJukeboxPlaylist();</pre>

=== <code>toBack</code> ===
{{function parameters
|obj
|''([[API:Function documentation/Roll20 object|Roll20 object]])'' The [[API:Function documentation/Roll20 object|Roll20 object]] to send to the back of its layer.}}
{{returns}}
==== Examples ====
<pre data-language="javascript">on('chat:message', function(msg) {
    if (msg.type === 'api' && msg.content === '!toback' && msg.selected) {
        _.each(msg.selected, (s) => {
            toBack(getObj(s._type, s._id));
        });
    }
});</pre>

=== <code>toFront</code> ===
{{function parameters
|obj
|''([[API:Function documentation/Roll20 object|Roll20 object]])'' The [[API:Function documentation/Roll20 object|Roll20 object]] to bring to the front of its layer.}}
{{returns}}
==== Examples ====
<pre data-language="javascript">on('ready', function() {
    on('add:graphic', function(obj) {
        toFront(obj);
    });
});</pre>

[[Category:API|Function documentation]]