[Script] KABOOM.js - Create explosions (and implosions) that manipulate token position

KABOOM.js Download Links: Version 1.2 Version 1.1 Version 1.0 Also available through 1-click install! Ever wonder why the tokens inside of your flimsy straw houses never budge when your players decide that fireball is the easiest solution to their troubles? It might have to do with the copious amounts of Sovereign Glue you keep around, but for everything else there is KABOOM! Now stops movement at walls on the dynamic lighting layer. No more spooky phasing! What can you use KABOOM for? Creating explosions that force tokens to move away. Creating whirlpools that drag things towards their centers Creating explosions that pull objects towards themselves? Creating whirlpools that spit things out? Any area of effect that requires tokens to move a towards or away from a point How do I use it? You can call KABOOM through chat with a simple message, or you can use it with other scripts by calling KABOOM.NOW(param1, param2). Detailed documentation is available below. Want to make an explosion that throws nearby things 30ft away? Just type "!kaboom 30" into chat. Want to make it a frost explosion? "!kaboom 30 --frost" to make it icy. How about an air blast that pushes stuff away a tiny bit, but at a long range? "!kaboom 5 150 no vfx" Chat Command : The basic chat command follows this format: !KABOOM effect-power [ effect-radius [ options [ --default-options]]] When you use KABOOM as a chat command, you need to have a token selected. ONLY effect-power is required. Everything else is optional. <effect-power> is the strength of the force moving tokens away or towards from the explosion point. It is measured in the same units you use on the page. Effect power can be negative if you want to pull things towards the object instead of pushing away. <effect-radius> is the maximum distance that the script search for objects to manipulate. If something is beyond this point, it will not move. Defaults to effect-power * explosion_ratio. This value is always parsed as positive! <options> are either 'no vfx', 'vfx', 'no-vfx', 'invisible', 'invis' to change whether an explosion effect appears, or 'scatter', 'no scatter' if you want to scatter tokens away from the explosion/implosion point more randomly. <more-options> can be found in the help menu, which is reached by typing " !KABOOM " or " !KABOOM --help " into chat. Through the API : The simplest function call looks something like this: KABOOM.NOW(15, [500,300]) Something more complicated may look like this: on('change:token', function(obj) { if (obj.id === big_baddie.id) { KABOOM.NOW({effectPower: 5, effectRadius: 15, type: 'holy'}, obj) } } Detailed Documentation here:  READ ME Change-log & Known Bugs: Known bugs: None so far! Version 1.0: Released to the public Version 1.1: Added support for Dynamic Lighting walls! The script now properly stops tokens moving when they collide with a wall. Tokens will not move if a wall is between it and the effect center. Tokens now always stop at the first wall they would impact (didn't do this before). Version 1.2: Added support for @{target|token_id} macros in chat commands (so players can use the script as well). The macro must appear after effectPower. Explosion VFX now scales in size with its effect power. Added another exposed function: KABOOM.getExplosionVFX(colour, radius, sparcity). KABOOM.NOW() finally returns a list of affected tokens for use in other functions.

Nice!

very neat

Will this throw tokens through walls defined on the Dynamic lighting layer, or will the tokens slam into them and stop moving?

Unfortunately I haven't found a way to get positional data of walls on the dynamic lighting layer so they phase through. TBH I'm not even sure if it's possible... But I guess I'll start testing. EDIT: It is possible and this is going to be a challenge. EDIT2: It was done.

It is possible (maybe not easy !), look at Stephen L.'s PathMath library in the repo.  He has functions for ray casting and intersection and such.

It only took 9 hours but I managed to figure it out! Admittedly most of my time was spent trying to figure out the format of PathMath function parameters. The script now obeys the laws of physics and objects are stopped at walls on the dynamic lighting layer. Sadly, it does not take into account if a wall is between the effect center and the token to be moved. I'll see if I can add that in later. EDIT: That was also done.

Awesome!  I probably should have pointed you at some of the other uses of that library...

PaprikaCC said: Sadly, it does not take into account if a wall is between the effect center and the token to be moved. I'll see if I can add that in later. Might take a look at my page navigator script's teleport functions(as ugly as they are). Specifically my mapSurround function. And actually, while writing this had a thought; a cleaner example would probably be Stephen's It's a Trap script since I believe he has essentially the same problem with figuring line of sight for detecting traps as you would for shielding tokens from the blast. Edit: Some edits for grammer, spelling, and clarity

PaprikaCC said: Sadly, it does not take into account if a wall is between the effect center and the token to be moved. I'll see if I can add that in later. It should be as easy as adding a pre check for each token where your "pathToMove" is from the epicenter to the token. /* line 218 */     // check for cover     movement_vector = checkCollision([[obj1[0], obj1[1], 1], [obj2[0], obj2[1], 1] ], walls);     if( movement_vector[1][0] !== obj2[0] || movement_vector[1][1] !== obj2[1] ) {         return;     } Something like that... (I've never used the library or tried this script out...)

I was going to test that, but I'm have a few problems.  One is that you have s for your state.KABOOM  but haven't defined s anywhere.  The other is I can't figure out how to get objects to scatter.  =D

Verified my scatter is on, but not getting any movement. BTW, you'll want to consume an extra token if your 'no' option finds a match:         case 'no':           if (input[i + 1] === 'vfx') {               options['vfx'] = false;               ++i;           } else if (input[i + 1] === 'scatter') {               options['scatter'] = false;               ++i;           }           break

Ah, figured it out.  The is_drawing thing.  Cool.  The code above placed at line 218 will prevent pushing an object with a wall next to it.  =D  Cheers!

Oh god I can't believe I forgot that. I was having issues with the state object not updating properly (it would reset upon sandbox restart to whatever it held previously) so I reverted most functions to use state.KABOOM... but I'll fix that real quick.

No worries, happens to the best of us. =D  It was really confusing because it kept telling me the error was in a different callstack (in my ImperialCalendar), but after I disabled it the error became clear. =D The fact that it had to be is_drawing was not immediately apparent. Most tokens will not be is_drawing so keying on that might not be the best idea. (or maybe only keying on that...) In my case, since all my game tokens represent characters, I might want the option to "scatter graphics that are drawings"  Additionally, you might want to filter out cards (well, have the option). With that patch to provide cover, I'm already thinking of how I might use this...  =D All in all, it's a really clever script!  Very well done!

Updated to provide cover now! I'm looking adding a function to check for partial cover (if the explosion would hit any part of the token and not just the center). It's actually pretty easy to do with just PathMath and VecMath libraries. I just used getTransformInfo, tupleToPoint and segmentIntersection from the PathMath object. Also as a note, having scattering active just makes it so that the script randomizes motion a little. Without it on, affected tokens will always move perfectly away and two tokens starting in the same spot will arrive at the same spot. With scattering active, the angle of deflection is altered, as well as the distance moved.

Ah, good to know!

Just incase there is a person who wants to try the 1-click version, the current version installed through 1-click requires the addition of an extra script (Path Math), and will stop working if you change any of the settings from the script library page. First, you need to install the PathMath script to your game through 1-click if you are choosing to use KABOOM. I just misspelled it on my end so it's not automatically added when you added KABOOM. Second, if you do click any of the buttons, or change the explosion ratio, you can fix the problem by resetting KABOOM's internal state with the chat command. !KABOOM --reset I have already submitted a fix to Roll20, which will hopefully render this issue invalid in 3 weeks. This has been fixed, 1-click installs are working properly and don't require anything extra.

This is quite a fun script! Glad to see that you've exposed a function to use it programmatically too. This will be fun to integrate into It's A Trap as a new trap property. :) Also, congratulations on your shiny new API Scripter tag.

Thanks! Your Path Math library made implementing Dynamic Lighting interactions nice and simple. Right now I'm adding a @{target|token_id} functionality for non-GMs to access the script! EDIT: The macro functionality is in version 1.2! It will be available through 1-click install in about 3 weeks.

Big KABOOMs require big VFX explosions. KABOOM now scales the size of explosions to the effect's strength. !KABOOM 40 will create an explosion of radius ~40 feet (scaling with the page's scale number). Implosion effects now delay token movement by roughly 1 second. The VFX finishes and then tokens are moved. Regular explosions still move tokens as the VFX is shown. Explosions with large radii but low pushing power are represented by large explosions with less particles. I may add a ratio number to Global config in case people don't like such large explosions.

Another exposed function! KABOOM.getExplosionVFX(colour, radius, sparcity) If you want to create size scaled explosion VFX like KABOOM does, there is a function that returns a custom VFX object based on the colour specified, the radius of the effect and a sparcity value. @param1 - COLOUR Accepts a string or custom VFX object with a startColour attribute. You can pass the name of a built-in colour as well. @param2 - RADIUS Determines the radius of the explosion in units on the tabletop. A value of 3 will create an explosion that reaches 3 squares away from the center. Defaults to 2 (like the built-in explosion). @param3 - SPARCITY Determines how many particles are created by the effect. Values higher than 1 decrease the amount of particles spawned. Defaults to 1. To use the spawned VFX in your own scripts, just use: // For an burst of water, 60ft wide spawnFxWithDefinition(x, y, KABOOM.getExplosionVFX('water', 12), pageid)

Version 1.2 update - For API scripters For the API scripters who are interested in integrating KABOOM, the exposed KABOOM.NOW() function returns an array of affected objects sorted by distance from the explosion point, so you can use them with damage calculations, status updates and whatever else you want. [{ distance : 7.14929133568, data : Roll20Token1}, { distance : 10.3858909255, data : Roll20Token2}] // 'distance' is the distance the token started from the explosion point. // If the token was in the square next to the explosion and you have // the grid set to 5 feet per square, the returned value will be 5. // 'data' is the Roll20 graphic object that was moved. // You can do something like: _.each(KABOOM.NOW(trapAreaOfEffect, trapToken), (obj) => { if (obj.distance < maxDamageArea) { obj.data.set({ bar1_value: obj.data.get('bar1_value') - maxDamage }) } else { obj.data.set({ bar1_value: obj.data.get('bar1_value') - minDamage }) } }