A module that allows users to embed macros directly into effects. These macros are then called automatically when the appropriate trigger happens. The options are:
- When an effect is created.
- When an effect is deleted.
- When an effect is toggled (on, off, or both).
- When the actor who has the effect starts their turn.
- When the actor who has the effect ends their turn.
- At the start of any combatant's turn.
- When the actor who has the effect is marked defeated in combat.
- At the start of a combat round.
- At the end of a combat round.
- When combat is started.
- When combat is ended.
An effect can have a macro of any of these types, not just one. There is also the static 'never' type meant for being explicitly called by other scripts. This type is never called automatically.
How to
Macros are added in the ActiveEffect config. Selecting the type of trigger and clicking 'Add Macro' (or 'Edit Macro' for an existing macro) opens a macro editor. When an embedded macro is triggered, it is executed for the owner of the actor who has the effect. If no such owner, then it is executed as if by the GM.
The module will automatically iterate over all effects that currently affect the actor.
Script Helpers
By default, these variables are pre-defined in any effect macro.
effect: The effect itself.actor: The actor who owns the effect (even if the effect is on an item). If no actor, thennull.character: The user's assigned actor. If no assigned actor, thennull.token: If the actor is synthetic (unlinked), thentokenis the is the token placeable on the actor's scene, otherwise the first token found on the currently viewed scene belonging toactor. If none found, thennull.scene: The scene on whichtokenis embedded. If there is no token, then the currently active scene is used. If no scene, thennull.origin: The document thatActiveEffect#originpoints to. If no such thing, thennull.speaker: The 'speaker' object normally used in chat messages, speaking as theactorif they exist.item: If the effect is on an item and not an actor, this is that, otherwisenull.
Added functions
A set of async functions have been added to active effects.
ActiveEffect#callMacro(type, context={})calls a macro embedded in the effect of the specific type. Thecontextobject can be used to pass additional parameters to the script, and can be referenced withthis.ActiveEffect#hasMacro(type)returns true or false whether or not an effect has a macro of the given type.ActiveEffect#removeMacro(type)removes a macro of the given type from the effect.ActiveEffect#createMacro(type, script)creates an embedded macro of the given type inside the effect. Identical to using the provided interface and writing a macro there. The provided script can be a function or a string.ActiveEffect#updateMacro(type, script)updates a macro of the given type on an effect. In most cases functionally identical tocreateMacro, and will remove the embedded macro if no script is provided. The provided script can be a function or a string.
System Specific Triggers
The module works in every system that has Active Effect support, however it can leverage system-specific hooks as well, if added. These are the system-specific hooks added so far:
dnd5e. When you make an attack roll (dnd5e.rollAttack), when you roll damage (dnd5e.rollDamage), when you make a saving throw/death saving throw (dnd5e.rollAbilitySaveanddnd5e.rollDeathSave), and when you make an ability check, skill check, tool check (dnd5e.rollAbilityTest,dnd5e.rollSkill,dnd5e.rollToolCheck), or when you take a rest (dnd5e.shortRest,dnd5e.longRest). The arguments passed to the system hooks are passed to the macro as well and can be accessed withthis.