Character Vault
Any Concept / Any System
Compendium
Your System Come To Life
Roll20 for Android
Streamlined for your Tablet
Roll20 for iPad
Streamlined for your Tablet

Personal tools

Difference between revisions of "API:Events"

From Roll20 Wiki

Jump to: navigation, search
(Created page with "There are several different types of events that you can respond to. In general, each type of object has a corresponding event for changes, additions, and removals. Each event...")
 
 
(23 intermediate revisions by 6 users not shown)
Line 1: Line 1:
 +
<div style="background:#f0e2a1; border: 3px solid #dbc870; padding: 10px;">
 +
<big>'''''Attention:'''''
 +
''Roll20 is no longer maintaining this document on the community wiki. For the most up-to-date information please visit this page on our [http://Roll20.net/help Help Center] for assistance: [https://roll20.zendesk.com/hc/en-us/articles/360037772813-API-Events Here]. For more information you can email us at Team@roll20.net''</big>
 +
</div>
 +
 +
{{apibox}}
 +
 
There are several different types of events that you can respond to. In general, each type of object has a corresponding event for changes, additions, and removals. Each event will be triggered once per object that changes. If more than one property on the object changes at the same time, only one "global" event (e.g. change:graphic) is triggered.
 
There are several different types of events that you can respond to. In general, each type of object has a corresponding event for changes, additions, and removals. Each event will be triggered once per object that changes. If more than one property on the object changes at the same time, only one "global" event (e.g. change:graphic) is triggered.
  
Line 4: Line 11:
 
When you listen to an event, you create a function known as a '''callback''' that is executed anytime the event occurs. The callback function receives several parameters which are objects that tell you information you want to know about the event so you can decide what to do.
 
When you listen to an event, you create a function known as a '''callback''' that is executed anytime the event occurs. The callback function receives several parameters which are objects that tell you information you want to know about the event so you can decide what to do.
  
Callback paramters for each event will vary, but include:
+
Callback parameters for each event will vary, but include:
  
 
'''obj'''
 
'''obj'''
 +
 
The object that was changed. Any changes you make to this object will also be saved to the game. So if you want to move a Graphic object to the left, you would modify the <code>left</code> property of <code>obj</code> using <code>set</code>.
 
The object that was changed. Any changes you make to this object will also be saved to the game. So if you want to move a Graphic object to the left, you would modify the <code>left</code> property of <code>obj</code> using <code>set</code>.
  
 
* <code>obj.get("property")</code> returns the current value for the property.
 
* <code>obj.get("property")</code> returns the current value for the property.
 
* <code>obj.set("property", "newvalue")</code> sets a new value for the property. If you're changing several properties at once you can pass an object: <code>obj.set({left: 10, top: 20});</code>
 
* <code>obj.set("property", "newvalue")</code> sets a new value for the property. If you're changing several properties at once you can pass an object: <code>obj.set({left: 10, top: 20});</code>
* <code>obj.previous("property")</code> gets the previous value for the property. This can be used in event callbacks to determine "how much" a property has changed.
 
  
===Object Events===
 
  
 +
'''prev'''
 +
 +
This is an object of the properties of the <code>obj</code> as they were before any changes were made due to this event. Useful for determining "how much" a property has changed.
 +
 +
''NOTE:'' This is a basic object, so you access the properties using bracket-notation: <code>prev["bar1_value"]</code>, NOT using set or get functions.
 +
 +
===Event Ordering===
 +
 +
Events are fired synchronously (meaning each function won't start until the previous one has finished) in order from first-bound to last-bound, and also from specific property to general object. So given the following:
 +
 +
<pre data-language="javascript">
 +
on("change:graphic", function1);
 +
on("change:graphic", function2);
 +
on("change:graphic:left", function3);
 +
</pre>
 +
 +
If the objects <code>left</code> property changed, then the order would be function3, then function1, then function2.
 +
 +
In addition, if you have multiple scripts in your campaign, the scripts are loaded in the same order they appear on your Campaign Scripts page, from left-to-right.
 +
 +
'''Note:''' Events are only triggered by changes made by players/the GM playing the game. Events will not be triggered by API changes. So if a player moves a piece on the tabletop, you would receive a "change:graphic" event. If you modify the same graphic's property in an API script, there will not be a "change:graphic" event triggered.
 +
 +
===Campaign Events===
 +
 +
'''ready'''
 +
 +
This event fires after all the current data for the campaign has been loaded. So if you want to find a list of all objects in a campaign, or a specific object that is already in the Campaign, be sure to only look for it after the ready event fires. In addition, if you bind to <code>add</code> events (such as <code>add:graphic</code>) before the <code>ready</code> event fires, you will receive add events for objects that were already present in the campaign.
 +
 +
<pre data-language="javascript">
 +
on("ready", function() {
 +
  var tokenThatAlreadyExisted = getObj("graphic", "-ABc123");
 +
});
 +
</pre>
 +
 +
'''change:campaign:playerpageid'''
 +
 +
Fired whenever the page that the players are currently on changes.
 +
 +
'''change:campaign:turnorder'''
 +
 +
Fired whenever the turn order listing for the campaign changes.
 +
 +
'''change:campaign:initiativepage'''
 +
 +
Fired whenever the turn order is hidden or shown for a page. This may not be the same as the ID of the currently active page. If this is set to <code>false</code> (including if an API script sets it to false), it will close the turn order for all GMs/players. Setting it to a valid page ID will open it for all GMs/players.
 +
 +
===Object Events===
  
 
'''change:graphic'''
 
'''change:graphic'''
 +
 
Triggered whenever a Graphic object (which is almost any type of object on the tabletop, including tokens, maps, and cards) changes.
 
Triggered whenever a Graphic object (which is almost any type of object on the tabletop, including tokens, maps, and cards) changes.
  
Callback paramters: obj
+
Note: API created Graphic objects will trigger this event on create.
 +
 
 +
Callback paramters: obj, prev
  
 
<pre data-language="javascript">
 
<pre data-language="javascript">
on("change:graphic", function(obj) {     
+
on("change:graphic", function(obj, prev) {     
   //Do something with "obj" here
+
   //Do something with "obj" here. "prev" is a list of previous values.
 +
  // Note that "obj" and "prev" are different TYPES of objects.
 +
  // to work with obj you need to use obj.get("name");
 +
  // to work with prev you can use prev["name"];
 
});
 
});
 
</pre>
 
</pre>
Line 29: Line 88:
  
 
'''change:graphic:(property)'''
 
'''change:graphic:(property)'''
 +
 
You can also bind to an event for each specific property on the object. So if you have a script that you want to run only when the <code>rotation</code> changes, you would do:
 
You can also bind to an event for each specific property on the object. So if you have a script that you want to run only when the <code>rotation</code> changes, you would do:
  
 
<pre data-language="javascript">
 
<pre data-language="javascript">
on("change:graphic:rotation", function(obj) {     
+
on("change:graphic:rotation", function(obj, prev) {     
 
   //Always set rotation back to 0, so no one can rotate objects.     
 
   //Always set rotation back to 0, so no one can rotate objects.     
 
   obj.set("rotation", 0);
 
   obj.set("rotation", 0);
Line 39: Line 99:
  
 
'''add:graphic'''
 
'''add:graphic'''
 +
 
Triggered whenever a graphic object is added to the tabletop for the first time. Will also be called for existing objects when the tabletop starts up if you bind to this event ''outside'' of the <code>ready</code> event.
 
Triggered whenever a graphic object is added to the tabletop for the first time. Will also be called for existing objects when the tabletop starts up if you bind to this event ''outside'' of the <code>ready</code> event.
  
Line 57: Line 118:
 
   started = true;
 
   started = true;
 
});
 
});
 +
</pre>
  
 
'''destroy:graphic'''
 
'''destroy:graphic'''
 +
 
Triggered whenver a graphic object was removed from the tabletop.
 
Triggered whenver a graphic object was removed from the tabletop.
  
Line 69: Line 132:
 
change:path, add:path, destroy:path, change:text, add:text, destroy:text, change:token, add:token, destroy:token, change:card, add:card, destroy:card
 
change:path, add:path, destroy:path, change:text, add:text, destroy:text, change:token, add:token, destroy:token, change:card, add:card, destroy:card
  
===Chat Events and Functions===
+
See [[API:Objects|the Objects reference]] for a complete list of all object types and sub-types.
 
+
[[Category:API|Events]]
'''chat:message'''
+
 
+
Triggered whenever a new chat message is received. Note that if the message is of type "rollresult", you will need to call <code>JSON.parse()</code> on the content of the message to get an object which contains information on the roll results. If the message is of type "api", then it hasn't been shown to anyone, and the player who sent the chat message is probably expecting an API script to do something as a result of the message.
+
 
+
Callback parameter:
+
<pre data-language="javascript">
+
{   
+
  who: "Riley D.", //The person who sent the message. Can be any string.
+
  type: "general", //One of "general", "rollresult", "emote", "whisper", "desc", "api"
+
  content: "The chat message", //The chat message, if it's a rollresult this will be a JSON string of data about the roll
+
  target: "-Abc123", //For whispers, the target of the whisper
+
}
+
</pre>
+

Latest revision as of 17:55, 18 February 2020

Attention: Roll20 is no longer maintaining this document on the community wiki. For the most up-to-date information please visit this page on our Help Center for assistance: Here. For more information you can email us at Team@roll20.net

Roll20 API

Getting Started


Reference


Cookbook (Examples)


Community Scripts

There are several different types of events that you can respond to. In general, each type of object has a corresponding event for changes, additions, and removals. Each event will be triggered once per object that changes. If more than one property on the object changes at the same time, only one "global" event (e.g. change:graphic) is triggered.

Contents

[edit] Callback Parameters

When you listen to an event, you create a function known as a callback that is executed anytime the event occurs. The callback function receives several parameters which are objects that tell you information you want to know about the event so you can decide what to do.

Callback parameters for each event will vary, but include:

obj

The object that was changed. Any changes you make to this object will also be saved to the game. So if you want to move a Graphic object to the left, you would modify the left property of obj using set.

  • obj.get("property") returns the current value for the property.
  • obj.set("property", "newvalue") sets a new value for the property. If you're changing several properties at once you can pass an object: obj.set({left: 10, top: 20});


prev

This is an object of the properties of the obj as they were before any changes were made due to this event. Useful for determining "how much" a property has changed.

NOTE: This is a basic object, so you access the properties using bracket-notation: prev["bar1_value"], NOT using set or get functions.

[edit] Event Ordering

Events are fired synchronously (meaning each function won't start until the previous one has finished) in order from first-bound to last-bound, and also from specific property to general object. So given the following:

on("change:graphic", function1);
on("change:graphic", function2);
on("change:graphic:left", function3);

If the objects left property changed, then the order would be function3, then function1, then function2.

In addition, if you have multiple scripts in your campaign, the scripts are loaded in the same order they appear on your Campaign Scripts page, from left-to-right.

Note: Events are only triggered by changes made by players/the GM playing the game. Events will not be triggered by API changes. So if a player moves a piece on the tabletop, you would receive a "change:graphic" event. If you modify the same graphic's property in an API script, there will not be a "change:graphic" event triggered.

[edit] Campaign Events

ready

This event fires after all the current data for the campaign has been loaded. So if you want to find a list of all objects in a campaign, or a specific object that is already in the Campaign, be sure to only look for it after the ready event fires. In addition, if you bind to add events (such as add:graphic) before the ready event fires, you will receive add events for objects that were already present in the campaign.

on("ready", function() {
  var tokenThatAlreadyExisted = getObj("graphic", "-ABc123");
});

change:campaign:playerpageid

Fired whenever the page that the players are currently on changes.

change:campaign:turnorder

Fired whenever the turn order listing for the campaign changes.

change:campaign:initiativepage

Fired whenever the turn order is hidden or shown for a page. This may not be the same as the ID of the currently active page. If this is set to false (including if an API script sets it to false), it will close the turn order for all GMs/players. Setting it to a valid page ID will open it for all GMs/players.

[edit] Object Events

change:graphic

Triggered whenever a Graphic object (which is almost any type of object on the tabletop, including tokens, maps, and cards) changes.

Note: API created Graphic objects will trigger this event on create.

Callback paramters: obj, prev

on("change:graphic", function(obj, prev) {    
  //Do something with "obj" here. "prev" is a list of previous values.
  // Note that "obj" and "prev" are different TYPES of objects. 
  // to work with obj you need to use obj.get("name");
  // to work with prev you can use prev["name"];
});


change:graphic:(property)

You can also bind to an event for each specific property on the object. So if you have a script that you want to run only when the rotation changes, you would do:

on("change:graphic:rotation", function(obj, prev) {    
  //Always set rotation back to 0, so no one can rotate objects.    
  obj.set("rotation", 0);
});

add:graphic

Triggered whenever a graphic object is added to the tabletop for the first time. Will also be called for existing objects when the tabletop starts up if you bind to this event outside of the ready event.

Callback parameters: obj

on("add:graphic", function(obj) {
  //Will be called for all new graphics, including ones that already existed at the start of the play session.
});

var started = false;

on("ready", function() {
  on("add:graphic", function(obj) {
    //Will only be called for new objects that get added, since existing objects have already been loaded before the ready event fires.
  });
  //You could also set a variable and ignore add events until it is true.
  started = true;
});

destroy:graphic

Triggered whenver a graphic object was removed from the tabletop.

Callback parameters: obj

Other Object Types

There are also events for all the other object types, and sub-types, such as:

change:path, add:path, destroy:path, change:text, add:text, destroy:text, change:token, add:token, destroy:token, change:card, add:card, destroy:card

See the Objects reference for a complete list of all object types and sub-types.