Roll20 Draw Circle of Fixed Radius

Concept

SmartAoE. Accept you ever overlayed a cone, line, or circle template on a map and wondered if that square that is simply barely covered should count equally "in"? Sure, at that place are pre-made grid templates out in that location, simply you are normally limited to 90/45deg orientations. The thought backside this script is to provide flexibility in casting angles (to align just the right spot earlier triggering) and a means for consistent ruling of these cases. Also, the script tin can detect creatures within affected squares and be able to roll saving throws and/or employ damage and condition markers automatically (ala GroupCheck or similar script).

• SmartAoE forum thread

Figure description. Example of 4 active AoE's: 90deg cone (fixed radius, snapped to intersection), 5e-style cone (variable radius), line, and circle (using bladder keyword and custom multi-sided controlToken). The circle AoE is triggered (5e SRD Water ice Storm spell), making saving throws for tokens in surface area, automatically deducting impairment (--autoApply|truthful), and outputting results to chat.

SmartAoE Nick Olivo (December. 2021)

Contents

• 1 Concept
• two How does it work?
• 3 Initial Setup/Install
• 4 Acknowledgements
• 5 Listing of Subcommands
  • 5.ane AoE Behavior Commands
  • v.2 AoE Math and/or Trigger Behavior Commands
  • 5.3 Chat Output Manner Commands
• vi Chat Output Cheat Sheet
• 7 Quirks, Recommendations, Known Issues and/or TBD
  • vii.1 Using custom images for title background
• 8 Example SmartAoE Macros
  • 8.i Simple 20ft cube
  • 8.ii Simple variable cube
  • 8.3 Simple 5e fixed-radius cone with origin rotation
  • 8.4 True radius 15ft cone approximation
  • 8.v Pathfinder 20ft circle
  • 8.6 Called-for Hands (5e)
  • 8.seven Faerie Burn (5e)
  • 8.8 Ice Storm (5e)
  • viii.ix Spirit Guardians (5e)
  • viii.x Aura of Vitality (5e Healing)
  • 8.11 Wall of Burn (5e)
  • eight.12 Custom Ruleset Case, 180deg cone
• nine [For script writers] Registering your token change events to SmartAoE

How does it work?

Current functionality is to spawn a "control token" over a selected token. The location of the AoE is ready past the positioning of the control token (and for lines/cones, the relative positions of the selected and control tokens). Depending on the commands used to spawn that control token, the script will associate those settings with that control token and deed appropriately (a link betwixt the selected and control tokens is fabricated and stored in persistent memory). To determine whether a foursquare is affected, you define a minimum grid coverage surface area in your macro. I'll use cones in the following word: For case, using --minGridArea|0.25 would require 25% of the grid foursquare to be covered by the cone boundaries. You can choose to have the origin of the cone be in the default center of the origin (selected) token, or use the --origin|nearest or --origin|nearest, face command to automatically shift the origin bespeak to the nearest corner or face up of the origin token. There are additional commands to rotate the cone origin bespeak CW/CCW and to "trigger" the effect.

You tin can besides define rules for the minimum percentage of a token's expanse that needs to be covered by an affected AoE grid square in order for the creature to be considered "in" the area of result.

At that place are a variety of customization options for the AoE, including blazon (line, circle, cone, foursquare - of which circle and square tin be made independent of source token position), radius, AoE fill and line colors, saving throw formulas, difficulty class (target save number), up to two harm formulas & damage types, condition markers for laissez passer/fail/dead, bar links, damage resistance/vulnerability/immunity (based on attribute content and damage type), auto application of impairment, and auto-deletion of the AOE controlToken and/or "dead" tokens. These parameters and more are described below under #Listing of Subcommands.

If the AoE definition includes whatsoever rolls (for damage or saving throws), there volition be customizable chat output with the results.

• What about hidden tokens? Results for Tokens on the GM layer will exist whispered to the GM in a separate table
• What if I want to hibernate the names of tokens to avert? There is an pick --hideNames|1 to keep your chat spoiler-free :)

Initial Setup/Install

1. Install the SmartAoE api script, currently available for one-click install or found on GitHub here: v0.25
2. Install the API script (available equally 1-click install). SmartAoe is dependent on this utility script!
3. Note: the following 2 steps are at present automatically performed for you (if the "AoEControlToken" character does non be during install) if using version 0.21 or later!
   1. Create a graphic symbol sheet with the default token image y'all want for the AoE command token. If yous do not specify a --controlTokName, then the script will wait for the default token for a character named AoEControlToken. Yous can use a Multi-Sided Token if you'd like, for which you may set the side and size via commands when spawned.
   2. Give the default token sight. A while ago, Roll20 decided to requite sighted tokens z-order priority over sightless tokens. If the control token does non have sight, it may appear nether the caster token, requiring moving the caster token out of the way to admission it. Giving the control token sight will eliminate this possibility.
4. Create macro(s) utilizing the syntax described below. There are currently six different base of operations commands, though the first and third volition be the virtually common:

Syntax	Description
!smartaoe <subcommands>	this is the primary api syntax. Descriptions of the subcommands are found here (#Listing of Subcommands), but they all follow the course --commandName|parameter(s)
!smartrotateorigin <cw/ccw>	valid for cones merely - this rotates the origin signal cw or ccw along corners or faces of the origin token
!smarttrigger	Triggers the fx and does all the stuffs. Currently no subcommands for users (though the script itself may telephone call this command with params via a !smartquery below).
!smartquery <optional token_id>	This checks a selected token (if no token_id parameter supplied) or a targeted token (requires a token_id parameter) for overlapping AoEs and triggers any/all AoE's that are active in the target token's square merely. Useful for effects that occur at the showtime or finish of a animal'southward plow (e.k. 5e Stinking Cloud or Flaming Sphere)
!smartremove	currently no subcommands. All of the AoE'due south (and associated controlTokens) linked to the selected token will exist removed. This is primarily used for AoE's with fixed radius emanating from a pulley. Encounter the subcommand --controlTokName|self in the #List of Subcommands below for more details
!smartclearcache	currently no subcommands. All of the AoE links in the Campaign will exist removed. This will not delete any AoE tokens or paths (drawings), which volition need to be deleted manually. Only use this command if y'all suspect that the SmartAoE State object has been corrupted somehow.

Power Proper name	Ability Content	Description
CCW	!smartrotateorigin ccw	rotates a cone origin bespeak counter-clockwise
CW	!smartrotateorigin cw	rotates a cone origin signal clockwise
Trigger	!smarttrigger	triggers the AoE effects in every affected grid foursquare

Ability Name	Ability Content	Description
aTrigger-ALL	!smarttrigger	triggers the AoE effects in every affected grid square
aTrigger-Target	!smartquery @{target|Choose a Target|token_id}	prompts for a target token and triggers the AoE effects only on that token
aRemove	!smartremove	removes all AoE tokens and grid shading linked to the selected caster token

Acknowledgements

• Folks I've shamelessly stolen and/or modified code from:
  • TheAaron (numerous sources)
  • Kurt J. (chat styling, Bresenham line algorithm Scriptcards)
  • Jakob(GroupCheck)
  • keithcurtis(ping-pull and api triggers from from chat icons Reporter^(Forum))
• All-around great guy whose encephalon I've picked too many times to count: timmaugh
• My home game players and my Patreon supporters for beta testing and feedback, with special thanks to FR and Michael C

Support me on Patreon

I've been asked past a few folks if they can provide support in appreciation for a script or other help. *If you notice yourself falling into that group, too, and then thanks! If not, no worries - it's not why I do this.* I just want everyone to accept as much fun as possible playing the games that they dearest!
Disclaimer: Patreon campaigns are not affiliated with Roll20. Contributions are entirely voluntary and Roll20 cannot provide support or refunds for contributions.

List of Subcommands

AoE Beliefs Commands

Command	Parameter(s)	Clarification	Default Value	Example(s)	Additional Notes
--radius	<###><optional units like ft. or "u">	If a numeric value is specified, the AoE volition have a constant radius regardless of the distance between the origin and control tokens. If "variable" (or omitted), the radius is dynamically adamant by the relative spacing of the 2 tokens	variable	--radius|60ft --radius|12u	If no units are given, will default to pixels! Behavior depends on "aoeType" keyword and "origin" type: For "nearest" origin, if "float" keyword is omitted, the origin token's square is omitted from the radius (making it bigger). Otherwise, float will result in a truthful radius.
--aoetype	<type>,<optional coneAngle> or <optional "bladder">	currently supports "line", "square", "circumvolve", "PFcircle", "wall", "cone", "PFcone", and "5econe"	line	--aoetype|5econe --aoetype|cone, 90 --aoetype|circumvolve, float --aoetype|line --aoetype|PFcone	--The "bladder" keyword "untethers" the AoE from the sourceToken, creating the AoE around the controlToken only (eastward.g. a Fireball spell) --"5econe" will create a triangular shape whose max width equals its length, whereas a "cone" volition use a true radius and coneAngle --The "PFxxxx" types volition perform an boosted filtering on affected grids using the "every other diagonal counts as 2squares" rule. NOTE: default is "line" if this subcommand is omitted.
--width	<###><optional units like ft. or "u">	the width of a wall-type AoE in Pixels or units	1u	--width|3u --width|10ft	simply used for "wall" AoE's
--instant	<true/aye/1/simulated/no/0>	If set to true, the selected AoE token will exist deleted immediately afterward triggering	False	--instant|1	Note: default is false if this subcommand is omitted
--origin	<style> <optional "face up">	AoE starts in center or edge of square (ignored for line AoE's)	center	--origin|nearest --origin|nearest, face --origin|center	"Heart" (or omitted) volition option the centre of the origin token for the AoE origin. "Nearest" will pick the closest corner. "Nearest, face up" will include the flat sides of the token'south square as potential origin points.
--forceIntersection	<true/yep/1/false/no/0>	forces the dragged controlToken eye to the intersection of grid squares	false	--forceIntersection|0	I'd recommend setting to true for PF-style cone approximations. Otherwise, if set to false (or omitted), you can always press Alt while positioning the controlToken for fine tuning of the AoE placement. NOTE: If this command is omitted, the default beliefs is to automatically set to true if a "float" way circle or square AoE is used, unless the total AoE size is 1 square or less (equally you lot typically want a 5ft square to exist centered in the square). You can always override this default beliefs using the command explicitly withal.
--mingridarea	<#>	what percentage of the grid foursquare's area must lie within the AoE to be included in the last affected expanse	0.01	--mingridarea|0.1	The case to the left would crave just 10% of the filigree to be covered by the AoE to be included. For 5e cones, I'd recommend a practiced place to beginning would exist 25%. For PF cone approximations, I'd go with 50% along with --forceIntersection|1. More than 50% might start making cones not "emanate" fully from the source token
--mintokarea	<#>	what percentage of the token's area must lie within the AoE to be included equally an affected creature	0.01	--mintokarea|0.25	The case to the left would require but 25% of the token'due south expanse to be covered by afflicted squares for them to be in the area of event.
--fx	<style>-<type>	will spawn fx in affected squares when triggered	---	--fx|burn down-decease --fx|glow-holy	fx will spawn at each affected square
--aoecolor	<#RRGGBBTT>	determines the fill color of the AoE's afflicted squares	#ff000050	--aoeColor|#ff000050	NOTE: default is #ff000050 if this subcommand is omitted
--aoeOutlineColor	<#RRGGBB>	determines the line color of the AoE outline	#ff0000	--aoeColor|#ff000050	Note: default is #ff0000 if this subcommand is omitted
--gridcolor	<#RRGGBBTT>	determines the stroke(line) color of the AoE's afflicted squares	#000000	--gridColor|#ff994450	To accept no grid lines, fix transparency to max by adding "00" to digits 7&viii NOTE: default is #000000 if this subcommand is omitted
--controlTokName	<charName> or "cocky"	The name of the graphic symbol sail whose token volition be used as the AoE control token. If a graphic symbol name is provided, the default token will be spawned for subsequently positioning. If "self" is used, the AoE will immediately aggrandize around and move with the selected token	AoEControlToken	--controlTokName|Fireball --controlTokName|cocky	It is mostly best if the default token image is a png file with partial transparency to allow the afflicted grid squares and tokens to be visible. Rollable tabular array tokens are supported. NOTE: "self" can simply be used for square/circle aoeTypes with the float keyword and with pre-defined radius Note: if "self" is used, then --controlTokSize and --controlTokSide volition exist ignored. NOTE: if "cocky" is used, it is recommended to set up --forceIntersection|0 to forestall the default beliefs of centering float AoE'south at grid intersections Notation: default is "AoEControlToken" if this subcommand is omitted.
--controlTokSize	<#>	The size (in squares) of the command token	1	--controlTokSize|8	Note: default is one if this subcommand is omitted
--controlTokSide	<#>	For rollable table tokens: the side of the control token's epitome to be gear up when created	1	--controlTokSide|6	Note: default is 1 if this subcommand is omitted
--isDrawing	<true/yes/i/false/no/0>	Sets the isdrawing property of the spawned control token	Imitation	--isDrawing|truthful	Note: default is false if this subcommand is omitted
--ignore	<attrName, attrValue>	Characters with matching attribute values will not be included in the chat output	---	--ignore|SmartAoE_Ignore, 1	NOTE: must have both the attrName and attrValue separated past a comma
--selectedID	<token_id or character_id>	allows directly option of the source token	---	--selectedid|-MlBqIRAtRSwAZ-8Jr_E
--playerID	<player_id>	The proper name of the calling histrion. Useful when calling from another API script. Tells the script which playerID tin control the control token (if not ready by default in character canvass). Besides for error msg whispers when chosen by some other script.	---	--playerid|-MlBqIRAtRSwAZ-8Jr_E

AoE Math and/or Trigger Behavior Commands

Command	Parameter(south)	Description	Default Value	Example(s)	Additional Notes
--dc	<value or inline roll>	the target roll for each saving throw (>= is passing, < is declining)	0	--dc|{selected|spell_save_dc} --dc|[[5d6+2]]
--saveformula	<inline scroll with special syntax (see notes)>	Formula to be used for saving throws for all afflicted tokens.	---	--saveFormula|<<1d20 + a{dexterity_save_bonus}>> --saveFormula|5eDEX	In order to delay the save rolls until the AOE is triggered, and to employ that formula to each token individually, supercede inline roll format in the following fashion: "[[…]]" is replaced by "<<…>>" "@{…}" is replaced by "a{…}" Note: for 5e games, you tin use the autograph "5eSTR", "5eDEX", "5eCON", "5eINT", "5eWIS","5eCHA"
--damageformula1	<inline roll>	Formula to be used for damage1	---	--damageformula1|[[8d6]] --damageformula1|[[(5+?{Cast at what level? |3,3|four,4|5,5|half dozen,6|7,7|8,eight|9,nine})d6]] --damageFormula1|[[-1*2d6]]	Negative damage will be interpreted by the script as healing!
--damagesaverule	<expression>	The math functioning (accepts single Operator and Operand) to be applied if the saving throw succeeds	*0.v	--damagesaverule|*0 --damagesaverule|-10	Note: default is "*0.5" if this subcommand is omitted
--damagetype1	<text>	the impairment type for damage1	---	--damageType1|Burn
--damageformula2	<inline scroll>	Formula to be used for damage2	---	--damageformula1|[[8d6]] --damageformula1|[[(5+?{Cast at what level? |iii,3|four,four|5,v|6,6|seven,7|8,8|nine,9})d6]]
--damagetype2	<text>	the damage type for damage2	---	--damageType1|Fire
--bar	<#, optional #, optional #>	which token bubble(south) to apply harm. Default = 1	ane	--bar|1 --bar|3,1 --bar|3,1,2	If multiple bar values are defined: *For damage, once the first bar value is reduced to 0, whatsoever excess damage will be applied to the subsequent bar number until all damage is accounted for or all denoted bar values are 0. *For healing (negative harm), bars will fill up until the max value is reached, then backlog will be applied to the next bar value, etc. If the bar value has no max, there will be no limit to the amount of "healing" done.
--autoapply	<truthful/aye/1/fake/no/0>	Toggle to utilise impairment and condition markers automatically or after subsequent interaction with chat output.	False	--autoApply|ane	Confirmation of the applied impairment will be posted to chat. Tokens on GM layer will have whispered confirmation. NOTE: default is false if this subcommand is omitted.
--conditionfail	<name(s) of status markers to apply on a failed save>	comma delimited	---	--conditionFail|blood-red --conditionFail|red@3 --conditionFail|skull,cobweb	Note: if custom markers are used, you must include the whole id, e.g. "proper name::####" Notation:inserting @# will overlay a number over the condition marker
--conditionpass	<proper noun(s) of status markers to apply on a successful save>	comma delimited	---	--conditionPass|Target::1510119 --conditionPass|green@three --conditionPass|aura,commodities-shield	Note: if custom markers are used, y'all must include the whole id, e.g. "proper noun::####"
--zerohpmarker	<proper noun(south) of status markers to apply if designated token bar is 0 after damage is practical>	comma delimited	---	--zerohpmarker|dead	Annotation: if custom markers are used, you must include the whole id, east.g. proper name::####
--removeAtZero	<true/yes/i/faux/no/0>	if the key bar value is 0 or less after trigger, that token will exist deleted from the map	FALSE	--removeAtZero|truthful	Annotation: default is false if this subcommand is omitted. WARNING: be conscientious with this, considering if your player tokens are not ignored past the AoE (using the --ignore command), their tokens volition exist deleted!
--resistAttr	<attrName>	If the damageType(due south) string is included in the current value of the denoted attribute, then the --resistanceRule will exist applied	npc_resistances	--resistAttr|npc_resistances --resistAttr|npc_resistances, npcd_resistances	If multiple attribute names are supplied, the script will bank check both NOTE: default is npc_resistances if this subcommand is omitted
--vulnerableAttr	<attrName>	If the damageType(south) string is included in the current value of the denoted attribute, and so the --vulnerableRule will be applied	npc_vulnerabilities	--vulnerableAttr|npc_vulnerabilities --vulnerableAttr|npc_vulnerabilities, someOtherAttributeName	If multiple attribute names are supplied, the script volition check both Note: default is npc_vulnerabilities if this subcommand is omitted
--immunityAttr	<attrName>	If the damageType(southward) string is included in the current value of the denoted attribute, then the --immunityRule will exist applied	npc_immunities	--immunityAttr|npc_immunities --immunityAttr|npc_immunities, someOtherAttributeName	If multiple attribute names are supplied, the script volition bank check both NOTE: default is npc_immunities if this subcommand is omitted
--resistanceRule	<expression>	The math functioning (accepts single Operator and Operand) to exist practical if target is resistant to damageType(south)	*0.5	--resistanceRule|*0.five --resistanceRule|/2 --resistanceRule|-x	Annotation: default is "*0.5" if this subcommand is omitted
--vulnerableRule	<expression>	The math operation (accepts unmarried Operator and Operand) to be applied if target is vulnerable to damageType(southward)	*2	--vulnerableRule|*ii --vulnerableRule|+ten	Annotation: default is "*2" if this subcommand is omitted
--immunityRule	<expression>	The math operation (accepts unmarried Operator and Operand) to be practical if target is immune to damageType(s)	*0	--immunityRule|*0	Notation: default is *0 if this subcommand is omitted

Chat Output Fashion Commands

Command	Parameter(south)	Description	Default Value	Case(s)	Additional Notes
--championship	<text>	the title of the chat output table	SmartAoE	--title|Burning Hands	Note: all chat output options will revert to default values if omitted from the macro
--leftsub	<text>	subtitle of the chat output table. If rightsub is included, they volition be separated by a diamond icon	---	--leftsub|some text --leftsub|Slot level ?{Cast at what level?|3,3|4,four|5,5|6,6|7,7|8,eight|ix,9}	" "
--rightsub	<text>	subtitle of the chat output table. If leftsub is included, they volition be separated past a diamond icon	---	--rightsub|some text --rightsub|DC @{selected|spell_save_dc} DEX	" "
--desc	<text>	optional description at bottom of chat output table	---	--desc| Line 1 of the description%br%Line 2 of the description	Note: If you lot want to add line breaks in your clarification, use the code %br% as shown in the example to the left
--hideNames	<true/yep/1/false/no/0>	If true, the token names volition be replaced with Target_#	FALSE	--hidenames|1	" "
--titlecardbackground	<html>	Value to gear up the html "background-image:" property of the title field of the conversation output	linear-gradient(red, yellow)	--titlecardbackground|linear-gradient(#995522, blue) --titlecardbackground|url('https://s3.amazonaws.com/files.d20.io/images/ 248538196/c9xft1A2jWNqOkBsxQwyLQ/max.jpg?1633278017');background-size: 100% 100%; background-repeat: no-echo;	encounter #Using custom images for championship groundwork for more info on using custom title groundwork images
--titlefontface	<fontName>	Font style of the conversation output title	Contrail One	--titlefontface|Contrail One	" "
--titlefontcolor	<#RRGGBB>	Font colour of the chat output title	#EEEEEE	--titlefontcolor|#EEEEEE --titlefontcolor|red	" "
--titlefontsize	<html size>	Font size of the chat output championship	1.2em	--titlefontsize|1.2em --titlefontsize|18px	" "
--titlefontlineheight	<html size>	line-superlative of the chat output title	1.2em	--titlefontlineheight|i.2em --titlefontlineheight|18px	" "
--titlecardbottomborder	<html>	Html edge of the table title	2px solid #444444;	--titlecardbottomborder|2px solid #444444	" "
--subtitlefontface	<fontName>	Font style of the chat output subtitle	Tahoma	--subtitlefontface|Tahoma	" "
--subtitlefontcolor	<#RRGGBB>	Font color of the chat output subtitle	#333333	--subtitlefontcolor|#333333	" "
--subtitlefontsize	<html size>	Font size of the conversation output subtitle	13px	--subtitlefontsize|13px	" "
--bodyfontface	<fontName>	Font style of the chat output torso	Helvetica	--bodyfontface|Helvetica	" "
--bodyfontsize	<html size>	Font size of the chat output trunk	14px	--bodyfontsize|14px	" "
--tablebgcolor	<#RRGGBB>	Groundwork colour of the impairment and description fields	#EEEEEE	--tablebgcolor|#EEEEEE	" "
--tableborder	<html>	Html border of the table	2px solid #000000;	--tableborder|2px solid #000000;	" "
--tableborderradius	<html>	Html edge radius of the table	6px;	--tableborderradius|6px;	" "
--tableshadow	<html>	Html shadow of the table	5px 3px 3px 0px #aaa;	--tableshadow|5px 3px 3px 0px #aaa;	" "
--evenrowbackground	<#RRGGBB>	Groundwork color of the even rows of the Relieve fields	#DDDDDD	--evenrowbackground|#DDDDDD	" "
--oddrowbackground	<#RRGGBB>	Background colour of the odd rows of the Save fields	#FFFFFF	--oddrowbackground|#FFFFFF	" "
--evenrowfontcolor	<#RRGGBB>	Font color of the even rows of the Save fields	#000000	--evenrowfontcolor|#000000	" "
--oddrowfontcolor	<#RRGGBB>	Font color of the odd rows of the Save fields	#000000	--oddrowfontcolor|#000000	" "

Chat Output Crook Sheet

The following describes the diverse regions and features of the chat output, forth with labels for which #Conversation Output Style Commands are relevant to which regions

Annotation: if a target token does not have artwork, the icon region will be blank, but the ping-pull will withal function if that region is clicked. Ping-pulls are visible to all players.

NOTE: Results for tokens on the GM layer will be whispered to the GM. Ping-pulls from from this area volition only be visible to the GM.

Quirks, Recommendations, Known Issues and/or TBD

1. (Quirk) If you specify a fixed radius for a foursquare or circle AoE, the actual area covered volition depend on whether the "float" keyword is used in the --aoeType| command.
   1. If "float" keyword is included (AoE untethered from sourceToken), you will get a truthful radius. East.m. a 10ft radius covers a 4x4 square
   2. If "float" keyword is omitted (AoE is tethered to sourceToken), the origin token square is not counted toward the radius. E.g. a 10ft radius volition be "within 10ft of the token", making the bodily AoE comprehend a 5x5 square region. Nevertheless, see issue #1 below
2. (Quirk) For float AoE types, if --forceIntersection is omitted, the default beliefs is to forcefulness the controlToken to intersection, unless the AoE size is i foursquare or less. For larger AoEs you typically desire to middle the AoE on an intersection, while for single foursquare AoEs you typically want it to be centered in the square via snap to center. If --forceIntersection is explicitly gear up, the script will laurels the explicit setting.
3. (Quirk) When applying status markers from a custom uploaded mark fix, the full marker name::number must be included in the --conditionFail command as shown below. The easiest way to find the proper name::number code for a custom set is to open up your token-modern handout and roll to the section with all the status markers as they will be listed there. If you employ one of the default Roll20 markers, yous would merely need the name. Yous can mouse over the radial menu in the VTT to find just the name.

---

1. (Recommendation) For 5e-style cones, I recommend starting with --minGridArea|0.25 and --origin|nearest, face up. Requiring more than area coverage may start to omit the squares nearest the sourceToken for some orientations. Allowing the cone to originate on token faces gives more flexibility in positioning.
2. (Recommendation) For PF-mode cones, I recommend starting with --minGridArea|0.5, --origin|nearest, and --forceIntersection|1 to better estimate the rules. Still, come across consequence #4 below.

---

1. (Outcome, TBD) Foursquare and circle AoE's of stock-still radius, "nearest" origin pt, and linked to the sourceToken (i.due east. not using the "bladder" keyword) does not properly take into account the token size, so currently only accurate for a 1 square token. This is on the listing of things to gear up.
2. (Consequence, TBD) If 5e Proficency Dice are used, there is currently no way to reference the rolled DC and display in the Subtitle region. Prob going to make a Macro-level variable to allow a replacement of that text with the rolled value. Either mode, the DC will demand to exist wrapped in square brackets to perform the roll, east.thousand. --dc|[[@{selected|spell_save_dc}]]
3. (Consequence, TBD) If you click on the token icon in the chat output, a ping-pull is performed for all players. Saving throw results for tokens on the GM layer are whispered to the GM. However, currently if the GM clicks the token icon in chat, it will still ping-pull everyone, potentially revealing the token'southward location to players. This is on the list of things to fix. (fixed!)
4. (Result, no fix?) Existing Pathfinder cone templates do not announced to employ a uniform dominion for determining if a foursquare is in the cone. SmartAoE applies the same --minGridArea percentage dominion to each grid square. This is more mathematically "fair", IMO, but those wishing to adhere strictly to PF cone template guidelines will probable need to use another method than SmartAoE (unless someone comes upward with a combination of settings that piece of work within the SmartAoE framework) (fixed with new PFcone and PFcircle aoeTypes!)
5. (Issue, TBD) Resistance/amnesty rules are elementary at present. If a creatures is resistant to, say, piercing damage from just not-silvered or not-magical sources, the script currently does not account for this. Each game ruleset and naming convention is different, and I haven't still come up with an elegant style to handle this that is generic enough for multiple rulesets.
6. (Roll20 Issue) If yous make a very large AoE and trigger fx, you lot may come across some lag depending on ...??? This seems to be a Roll20 quirk that fifty-fifty affects single instances of fx. Just be aware of this.

Using custom images for title background

The --titlecardbackground subcommand will accept css styling information to further personalize the chat output. One fun play a trick on is to utilize an epitome for your title background.
Example: --titlecardbackground|url('https://s3.amazonaws.com/files.d20.io/images/248538196/c9xft1A2jWNqOkBsxQwyLQ/max.jpg?1633278017');background-size: 100% 100%; groundwork-echo: no-echo;

If you have something in your image library that you desire to use, TheAaron came upwards with a simple script to give you lot the URL for that image. Install the post-obit, drag your art to a map, and type !GetTokenUrl. The URL volition be printed to chat!

(() => {     var CMD = '!GetTokenUrl';          on('chat:bulletin', msg => {         if(msg.content === CMD && msg.selected.length > 0) {             var urls = _.map(msg.selected, selected => {                 var token = getObj('graphic', selected._id);                 render token.get('imgsrc');             });                          sendChat('Get TOKEN URLs', urls.join('<br/><br/>'));         }     }); })();        

Example SmartAoE Macros

I accept put several 5e spell macros in a GitHub repo here:[Spell Repo]

Simple 20ft cube

This macro has blank-bones functionality. It but spawns a 20ft cube, using the float keyword to disconnect it from the sourceToken. Note that since the "float" keyword was used, the script automatically snaps the controlToken to the grid intersections.

!smartaoe {{   --aoeType|square, float   --radius|10ft }}        

Simple variable cube

This macro has bare-basic functionality. It just creates a square AoE linked to the sourceToken and creates burn-fire fx on trigger. Radius is variable based on relative positions of source & command tokens.

!smartaoe {{   --aoeType|square   --fx|burn-fire }}        

Simple 5e fixed-radius cone with origin rotation

Creates a simple 5e-style 30ft cone with default coloration (no trigger effects). The origin point of the cone is rotated counter-clockwise and then clockwise around the token to fine tune the cone positioning using !smartrotateorigin ccw/cw commands in dissever ability macros (described in #Initial Setup/Install. Both the token corners and faces are valid origin points due to the control --origin|nearest, face up in the AoE-generation macro.

!smartaoe {{   --aoeType|5econe   --radius|30ft   --minGridArea|0.25   --origin|nearest, face }}        

!smartrotateorigin ccw        

!smartrotateorigin cw        

True radius 15ft cone approximation

The following uses the "cone" aoeType, with a query determining the cone radius. Radius is fixed at 15ft.

!smartaoe {{   --aoeType|cone, ?{Enter cone bending|xc}   --radius|15ft   --minGridArea|0.50   --origin|nearest, face }}        

Pathfinder 20ft circle

The "PFcircle" aoeType performs an additional filter to the affected grid squares, using the "every other diagonal counts as 2 squares" rule.

!smartaoe {{   --aoeType|PFcircle, bladder   --radius|20ft   --minGridArea|0.fifty }}        

Burning Hands (5e)

This macro creates a 15ft 5e-fashion cone using the default AoEControlToken character for the controlToken, allows token faces to exist the signal of origin, triggers fire fx, rolls 5e DEX saves (ignoring tokens with a "1" in a custom aspect called "SmartAOE_ignore", and machine applies impairment to the tokens afterward saves are made. Also, green/reddish condition markers for pass/fail are applied, and tokens having 0 in their bar1 field volition gain the "expressionless" condition marking. Annotation: The macro below includes --instant|ane, merely the animated gif was created earlier that command was available.

!smartaoe {{   --title|Burning Hands   --leftsub|Slot level ?{Cast at what level?|1,one|2,two|3,three|iv,4|five,5|6,6|seven,vii|8,8|ix,9}   --rightsub|DC @{selected|spell_save_dc} DEX    --aoeType|5econe   --forceIntersection|0   --radius|15ft   --origin|nearest, face   --minGridArea|0.25   --minTokArea|0.25   --fx|fire-fire   --dc|@{selected|spell_save_dc}   --saveFormula|5eDEX   --damageFormula1|[[(?{Cast at what level?}+two)d6]]   --damageType1|Burn down   --ignore|SmartAOE_ignore,ane    --instant|one    --autoApply|ane   --bar|ane   --conditionFail|red   --conditionPass|green   --zeroHPmarker|dead   --desc|Every bit yous concur your hands with thumbs touching and fingers spread, a sparse sheet of flames shoots along from your outstretched fingertips. Each creature in a 15-foot cone must make a Dexterity saving throw. A creature takes 3d6 burn down damage on a failed save, or half as much harm on a successful one.%br%%br%The fire ignites any flammable objects in the area that aren't being worn or carried. }}        

Faerie Burn down (5e)

This macro creates a 20ft cube (square, float). On trigger, creates fx and autorolls saving throws. On a failed save, a condition mark is applied to the token to point that it now grants advantage. Since this item condition marker is from a custom uploaded marking set, the total marker name::number must exist included in the --conditionFail command every bit shown beneath. If you utilise one of the default Roll20 markers, you would just need the name. This is a quirk of the Roll20 api. Conversation output is customized for a more Fae-appropriate theme. NOTE: The macro below includes --instant|1, merely the animated gif was created before that control was available.

!smartaoe {{   --title|Faerie Burn   --leftsub|Slot level ane   --rightsub|DC @{selected|spell_save_dc} DEX   --titlecardbackground|linear-slope(#af70c2, #e0cce6)   --oddrowbackground|#af70c2   --evenrowbackground|#e0cce6   --oddrowfontcolor|#000000   --tablebgcolor|#e0cce6   --aoeColor|#bd39e650   --aoeOutlineColor|#9611bf    --aoeType|square, bladder   --radius|10ft   --minTokArea|0.25   --fx|bubbling-magic   --dc|@{selected|spell_save_dc}   --saveFormula|5eDEX    --autoApply|1   --instant|one   --conditionFail|GrantsAdvantage::1510122   --desc|Each object in a twenty-foot cube within range is outlined in blue, greenish, or violet light (your selection). Whatsoever creature in the area when the spell is bandage is also outlined in light if it fails a Dexterity saving throw. For the duration, objects and affected creatures shed dim low-cal in a 10-foot radius.%br%%br%Whatever assault scroll against an affected creature or object has advantage if the assailant can see it, and the affected creature or object can't benefit from existence invisible. }}        

Ice Tempest (5e)

This macro creates a 20ft radius "floating" circle using a custom multi-sided token from a character called "GenericSpellAoE" (default token set upwards beforehand) for the controlToken, triggers ice fx, rolls 5e DEX saves (ignoring tokens with a "1" in a custom aspect chosen "SmartAOE_ignore", and delays damage awarding to the tokens until the P/F icons are clicked in the chat output. There are two harm types for this spell. Also, tokens having 0 in their bar1 field subsequently damage is practical from this click event volition gain the "dead" condition marker. In that location are likewise several changes to the formatting of the chat output from the default. NOTE: The macro beneath includes --instant|1, but the animated gif was created earlier that command was available.

!smartaoe {{   --title|Ice Storm   --leftsub|Slot level ?{Cast at what level?|iv,4|five,5|6,half-dozen|7,7|eight,viii|9,9}   --rightsub|DC @{selected|spell_save_dc} DEX   --titlecardbackground|linear-gradient(blue, cyan)   --oddrowbackground|#00ccff   --evenrowbackground|#edfcfc   --oddrowfontcolor|#000000   --tablebgcolor|#edfcfc     --controlTokName|GenericSpellAoE   --controlTokSize|8   --controlTokSide|14   --aoeColor|#00ccff50   --aoeOutlineColor|#0099ff   --aoeType|circumvolve, float   --radius|20ft   --minGridArea|0.25   --minTokArea|0.25   --fx|burn-frost   --dc|@{selected|spell_save_dc}   --saveFormula|5eDEX   --damageFormula1|[[(?{Bandage at what level?}-ii)d8]]   --damageType1|Bludgeon   --damageFormula2|[[4d6]]   --damageType2|Common cold   --ignore|SmartAoE_Ignore,1    --instant|1    --autoApply|0   --bar|one   --zeroHPmarker|expressionless   --desc|A hail of rock-hard ice pounds to the ground in a 20-foot-radius, 40-foot-high cylinder centered on a point within range. Each creature in the cylinder must brand a Dexterity saving throw. A creature takes 2d8 bludgeoning harm and 4d6 cold damage on a failed save, or half as much damage on a successful i.%br%%br%Hailstones turn the tempest's surface area of effect into difficult terrain until the end of your next turn. }}        

Spirit Guardians (5e)

A couple of different concepts in this macro. First, since the spell is centered on and moves with the pulley, the command --controlTokName|self is used. Since the default behavior for a "float" type AOE is to forcefulness the origin to a grid intersection and we desire the token to snap to grid, we use --forceIntersection|0. Technically, 5e rules count diagonal squares as only 5ft. I used a circle here with true diagonal altitude and requiring fifty% of the grid to be covered, but y'all could easily change to a square by changing the aoeType command to --aoeType|square, float. Since the spell effects are triggered at the start of the creature's turn, we don't want to trigger the entire AoE region. Instead, we volition pass a target token_id to an alternate triggering command (!smartquery @{target|Cull a Target|token_id}). When the spell ends, it is removed with another alternate control (!smartremove). Both of these commands accept been added every bit an ability on the caster token.

The macro creates a 15ft radius "floating" circle centered on caster, has transparent AoE gridlines, triggers holy fx, rolls 5e WIS saves for affected tokens (ignoring tokens with a "1" in a custom aspect called "SmartAOE_ignore"), and automatically applies damage to the token. Tokens having 0 in their bar1 field after impairment is practical will gain the "expressionless" condition marker. The chat output has been customized, including the use of a groundwork prototype in the championship. This paradigm has been uploaded into my personal fine art library and is referenced by its URL.

!smartaoe {{   --title|Spirit Guardians   --leftsub|Slot level ?{Bandage at what level?|iii,3|iv,4|5,5|six,6|7,7|8,8|nine,9}   --rightsub|DC @{selected|spell_save_dc} WIS  --titlecardbackground|url('https://s3.amazonaws.com/files.d20.io/images/253253846/-01wiItwF1nthkh7UwRkIQ/max.png?1635696123');background-size: 100% 100%; background-repeat: no-echo   --oddrowbackground|#ffffaa   --evenrowbackground|#ffffff   --oddrowfontcolor|#000000   --tablebgcolor|#ffffff   --aoeColor|#ffff0050   --aoeOutlineColor|#cccc00   --gridColor|#ffffff00    --controlTokName|cocky   --aoeType|circumvolve, bladder   --radius|15ft   --forceIntersection|0   --minGridArea|0.5   --minTokArea|0.25   --fx|burn-holy   --dc|@{selected|spell_save_dc}   --saveFormula|5eWIS   --damageFormula1|[[?{Cast at what level?}d8]]   --damageType1|Radiant    --ignore|SmartAoE_Ignore,1    --autoApply|1   --bar|1   --zeroHPmarker|dead }}        

Aura of Vitality (5e Healing)

This macro is nearly identical to the Spirit Guardians macro higher up (read description for explanations). The only differences are: 1)the --noSave|i command is used as in that location is no saving throw (the save becomes hardcoded to 0 and the DC hardcoded to 99999), two)radius is larger, 3)the damageFormula results in a negative number! (this is interpreted as healing by the script), 4)no tokens are ignored, and 5)the title background image URL is different.

Note: Due to a quirk of the Roll20 inline scroll parser, y'all can't have a negative number in the first position. That is why you volition find the strange [[0 + [[0 - two]]d6]] syntax for the healing "harm"

The macro creates a 30ft radius "floating" circle centered on pulley, has transparent AoE gridlines, triggers holy fx, forces targets to "fail" the saving throw, and automatically "heals" (applies negative damage to) the token. Tokens are not healed over their max.

At present, I realize that a simpler approach using token auras and a vanilla macro would work just likewise. My point in including this example is to help you understand some of the syntax and behavior of the script ;)

!smartaoe {{   --title|Aura of Vitality   --leftsub|Slot level 3   --rightsub|No Save  --titlecardbackground|url('https://s3.amazonaws.com/files.d20.io/images/253287692/0dpMLj12wwv9cRy5RRw6LA/max.png?1635706258');background-size: 100% 100%; groundwork-repeat: no-echo   --oddrowbackground|#ffffaa   --evenrowbackground|#ffffff   --oddrowfontcolor|#000000   --tablebgcolor|#ffffff   --aoeColor|#ffff0050   --aoeOutlineColor|#cccc00   --gridColor|#ffffff00    --controlTokName|self   --aoeType|circle, bladder   --radius|30ft   --forceIntersection|0   --minGridArea|0.5   --minTokArea|0.25   --fx|bubbles-holy   --noSave|ane   --damageFormula1|[[0 + [[0 - 2]]d6]]   --damageType1|(Healing)   --autoApply|1 }}        

Wall of Fire (5e)

The post-obit uses the "wall" aoeType and a width of 3u (15ft on a standard map). The spell technically produces a wall 1ft wide, just all creatures in a wall square or inside 10ft of that square on i side are affected, making the width finer 15ft.

!smartaoe {{   --title|Wall of Burn down   --leftsub|Slot level ?{Cast at what level?|4,4|5,5|vi,6|7,7|8,viii|9,ix}   --rightsub|DC @{selected|spell_save_dc} DEX    --aoeType|wall   --offset|1,0   --minGridArea|0.5   --radius|30ft   --width|3u   --fx|burn-fire   --dc|@{selected|spell_save_dc}   --aoeColor|histrion   --aoeOutlineColor|#990000   --damageFormula1|[[(i+?{Cast at what level?})d8]]   --saveFormula|5eDex    --autoApply|1   --bar|1   --zeroHPmarker|dead }}        

Custom Ruleset Example, 180deg cone

The following instance shows how to implement a custom ruleset via deferral characters in the --saveFormula command. In our fictional game arrangement, successes are determined by rolling 2d100kh1, adding modifiers, and comparison to a static value of 66. In this example, modifiers are target defense (@{psi_shield_bonus}) and "caster" power level (@{selected|psi_strength}. Note that the "scroll" is deferred to script runtime by replacing inline curl brackets [[...]] with the <<...>> constructor. Target-based attributes must be deferred likewise in order for the script to use each target'south attribute value. The @{...} syntax for target attributes are replaced with the a{...} constructor. Since the "pulley"-based modifier is the same for all targets, the normal @{selected|attrName} syntax is used and will be expanded usually by the Roll20 parser prior to passing it over to the script. If the resulting gyre is >= 66, and so the defender succeeds. On a success, no impairment is practical (due to the command --damageSaveRule|*0. On a failure, impairment is practical automatically, and the expiry-zone marker is practical. If the target has a bar1 value of 0 after damage awarding, the dead condition marker is also practical. This instance as well features a custom title background prototype, custom AoE colors, and a radius based on a query that is re-used between the --radius and --rightsub commands.

!smartaoe {{   --championship|Psi Boom   --leftsub|1x/24-hour interval   --rightsub|?{Enter radius|15ft,15ft|30ft,30ft}   --subtitlefontcolor|#ffffff   --titlecardbackground|url('https://s3.amazonaws.com/files.d20.io/images/254392553/tR0yBgEO-OWdvmskzHBZrg/max.png?1636291858');background-size: 100% 100%; background-repeat: no-repeat    --aoeType|cone, 180   --radius|?{Enter radius}   --minGridArea|0.l   --origin|nearest   --forceIntersection|1   --aoeColor|#ff00ff50   --gridColor|#aa00aa   --aoeOutlineColor|#880088   --fx|burn-charm   --instant|1    --dc|66   --damageFormula1|[[2d10 + @{selected|psi_strength}]]   --saveFormula|<<2d100kh1 + a{psi_shield_bonus} - @{selected|psi_strength}>>   --damageSaveRule|*0   --conditionFail|death-zone   --zeroHpMarker|dead   --autoApply|1 }}        

[For script writers] Registering your token change events to SmartAoE

Script writers tin can now register their token change events to SmartAoE!

For example, the Aura/Tint HealthColor^(Forum) script looks for changes in token bar values to set the aura color. However, changes made by the api don't usually trigger this event, so information technology would remain idle when SmartAoE removed/added hp. By registering your token change event handler function, SmartAoE will notify your script to trigger your function after it changes any token properties.

Add something like this line to your script where you would normally register your events:

          if('undefined' !== typeof SmartAoE && SmartAoE.ObserveTokenChange){                 SmartAoE.ObserveTokenChange(function(obj,prev){                     myEventHandlerFunction(obj, prev);                 });             };        

So, extending the example of Aura/Tint HealthColor^(Forum), the new registerEventHandlers part in that script would read as follows:

          //Register TRIGGERS------------         registerEventHandlers = function () {             on('conversation:message', handleInput);             on("change:token", handleToken);             on('add together:token', part (t) {                 _.delay(() => {                     permit token = getObj('graphic', t.id),                     prev = JSON.parse(JSON.stringify(token));                     handleToken(token, prev, "Aye");                 }, 400);             });             //register this script to SmartAoE to handle linked bar hp changes             if('undefined' !== typeof SmartAoE && SmartAoE.ObserveTokenChange){                 SmartAoE.ObserveTokenChange(office(obj,prev){                     handleToken(obj, prev, "NO");                 });             };         };        

This should wait familiar to those that take washed the same thing with TokenMod, as I blatantly ripped off Aaron's code. I repent for nothing ;)

cannlaire1989.blogspot.com

Source: https://wiki.roll20.net/Script:SmartAoE

Share :