Events

An event is part of the CAT framework that determines when a macro will run. Events have passes that further define when a macro will be called. Events are categorized by things that happen in foundry, such as moving a token or rolling an item. All CAT events have different passes and scope data.

Aura

Passes: Auras have one pass, other macro configuration data lets the API determine when to call the macro.
Trigger Data: Standard data is included. Note: targetToken is the token document providing the aura, token is the token document receiving the aura.
Return Data: An Aura update macro is expected to return Effect Data or undefined. Effect Data will be used to create an effect on the target token. Your macro can include its own logic to determine if the aura should not apply an effect by returning undefined instead.
Macro Configuration: Data must include distance (hardcoded Number) or configDistance (configuration key)
Example: Aura of Protection

Called

Passes: Called macros (callee) are only ever executed by other macros (caller). These are basically custom events for specific automations. The pass determines how broad the caller macro will check for the callee macro. actorCalled will look for macros from the actor, sceneCalled will look for macros from all actors on the scene, etc.
Trigger Data: Standard data is included. Arbitrary additional data may be provided by the caller macro.
Return Data: Caller macro may expect returned data.
Macro Configuration: Data must include passIdentifier for the pseudo-event that will be called.
Example: Sneak Attack with Cunning Strike

Check

Passes: Check is called when an ability check is made. actor, scene, nearby etc. is how broad a macro will look for actors to apply to.

• Situational is called before a roll is made.
• Context is called before the roll is made and after situational.
• Bonus is called after the roll is made but before the result.
• Post is called after result is determined.
  

Trigger Data: Standard data is included. All passes include raw hook data such as config, dialog, message, options, checkId. Bonus and Post also contain the roll.
Return Data: Context expects specifically formatted return data to generate a dialog for contextual advantage/disadvantage when it cannot be determined programmatically ({type: 'advantage' | 'disadvantage', label: string}). All other passes do not take return data, modify the options directly.
Macro Configuration: No specific requirements.
Example: actorContext - Keen Senses

Combat

Passes: Determines when in combat a macro is called. actor, scene, nearby etc. is how broad a macro will look for actors to apply to.
Trigger Data: Standard data is included. All passes include raw hook data and context specific data such as combat, combatant, previousCombatant, context (hook data), round, turn, previousRound, previousTurn.
Return Data: Passes do not take return data, modify documents directly.
Macro Configuration: No specific requirements.
Example: actorTurnEnd - Rage

Effect

Passes: Called when effects are created/deleted/updated. DoCreated and DoDeleted allow you to block creation/deletion. Pre passes are called synchronously. actor, scene, nearby etc. is how broad a macro will look for effects to apply to.
Trigger Data: Standard data is included. Some passes include raw hook data such as options, updates.
Return Data: DoCreate and DoDelete will cancel the creation/deletion of an effect when the return value is truthy. All other passes do not take return data, updates can be modified directly where available.
Macro Configuration: No specific requirements.
Example: actorDoCreate - I Survived to Tell the Tale

Item

Passes: Called when items are created, modified, or change state on an actor. actor, scene, nearby etc. is how broad a macro will look for items to apply to.

• created, deleted, updated, equipped, unequipped, attuned, unattuned are called when such actions happen to an item.
• bulkUpdated is called when the actor medkit is used.
• munched is called when an actor is imported or updated via D&D Beyond.
• medkit is called when an item is medkited.
  

Trigger Data: Standard data is included. Most passes include raw hook data such as options, and modification passes (like updated, equipped, attuned) include the specific updates object. The munched pass includes ddbCharacter data.
Return Data: Passes do not take return data. Modify the item or actor documents directly.
Macro Configuration: No specific requirements. Example: actorEquipped - Dwarven Thrower

Move

Passes: Called when a token moves across the canvas, including forced movement and teleportation. actor, scene, nearby etc. determines how broad a macro will look for actors to apply to.

• moved is called after a token completes its final standard movement.
• movedNear is called when a token's movement brings it within proximity of another actor.
• aimTeleport is called before crosshairs are aimed, modify range and animation to change range or animation.
• preTeleport and postTeleport

displace is called when a token is moved by a macro to an arbitrary point.

slide is called when a token is moved by a macro in a line.

Trigger Data: Standard data is included. Passes include the token and raw hook data such as options. (Teleport and displace passes typically include destination coordinates or movement vectors).

Return Data: preTeleport and displace can be returned truthy to cancel movement. slide can be returned a Number that will add/reduce from the movement, 0 will cancel the movement.

Macro Configuration: No specific requirements.