[Script] SmartAoE - graphical interface for implementing AoE's on gridded maps

@Daryl: what GiGs said ;). I usually try to avoid html replacements whenever possible, though it's sometimes a necessary evil if you really want a particular functionality. Another thing to keep in mind when you use the Adv query for --saveFormula is that whatever you choose will be applied to ALL the tokens in the area. So, if one creature has circumstantial DisAdv and the rest don't, you would probably need to use a "Trigger-Target" on all of them. Or if there are a ton of tokens, perhaps temporarily move the outlier token out of the AoE, "Trigger-ALL", then move it back into the area and Trigger-Target with DisAdv. That's all a bit fiddly for me, which is why I have just used the vanilla 5eINT so far in my games. Again, it comes down to how frequent these cases come up in your own game to determine what works best for you.

@Leon: So, nothing happens and you get no error messages? Do any of your macros using other api scripts work?

Hey David me again this is probably a really simple 1 & im just not that good with these macro things yet but im trying to create a macro for the thunderwave spell & i cant figure out how to get a 15ft cube/square that comes from in front of the token if i try it with float i can only seem to get 5ft then a 10ft radius 7.5ft just comes up the same as 10ft.    

Asher, you were on the right track with a square float type. You just need to set radius 7.5ft and forceIntersection|0. 

Try this (the offset is not needed, just makes it easier to see the token when spawned):

!smartaoe {{
  --aoeType|square, float
  --forceIntersection|0 ​
  ​--radius|7.5ft
  ​--offset|1,0
}}

This is a great API, have you intended to submit it to the Roll20 API library, so it could be installed from there?

Thanks, Andreas! Yes, this will for sure be a one-click option. I've just been getting a broader playtest sample to sniff out bugs before uploading. We've found a few, so I'm feeling more confident, but I'm still getting the occasional odd case for certain cones (particularly narrower ones) where things don't quite jive, likely related to point-in-polygon issues due to floating point approximations for literal edge cases I alluded to above (intersections of the AoE boundary lines with grid squares - the test point lies exactly on the polygon perimeter, but floating point errors result in them being calculated as "outside" and thus filtered out). It's rare enough though that it probably is "good enough" as-is for 99% of tables, so I will probably still submit to one-click even if this is not fully resolved. 

FYI I uploaded all the SmartAoE macros I currently use in my games to the following Github Repo

https://github.com/djmoorehead/SmartAoE-Macros/tree/main

Some of these use a custom rollable table token "character" as the control token. Some others use custom condition markers. You'll need to delete/modify as needed. Several use artwork I made in GIMP for the titlecardbackground.

Edit: note that there are comments at the top of each of these files which should not be included in your macros. Only copy starting from "!smartaoe".

Thanks again David that worked great

I am trying to edit the automatically installed table macro to include the player color variable for the AoE's and the lines, but I can't figure out where to put that in the existing macro. Any help appreciated.

its always best to post macros as actual text, not screenshots

Wyatt, the chat menu macro calls abilities on the AoEControlToken character sheet. You would need to edit the abilities themselves to change their functionality. The only thing editing the AoEGenerator macro is good for is adding/removing some of the buttons or other chat display features.

David M. said:

Wyatt, the chat menu macro calls abilities on the AoEControlToken character sheet. You would need to edit the abilities themselves to change their functionality. The only thing editing the AoEGenerator macro is good for is adding/removing some of the buttons or other chat display features.

Okay, I've found making the individual spells per player is more useful for combat anyways so I'm going that route. Thanks for the reply!

Cool, I figured most people would go that route. The pre-installed macro is more for those that just want to use it for general targeting purposes or as a "quick-start" no-frills way to test out the script. Another option is to use the AoEGenerator macro as a template for a "spellbook" macro containing all of your custom SmartAoE spells, grouped by level for example. 

David M. said:

Cool, I figured most people would go that route. The pre-installed macro is more for those that just want to use it for general targeting purposes or as a "quick-start" no-frills way to test out the script. Another option is to use the AoEGenerator macro as a template for a "spellbook" macro containing all of your custom SmartAoE spells, grouped by level for example. 

I just got started on using the API today, and this was something I wanted to do (organize all the spells into a spellbook). Nested macros in a query doesn't work, though I'm not surprised. My next move was to just add on to the AoEControlToken sheet and reference them just like the AoeGenerator macro does. Do you think this is best practice, or am I missing something? I also considered putting them on my player's character sheets instead, but my instinct is that it's better to centralize them all on one sheet.

Ian, having a centralized repository like what you are describing is the commonly used "macro mule" concept. It's really up to you which sheet you want to put it on. I would personally probably make a new sheet, as there are already a bunch of abilities on the AoEControlToken sheet. If your players don't want to customize the appearance, etc. of the spells, then putting them all on one sheet is the way to go - then players can just reference the spells that they have from that sheet. But if they want "their" fireball to look a certain way, I would put it on the player sheet.

Here's a link that explains the Macro Character Sheet.

Are we free to post SmartAOE macros that we have created here? Or is there a better place to do that?

Sure, you can post here! I was going to start a dedicated thread but hadn't gotten around to it yet.

I suppose we can start here and migrate over once you have the time :)

Silly question: How does one create the grey box to put the macro in?

David M. said:

Asher, you were on the right track with a square float type. You just need to set radius 7.5ft and forceIntersection|0. 

Try this (the offset is not needed, just makes it easier to see the token when spawned):

!smartaoe {{
  --aoeType|square, float
  --forceIntersection|0 ​
  ​--radius|7.5ft
  ​--offset|1,0
}}

Click on the line or select the lines you want to format, then click the magic wand icon on the left of the message toolbar and select "code" 

Brilliant! Thanks!

SmartAOE - ARMS OF HADAR

Improvements and suggestions (including colours and layout) are welcome

!smartaoe {{
  --title|Arms of Hadar
  --rightsub|DC @{selected|spell_save_dc} STR
  --titlecardbackground|linear-gradient(black, #9900ff)
  
  --oddrowbackground|#666666
  --evenrowbackground|#edfcfc
  --oddrowfontcolor|#000000
  --tablebgcolor|#edfcfc
  
  --controlTokName|AoEControlToken
  --controlTokSize|1
  
  --aoeColor|#434343
  --aoeOutlineColor|#000000
  --aoeType|circle
  --radius|10ft
  --minGridArea|0.25
  --minTokArea|0.25
  
  --fx|burst-death
  --dc|@{selected|spell_save_dc}
  --saveFormula|5eSTR
  
  --damageformula1|[[(1+?{Cast at what level? |1,1|2,2|3,3|4,4|5,5|6,6|7,7|8,8|9,9})d6]]
  --damageType1|Necrotic
  --instant|1
  
  --autoApply|yes
  --bar|1
  --zeroHPmarker|dead
  
  --desc|You invoke the power of Hadar, the Dark Hunger. Tendrils of dark energy erupt from you and batter all creatures within 10 feet of you. Each creature in that area must make a Strength saving throw. On a failed save, a target takes 2d6 necrotic damage and can’t take reactions until its next turn. On a successful save, the creature takes half damage, but suffers no other effect. 
At Higher Levels. When you cast this spell using a spell slot of 2nd level or higher, the damage increases by 1d6 for each slot level above 1st.
}}

Not sure why the spacing of the original code is being ignored and crushed together on the Cloudkill example.

Thanks for sharing these Mizzri! In case you missed my earlier post, I uploaded all the SmartAoE macros I have so far to GitHub here. Many of them have custom title background images as well. Cloudkill was on that list, for example. Just wanted to let you know in case you wanted to save some time! 

Note: in your Cloudkill macro, I noticed that there are duplicate entries for --damageFormula1. Only the last one will be used (luckily it's the one you want). Also, the --ignore line is specific to my game convention (I added an attribute called "SmartAoE_Ignore" to my PCs and other tokens representing object "characters" like lanterns, etc.). Not sure if you are using the same convention or not. That line won't hurt anything if you aren't, but just an FYI.

Thanks David. I'll delete my example in favour of your GitHub version, and wont post any you have already created!

No need to delete the post! I was just trying to save you some effort if you were making a bunch of macros :)

All good! I don't want people accidentally grabbing my poorly-coded versions, when you have proper versions on your GitHub :D

I do have a question about WEB: What part of the code causes the AOE marker to remain after the spell is triggered? I assume it's

--ignore|SmartAOE_ignore,1 

In my GitHub Web example, it's this line:

--conditionFail|Restrained::3381563

There is a similar command called --conditionPass. If the character token passes the save, then a different marker can be added.

Note that the example above is using a custom status marker that I created for my game. If you want to use the default Roll20 markers, you only need the name of the marker (found by hovering over the marker in the token's radial popup menu). If you have custom markers uploaded to your game, you need both the name and the number as in my example. This is a requirement imposed by the Roll20 api. If you use custom markers, the easiest way to find these numbers is to open your Token-mod handout and scroll down to the part that talks about status markers.

The --ignore subcommand is there for cases where you want to exclude certain tokens from automatically rolling the saving throw. For example, my players like to roll their own saves, and I use character sheets for some objects like light sources, conjurations, and other inanimate objects that I don't want saving throws rolled for. You input an attribute name and a value. If the value of that attribute on a token within the AoE matches that of the --ignore parameter, then no save will be rolled.  In my games, the attribute is "SmartAoE_ignore" and the value is "1", but it can be customized to whatever you want.

I'm using the --conditionFail|cobweb for mine, but my question was actually regarding the AOE grid remaining after the spell was cast (obviously to outline the webs on the ground)

Ah right, ok. For a persistent spell effect, either use --instant|0 or just remove the --instant line completely. The script defaults to the AoE sticking around until the control token is deleted.

Brilliant! Thanks! It's a shame there is no way (that I know of) for macros to spawn tokens, since there is some nice artwork available for webs and the like.

You can! A couple of options. For SmartAoE, you can use the following optional commands:

  --controlTokName|
  --controlTokSize|
  --controlTokSide|

To set up, create a character sheet for the AoE effect (e.g. "web") and set the default token to the appropriate artwork (best to use images with some transparency). Then use --controlTokName to reference that "character". Set the size in units appropriately with --controlTokSize. If you use a rollable table token to handle multiple AoE art, you can set the side as well.

You can adjust the aoecolor to something that matches or set to fully transparent. See my Ice Storm example on the wiki. I have a character sheet called GenericSpellAoE whose default token is a rollable table token. I set the controlTokName, size, and side.

NOTE: if you use marketplace images, you will first have to save and upload the images into your personal art library, as Roll20 doesn't allow the api to use marketplace art directly.

If you just want to spawn tokens without using SmartAoE, you can look into my SpawnDefaultToken script. This is how I handled AoE's before I wrote SmartAoE. That script has some additional options that SmartAoE does not (spawning multiple tokens in various placements, light emission, etc.) 

Running into an issue spawning this token. I've uploaded the premium asset to my library, created a character named the same as the artwork and selected the image as the character's token, but I am still getting this error when I attempt to use the macro.

Unable to find imgsrc for default token of (undefined)
You must use an image file that has been uploaded to your Roll20 Library

Yep, see the "NOTE:" in my last post ;)

The Roll20 api will only allow images in your "personal" art library to be spawned on the VTT. Marketplace purchases are not added to your personal library by default. You can do the following, however:

1) drag the image to the map
2) select the token and press "z"
3) right click the zoomed image and save to a local file location
4) upload the newly saved file to your personal art library. 

A pain, I know, but it's a Roll20 limitation.

Thanks again for your help and patience, David. I see the difference between what I did and what you suggested.

The image is working properly now, but I've lost some functionality of SmartAOE in the process: The target image in the middle of the grid no longer appears. When I click on and drag the 4x4 image/AOE grid created to the casting destination, I no longer get the Token Actions (Trigger ALL etc).

Ah yes, that would be another important step. My bad. Best practice would be to also copy those token actions over from the AoEControlToken to your new character sheet. This is one reason I use a rollable table token: so I don't clutter up my journal and have to create lots of character abilities.

This is a fantastic script and seeing Fireball actually happen will blow my players away (heh).

I see the previous post about using spell cards etc. but I try to go light on the number of scripts I install, this one is definitely worth it to make the process of dragging on an AoE template, arguing about who gets hit, rolling all the checks and applying the damage MUCH nicer. However, I would dearly love it if worked with the Roll20 5E Companion Script for spell slot tracking, they've just gotten used to that and lets them concentrate on what they want to do rather than ticking boxes.

Thanks again, even as-is this a (literal) game-changer for my caster's (and monsters') turns.

Thanks Octonaut! Resource management is actually the next thing I want to add to this script. I'm a bit behind on updates I wanted for SmartAoE and the Spawn script due to various reasons (holidays, feeling a bit under the weather, and some other things) but I hope to start looking into this sometime this weekend. Stay tuned!

My workaround;

• set the spell output to Spellcard.
• cast the spell from the sheet and use up arrow in chat to see the code there and copy it. (My example doesn't actually show that but that is the simplest way, I think)
• create a macro in the Attributes and Abilities tab with the name of the spell (I append them with AOE. for two reasons - one to distinguish from regular spell macro and two, so the Token Action Maker script won't touch it) and paste the code.
• put the rest of the code that calls the !SmartAOE script

For example, I set up a character's Moonbeam macro as below (note the lines before !smartaoe are the call to the sheet spell macro and was from the Token Action Maker script)

It does query level of casting twice, which is not ideal but my players are OK with it. It deducts the spell slot and all the other things!

%{-MhHHG-8U-1SX9a-n5I1|repeating_spell-2_-MhjhTEwuB5-1y3mIQtg_spell}

!smartaoe {{
  --title|Moonbeam (Perrin)
  --leftsub|Slot level ?{Cast at what level?|2,2|3,3|4,4|5,5}
  --rightsub|DC @{selected|spell_save_dc} CON
  
  --titlecardbackground|linear-gradient(#6d9eeb, #9fc5e8)  
  --aoeType|circle, float
  --aoeColor|#9fc5e850
  --aoeOutlineColor|#6d9eeb

  --radius|5ft
  --fx|burn-frost
  --minGridArea|0.5
  --minTokArea|0.25
  --dc|@{selected|spell_save_dc}
  --saveFormula|5eCON
  --damageFormula1|[[(?{Cast at what level?}+1)d10]]
  --damageType1|Radiant
  --ignore|SmartAOE_ignore,1 

  --autoApply|1
  --bar|1
  --zeroHPmarker|dead
}}

The output in chat;

Ok, I finally have Web working as I want it to, with one small exception. When the macro is first triggered, the web looks as it should, with no outline.

But once the Token Action is triggered and the spell resolves, there is a red --aoebackground created, even though the parameter is set to "transparent"

Including my code so you can see what I have entered.

!smartaoe {{
  --title|Web
  --leftsub|Slot level 1
  --rightsub|DC @{selected|spell_save_dc} DEX
  --subtitlefontcolor|#ffffff
  --bodyfontsize|12px
  --titlecardbackground|url('https://s3.amazonaws.com/files.d20.io/images/253364781/71ajr280Oxl9vDB5Bs-6ig/max.png?1635737279');background-size: 100% 100%; background-repeat: no-repeat
  --oddrowbackground|#aaaaaa
  --evenrowbackground|#cccccc
  --oddrowfontcolor|#000000
  --tablebgcolor|#cccccc
  --aoecolor|transparent
  
  --controlTokName|Web-20ftS-4x4
  --controlTokSize|4
  --aoeType|square, float
  --radius|10ft
  --minTokArea|0.25
  --fx|glow-death
  --dc|@{selected|spell_save_dc}
  --saveFormula|5eDEX 
  --autoApply|1
  --ignore|SmartAOE_ignore,1 
  --conditionFail|cobweb
  --desc|You conjure a mass of thick, sticky webbing at a point of your choice within range. The webs fill a 20- foot cube from that point for the duration. The webs are difficult terrain and lightly obscure their area.%br%Each creature that starts its turn in the webs or that enters them during its turn must make a Dexterity saving throw. On a failed save, the creature is restrained as long as it remains in the webs or until it breaks free.%br%A creature restrained by the webs can use its action to make a Strength check against your spell save DC. If it succeeds, it is no longer restrained.%br%The webs are flammable. Any 5-foot cube of webs exposed to fire burns away in 1 round, dealing 2d4 fire damage to any creature that starts its turn in the fire.
}}

Mizzri, you'll need to use the html color codes instead of the alias. Try these (the 7th/8th digits set the opacity percentage):

--aoeOutlineColor|#ffffff00

--aoeColor|#ffffff00

One more question, David. For spells that center on the caster (Arms of Hadar, for example), currently the AoEControlToken appears on the target character, but the actual AOE targeting circle does not appear until I move the AoEControlToken (and acts as a float, always centered on the caster).

Is there a way to initiate the circle of influence immediately once the macro is activated instead of having to move the AoEControlToken to spawn the targeting area?

For those, you can use this command:

--controlTokName|self

The caster token will be used as the control token. To remove the effect, make a token action ability on the caster sheet with this one-line macro:

!smartremove

Calling this command with the caster token selected will delete all AoEs tied to that token.

The only downside to this method is that you don't get to use custom art for the AoE effect. So, your choice which method you prefer.

Hi,

Thank you very much for such an awesome script. I'm, unfortunately, running into this error with every macros I'm trying to run:

(From SmartAoE): Error: libInline is not defined

Any ideas on how to resolve this? Thank you in advance for your help!

Have you installed the linInline script (available on one-click)? SmartAoE is dependent on that script.

Just started with this script. Love IT!   Trying to use the simple stuff first.  I use the AOEGenerator macro. When I use the FROM Caster macro , I don't seem to be able to remove the AOE effect unless I delete the Caster Token.  Any thoughts?

Thanks

To remove an AoE created with --controlTokName|self, make a token action ability on the caster sheet with this one-line macro:

!smartremove

Calling this command with the caster token selected will delete all AoEs tied to that token. See the wiki for more info.

EDIT - In hindsight, I should have included a "remove" button in the auto generated chat menu macro :/

Hi David thanks for the effort I really love your script.

totally new to the pro level at the moment I'm just a user and I have one issue I need help with:

I uploaded the script and created a fireball macro (small modification from the pre suggested one).

however:

it works fine in some of the maps and it does not in some others (same game)??!!??

in the non working ones the area of effect does not appear and if I press the "trigger all" button I get this ---(From SmartAoE): Error: Cannot read property 'x' of undefined-- 

I am launching it in the same way and even from the same character.

the only big difference is map width as it is set at 0.25! (big keep of giants).

So I did some trial and it seems that everything works fine until 0.3 width and then fails (another error I get below 0.3 width is (From SmartAoE): Error: Cannot read property 'get' of undefined).

also at 0.3 sometimes manages a weird area like this

any idea apart from rescaling all maps?

thanks

Andrea