[Script] AuraTriggers

Code : <a href="https://github.com/kjaegers/ScriptCards/blob/main/X_OtherScripts/AuraTriggers.js" rel="nofollow">https://github.com/kjaegers/ScriptCards/blob/main/X_OtherScripts/AuraTriggers.js</a> Docs : <a href="https://github.com/kjaegers/ScriptCards/blob/main/X_OtherScripts/AuraTriggers.md" rel="nofollow">https://github.com/kjaegers/ScriptCards/blob/main/X_OtherScripts/AuraTriggers.md</a> Discord : <a href="https://discord.gg/exT3mDKvbs" rel="nofollow">https://discord.gg/exT3mDKvbs</a> Current Version : 0.8 Aura Triggers allows you to define effects that take place when token enter or exit an active aura on another token. It supports tokens of varying radius correctly, with the aura radius extending around the token regardless of size. The script is not yet on OneClick, so it can be found at the GitHub link above. Triggers are defined as JSON array in the “gmnotes” field on a token. A notes field can contain multiple aura definitions that are keyed to the color of the two auras on the token itself, meaning one color can represent multiple auras and/or changing the color of an aura can activate/deactivate the aura effects. JSON elements are case sensitive, and I HIGHLY suggest running your JSON through an online JSON validator (I use <a href="https://jsonlint.com/" rel="nofollow">https://jsonlint.com/</a> ) to ensure it is properly formatted. Nearly all of the elements are optional and contain defaults if they are not set. Supported JSON elements to define an aura and its effects are: name (string): Display/logical name for the aura effect. color (string): Must exactly match the aura color on token, with the # sign (aura1_color or aura2_color). icon (string): Roll20 status marker key to apply while in aura. toPCs (boolean, default true): Apply to player-controlled character tokens. toNPCs (boolean, default true): Apply to non-player-controlled character tokens. toGraphics (boolean, default false): Apply to non-character graphics. toLayers (string, default objects): Restrict affected targets to specific Roll20 layers. &nbsp;Example: "objects,gmlayer". Supported layer values: objects (alias token), gmlayer, map, walls, foreground. ignoreWalls &nbsp;(boolean, default false): if using Path Math to let walls block auras, setting this to true prevents this aura from being impacted by walls. applySelf (boolean, default false): Apply the aura effect to the aura source token itself. removeOnExit (boolean, default true): Remove status marker when token exits aura. chatActionOnEnter (string, default ""): Sent once when token enters an aura. chatActionWhileInside (string, default ""): Sent on movement checks while token remains inside an aura. chatActionOnExit (string, default ""): Sent once when token exits an aura. chatActionOnStartTurn &nbsp;(string, default `""`): Sent when token starts its turn while inside an aura. chatActionOnEndTurn (string, default `""`): Sent when token ends its turn while inside an aura. sourceVfxOnEnter (string, optional): VFX played at aura source token on enter event. targetVfxOnEnter (string, optional): VFX played at affected token on enter event. sourceVfxOnExit (string, optional): VFX played at aura source token on exit event. targetVfxOnExit (string, optional): VFX played at affected token on exit event. sourceVfxWhileInside (string, optional): VFX played at aura source token while affected token remains inside. targetVfxWhileInside (string, optional): VFX played at affected token while it remains inside an aura. sourceVfxOnStartTurn (string, optional): VFX played at aura source token when affected token starts turn in aura. targetVfxOnStartTurn (string, optional): VFX played at affected token when it starts turn in aura. sourceVfxOnEndTurn (string, optional): VFX played at aura source token when affected token ends turn in aura. targetVfxOnEndTurn (string, optional): VFX played at affected token when it ends turn in aura. soundOnEnter (string, optional): Jukebox track title to play on enter event. soundOnExit (string, optional): Jukebox track title to play on exit event. soundWhileInside &nbsp;(string, optional): Jukebox track title to play while token remains inside an aura. soundOnStartTurn &nbsp;(string, optional): Jukebox track title to play when token starts turn in aura. soundOnEndTurn &nbsp;(string, optional): Jukebox track title to play when token ends turn in aura. attributeFilter (string, optional): Additional character-attribute condition(s) required for the aura to apply. Note that Aura visibility (if players can see auras or not) is not checked, so GMs can have auras you can see while players cannot. The OnEnter and OnExit (and the chatActionWhileInside ) entries allow for commands that are sent to chat when the indicated event happens. These are run once for a token entering or exiting the aura or every time it moves but stays inside the aura for chatActionWhileInside) . The actions taken can be simple emotes or chat messages, API calls, or anything else you can send to chat, including ScriptCards code if you have ScriptCards installed. Examples: [ { "name": "Blessing Field", "color": "#00ff00", "icon": "angel-outfit", "toLayers": ["map", "objects"] } ] &nbsp; This simple aura definition triggers if either Aura1_Color or Aura2_Color matches #00ff00 (Green). Any token passing into the aura that is a PC or NPC (meaning that the graphics object has a “represents” (for NPCs) or the represented character has a “controlledby” filled in for PCs), will receive the “angel-outfit” status marker. When the token exits the aura (or the aura is deactivated, or the aura token is moved/removed/etc.) the status marker will be removed. Here is a MUCH more complex example courtesy of Si on the ScriptCards discord channel: [ { "color": "#9900ff00", "name": "Paladin Aura", "icon": "angel-outfit", "toNPCs": false, "toPCs": true, "toGraphics": false, "removeOnExit": true, "toLayers": "objects,gmlayer", "chatActionOnEnter": "!script {{ +++5Elib;snlib+++ --#targettoken|[TID] --#sourcetoken|[ATID] --&amp;CharID|[*T:character_id] --&amp;PalID|[*S:character_id] --&gt;Lib5E_FIND_CLASS_LEVEL|[&amp;PalID];paladin;PLevel --?[&amp;PLevel] -le 9|&amp;Courage;.|&amp;Courage; and the Aura of Courage makes you immune to the Frightened Condition --#emoteText|[TNAME] enters the protection of Paladin [ATNAME] --#hideTitleCard|1 --vtoken|[TID] shield-holy --&gt;Lib5E_SET_GLOBAL_MOD_STATUS|[&amp;CharID]; save; Paladin Aura; 1 --!a:[&amp;CharID]|global_save_mod_flag:1 --&gt;Lib5E_GET_GLOBAL_MOD_STATUS|[&amp;CharID]; save; [ANAME];Aura --?[&amp;Aura] -eq 0|&gt;Create|&gt;Exists --X| --:Exists| --Rfind|[&amp;CharID];Paladin Aura;repeating_savemod;global_save_name --!a:[&amp;CharID]|[*R&gt;global_save_roll]:[*S:charisma_mod] --+|[c]Your saving throws will now receive an additional +[*S:charisma_mod] bonus[&amp;Courage][/c] --&gt;Lib5E_FIND_ACTIVE_GLOBAL_SAVE_MODS|[&amp;CharID];Mods --+Global Save Modifiers|[&amp;Mods] --&gt;End| --X| --:Create| --!or:[&amp;CharID]:savemod|global_save_name:Paladin Aura|global_save_active_flag:1|global_save_roll:[*S:charisma_mod] --+|[c]Your saving throws will now receive an additional +[*S:charisma_mod] bonus[&amp;Courage][/c] --&gt;Lib5E_FIND_ACTIVE_GLOBAL_SAVE_MODS|[&amp;CharID];Mods --+Global Save Modifiers|[&amp;Mods] Paladin Level --:End| --X|}}", "chatActionWhileInside": "!script {{ +++5Elib;snlib+++ --#targettoken|[TID] --#sourcetoken|[ATID] --#emoteText|[TNAME] remains protected by Paladin [ATNAME] --#hideTitleCard|1}}", "chatActionOnExit": "!script {{ +++5Elib;snlib+++ --#targettoken|[TID] --#sourcetoken|[ATID] --&amp;CharID|[*T:character_id] --#emoteText|[TNAME] leaves the protection of Paladin [ATNAME] --#hideTitleCard|1 --vtoken|[TID] shield-death --&gt;Lib5E_SET_GLOBAL_MOD_STATUS|[&amp;CharID]; save; Paladin Aura; 0}}" } ] This D&amp;D 5E sample runs actual ScriptCards scripts (that use the 5ELib and snlib libraries) on the enter/exit events and turns on/off Global Save Modifiers for a paladin’s saving throw aura. It will even create the GSM on the target character if it doesn’t already exist. Note that in this case, the color is set to #9900ff00 and since the extra “00” is appended as the alpha channel, it means the color is fully transparent, this aura won’t show visibly but the effect will still take place. You set this color through the normal Roll20 token interface. Aura Triggers just reads the color to determine if an aura should be active. Aura Triggers registers with both Token Mod and ScriptCards to listen for events if they are present (so moving a token/changing aura colors, etc. from a !token-mod or !script will be watched by Aura Triggers). I’ve created a channel on my Discord server for discussion and support of Aura Triggers. It can be found here: <a href="https://discord.gg/exT3mDKvbs" rel="nofollow">https://discord.gg/exT3mDKvbs</a> There are a couple of additional features planned (most notably triggers for "Ends turn in Aura" and "Begins Turn in Aura" since these are frequent triggers for some effects. As always, I'm open to suggestions.

Here is a visual using a simple trigger to apply a status marker. It was too big to upload to Roll20 so I put it on my Github: <a href="https://github.com/kjaegers/ScriptCards/blob/main/wiki_images/AuraTriggers.gif" rel="nofollow">https://github.com/kjaegers/ScriptCards/blob/main/wiki_images/AuraTriggers.gif</a>

One more quick example: [ { "color": "#9900ff", "name": "Prayer", "icon": "angel-outfit", "toNPCs": false, "toPCs": true, "toGraphics": false, "removeOnExit": true, "toLayers": "objects,gmlayer", "chatActionOnEnter": "[TNAME] feels protected!", "chatActionOnExit": "The protection around [TNAME] fades." }, { "color": "#9900ff", "name": "Prayer", "icon": "angel-outfit", "toNPCs": true, "toPCs": false, "toGraphics": false, "removeOnExit": true, "toLayers": "objects,gmlayer", "chatActionOnEnter": "[TNAME] is cowed by holy power!", "chatActionOnExit": "[TNAME] shrugs off the radiant opression." } ] This setup demonstrates two different effects with the same aura. PC get the first effect and "feel protected", while NPCs get the second effect and are "cowed by holy power". Both auras have the same color trigger, so both are active at the same time.

This looks fantastic. Just curious if dynamic lighting will block the effects. If the Paladin is on one side of the wall their protection radius would not cover those on the other side of it.&nbsp;

Ed W. said: This looks fantastic. Just curious if dynamic lighting will block the effects. If the Paladin is on one side of the wall their protection radius would not cover those on the other side of it.&nbsp; At this time, no, walls do not impact the auras. That is something I'd like to do, but will be fantastically complicated to implement.

Ed W. said: This looks fantastic. Just curious if dynamic lighting will block the effects. If the Paladin is on one side of the wall their protection radius would not cover those on the other side of it.&nbsp; Hiya, just wanted to clarify for any tables that play 2014, the Aura is not defined as an AoE (which would be affected by cover if no lines can be traced to target area), so RAW, the code above gives an accurate representation. Ofc every table can apply rules as they see fit,&nbsp; " Aura of Protection Starting at 6th level, whenever you or a friendly creature within 10 feet of you must make a saving throw, the creature gains a bonus to the saving throw equal to your Charisma modifier (with a minimum bonus of +1). You must be conscious to grant this bonus. At 18th level, the range of this aura increases to 30 feet. Aura of Courage Starting at 10th level, you and friendly creatures within 10 feet of you can’t be frightened while you are conscious. At 18th level, the range of this aura increases to 30 feet." 2024 rules make the Aura an Emanation and Emanations follow rules for AoE, so would be blocked "If all straight lines extending from the point of origin to a location in the area of effect are blocked, that location isn’t included in the area of effect. To block a line, an obstruction must provide Total Cover. See also “Cover.” "

Simon, that's an interesting distinction. I DID start implementing this, and I don't think it is going to be TOO hard except when the path objects are of the ellipse type. I'll have to dig into the math for that :)

There are also tables who play with radius = square. To avoid "I move 20 feet diagonally to avoid the impending fireball" interpretation.

Hey Simon. Totally get the raw rules, I just apply it in kind of the same way the fireball works with it wrapping around corners. Such as if you are in an open cavern but your line of sight from the paladin is blocked, say by a boulder, their aura would still reach you as it would wrap around the boulder. But if you are in one room and paladin is in another and the doors are shut the aura doesn't reach them.

I like a case by case approach - Wulf, Scourge of the Northern Wastes is on their knees, gasping as the gas trap fills the room, the DM calls for a Con save, Lady Eleanor steps up to the now locked door, places her hand against the wood and calls to The Morning Lord to spare her companion... roll : )

Aura Triggers version 0.8 is up on the GitHub: V 0.8: Properly handles an icon not being specified in an aura. Previously an aura without and icon was being ignored. Added support for walls blocking auras using Path Math and "pathv2" lighting objects. NOTE: Only Jumpgate Pathv2 walls are supported at this time. The older "Legacy" wall format is not. To use wall blocking, you will need Path Math and the associated dependencies installed from the API console. Added "ignoreWalls" option to aura definitions to allow certain auras to bypass wall blocking even if Path Math is enabled. Minor code cleanup and bug fixes. And V0.7 had these changes, but I don't think I posted it: Added chatActonOnStartTurn and chatActionOnEndTurn triggers for effects that trigger based on these events. Added corresponding VFX and sound effect support for start turn/end turn events as well as while inside events. &nbsp;