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.

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 paramters 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});
• obj.previous("property") gets the previous value for the property. This can be used in event callbacks to determine "how much" a property has changed.

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.

Callback paramters: obj

on("change:graphic", function(obj) {    
  //Do something with "obj" here
});

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) {    
  //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

===Chat Events and Functions===

'''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
}