Anybody wanna beta test a [default token] Spawning script, with toys?

So this started out as a simple script to help automate KeithCurtis' cool trick using rollable table tokens and !token-mod to generate spell effects, illustrated&nbsp; here , but kind of expanded from there. I first looked at King's excellent !Summon script, but it seemed like it did not support setting sides of rollable table tokens or some other features I was looking for, so I thought it would be a fun project. Kind of went down a rabbit hole with options, but it was a fun learning experience. Thought I would share in case others found a use for it or had any suggestions for new or existing features, or just had general feedback like "...but why?". Many thanks to TheAaron, timmaugh, GiGs, and others who helped me through a few technical roadblocks along the way! I'm sure it is a hot mess as I was learning stuff as I went, but it seems to work and was fun so I'm ok with that. Concept Like !Summon, !Spawn can be used for spell effects, monster summoning, cataclysmic terrain changes, or any similar type application.&nbsp; The general idea is to automatically spawn the default token for a given "character" with various options for token qty, location/arrangement, and certain token properties such as size, side (for rollable table tokens), light emission, and "represents" property. In addition, I wanted to be able to automatically call a character "Ability" after the spawn event. This last part has a few caveats, which I will address later in the post.&nbsp; Example: Click image to see Animated gif of a baddy raising 8 minions/mooks (appearing as random sides of a rollable table token) around each of two targets: &nbsp; Version History --v0.2&nbsp; fixes bug that prevented non rollable table tokens from spawning correctly --v0.3&nbsp; provides&nbsp; UDL support &nbsp;for the --light command. See updated command notes for differences in use of this command between LDL &amp; UDL --v0.4&nbsp; supports floating point&nbsp; (decimal) --size parameters &nbsp; for partial square token sizes --v0.5 &nbsp;added limited support for&nbsp; triggering FX&nbsp; at spawn origin points. See updated command notes. Currently no custom FX or those that require directional input. --v0.6 &nbsp;now compatible with the TheAaron's&nbsp; TokenNameNumber&nbsp; script (v0.5.12 or later). Spawned tokens whose default token has the text %%NUMBERED%% somewhere in the name will have a sequential number appended to their name. --v0.7 &nbsp;added new placement option&nbsp;&nbsp; --placement|cross # &nbsp;, which distributes spawned tokens similar to "burst,", but in a vertical &amp; horizontal reticle arrangement. # is radius (in squares) of the innermost spawned tokens relative to the origin token(s). --v0.8 &nbsp;added ability to override the token bar values.&nbsp; --bar1| &lt;current&gt; / &lt;max&gt; . Max is optional. If command is used, then the corresponding&nbsp;bar "link" will be removed, if present. Values for current &amp; max can be formulas using attributes and/or queries.&nbsp; e.g. --bar1| [[ @{charName|constitution}+10*?{Spell Level?|1} ]] --v0.9 added new command --expand| #,#&nbsp; , which causes the token to spawn first as a point, and then expand to full size based on user configurable number of frames and delay between frames (determining frame rate). --v0.10&nbsp; bug fix for certain cases where the default token does not have layer information. Now explicitly sets the spawn layer to that of the origin token(s). Side benefit: can now spawn on non-object layers (e.g. GM layer). Get the code here: <a href="https://github.com/djmoorehead/roll20-api-scripts/blob/master/Spawn%20Default%20Token/SpawnDefaultToken.js" rel="nofollow">https://github.com/djmoorehead/roll20-api-scripts/blob/master/Spawn%20Default%20Token/SpawnDefaultToken.js</a> Instructions Case 1: Selected token is the basis for spawn origin To use, select one or more tokens on the map, and call the script with at minimum the name of the "character" to summon. The following will simply spawn 1 of the default character tokens in the center of each selected token. !Spawn --name|charName Case 2: Target token is the basis for spawn origin Initial token selection is still required (as it is used for some defaults), but you can optionally cause the tokens to spawn at targeted token(s), with a little trickery. Roll20 has a standing bug that if both selected and target tokens are passed to an api script, the selected tokens are not retained. To get around this, after the initial call, the script will generate a chat button to prompt for a number of targets and will call itself again with the now complete set of information. &nbsp;!Spawn --name|charName --targets|2 A&nbsp; complete description of commands &nbsp;is included below. Note: I put &lt; &gt; around each of the parameters for readability. Don't include &lt; &gt; for actual use. ! Spawn {{ -- name | &lt; charName &gt; //(REQUIRED) name of the character whose target we want to spawn -- targets | &lt; # &gt; //Destination override. Instead of using selected token(s) as origin, use target token(s) -- qty | &lt; # &gt; // DEFAULT = 1 . How many tokens to spawn at each origin point. MAX = 20 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;//supports hardcoded and rollable table inline rolls such as [[ 1d6 ]] and [[ 1t[tableName] ]] -- offset | &lt; #,# &gt;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; //X,Y pos or neg shift in position of the spawn origin point(s) relative to the origin token(s), in number of SQUARES &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;//DEFAULT = 0,0 // (NOTE: a POSITIVE Y offset means LOWER on the map) --placement| &lt; option &gt; //How to arrange the tokens relative to the origin point (+ offset). Options are: //' stack ' : (DEFAULT) All tokens will be stacked on top of each other //' row ' : A horizontal row of tokens //' column , col ' : A vertical column of tokens //' surround ' : A clockwise spiral placement around origin token, starting at top (NOTE: any supplied offset will be ignored) //' grid #' : A square grid with "#" tokens per row. Raster left to right //' burst #' : An expanding diagonal distribution of tokens starting "#" squares from the 4 origin token corners. Large qty will form an "X" pattern // 'cross #' = "evenly" distributed vert/horiz cross pattern, starting directly above origin by # squares. Large qty will form a "+" pattern -- size | &lt; #,# &gt;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;// DEFAULT = 1,1 (X,Y) - How many SQUARES wide and tall are the spawned tokens? -- side | &lt; # or rand &gt;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;// DEFAULT = 1 . Sets the side of a rollable table token. &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;// # : Sets the side of all spawned tokens to "#" &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;// 'rand,random' : Each spawned token will be set to a random side -- order | &lt; option &gt;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; //The z-order of the token. (NOTE: a recent Roll20 "feature" will always put character tokens with sight above those without, so YMMV.) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;// toFront,front,top,above &nbsp;&nbsp;: Spawn token moved to front &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;// toBack,back,bottom,below : Spawn token moved to back -- light | &lt; #,# &gt;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;//Set light radius that all players can see. // For Legacy Dynamic Lighting (LDL): &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; //First # is the total radius of the light (light_radius)&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; //Second # is the start of dim light (light_dimradius) (so: 10,5 will be 10 ft of total light, with dim radius starting at 5ft) // For Updated Dynamic Lighting (UDL): //First # is the radius of bright light (bright_light_distance) //Second # is the additional radius of dim light (so: 10,5 will be 10ft of bright light + 5ft of dim light) -- mook | &lt; yes/no &gt;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;// DEFAULT = false (the "represents" characteristic of the token is removed so changes to one linked attribute, e.g. hp, will not propagate to other associated tokens. &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;//If set to true, linked attributes will affect all tokens associated with that sheet -- force | &lt; yes/no &gt;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // DEFAULT = false . The origin point is by default relative to the geometric center of the origin token &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;//Origin tokens of larger than 1x1 may spawn tokens in between squares, which may be strange depending on the specific case &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;//Set to true in order to force the token to spawn in a full square -- sheet | &lt; charName2 &gt;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // DEFAULT = selected character . The character sheet in which to look for the supplied ability &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;//useful if the ability exists on a "macro mule", etc. -- ability | &lt; abilityName &gt; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;//The ability to trigger after spawning occurs. With caveats as described below --fx| &lt; type-color &gt; //Trigger FX at each origin point. //Supported types are: bomb,bubbling,burn,burst,explode,glow,missile,nova,splatter //Supported colors are: acid,blood,charm,death,fire,frost,holy,magic,slime,smoke,water --bar1| &lt; currentVal/optionalMax &gt; //overrides the token's bar1 current and max values. Max is optional. If overridden, bar1_link will be removed --bar2| &lt; currentVal/optionalMax &gt; //overrides the token's bar2 current and max values. Max is optional. If overridden, bar2_link will be removed --bar3| &lt; currentVal/optionalMax &gt; //overrides the token's bar3 current and max values. Max is optional. If overridden, bar3_link will be removed -- expand| &lt; #frames, delay &gt; //Animates the token during spawn. Expands from size = 0 to max size //#frames: how many frames the expansion animation will use. Start with something like 20 //delay: how many milliseconds between triggering each frame? Start with something like 50. Any less than 30 may appear instant }} The --placement option is the trickiest one to describe, so here is a reference chart to show how --placement and --offset relate to each other for multiple tokens. Note how the --offset command is ignored for the --placement|surround option. Here is a completely unrealistic example from a game mechanics standpoint, spawning 1d4+1 Dancing Lights or Flaming Spheres in a burst 1 pattern originating three squares below a target token, then triggering the "SpellTemplate" ability on the "Yelric" character sheet. !Spawn supports multi-line commands using the double bracket syntax. Also, will support case insensitive search and allows extra spaces between commands, parameters and delimiting characters ("--", "|", and ","), so the following will still work: !Spawn {{ --naMe | GenericSpellAoE --targeTs |1 --qty| [[ 1d4 + 1 ]] --offset | 0 , 3 --placement| buRst 1 -- size|1,1 --side| ?{Spell?|Dancing Lights,7 |Flaming Sphere,2} --order | toFront --light| 10,-5 --force|yes --sheet|YeLriC --ability|SpellteMplAte }} Caveats/Known Issues 1) Like with any other scripts that affect images, Roll20 limits api access to only images found in the user's personal art library . Annoying. So, if you have purchased Marketplace content, you will have to go through the arduous process of getting those images into your "My Library". Select token, press Z, right-click, save image locally, then re-upload to Roll20. 2) Also not currently accessible by the api are: Bar position &amp; bar styles . So, no compact bottom overlapping bars for your spawned mooks until Roll20 allows that to happen. 3) The Ability triggered after spawning is currently pretty temperamental. This is irritating because it was one of the main features I was looking for. The following seem to cause problems: &nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp; a) When the ability contains a query, things break. &nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp; b) When the ability is whispered, it just gets ignored (?!). I don't fully understand this. I have a cheesy workaround that kinda works but is not yet implemented, as it forces the whisper to the player that made the api call. This probably would be ok for 99% of cases, but I'd like it to be more generic. There is a forum thread&nbsp; here &nbsp;that discusses the issue. &nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp; c) If the ability calls another ability or macro either directly or via chat buttons, things break. Chat buttons will be created, but will fail when clicked &nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp; NOTE: If anybody wants to wade through any of these Ability issues, it is found at the very bottom of the processCommands function. Search for the comment " automatic trigger of a supplied ability " to jump directly to that portion of the code. I think I went overkill on the error handling, so I haven't encountered anything that will crash the sandbox (yet) :) That's about it for now. This post is long enough, so thanks for getting this far! I can include some other examples in later posts.

This example spawns four dancing lights with a rollable table token (GenericSpellAoE) in a burst two squares from the selected character. The token is set to emit dim light as per the spell. The character casting the spell has darkvision with a light multiplier of two, in case anybody is counting squares :) !Spawn {{ --name| GenericSpellAoE --qty| 4 --placement| burst 2 --offset| 0,0 --force| yes --size| 1,1 --side| 7 --order | toFront --light| 10,-5 }} Click for animated gif: This example casts a Flaming Sphere adjacent to a target, using our GenericSpellAoE rollable table token. We are triggering the FlamingSphereDam ability from the GenericSpellAoE character sheet (the --sheet command overrides the default selected character search location). The ability automatically rolls the damage for the spell, using a 5E template. Note that higher level casting options currently aren't used, due to the "query within ability" caveat described above. It would be nice to figure this out in the future. !Spawn {{ --name| GenericSpellAoE --targets| 1 --force| yes --offset| 1,0 --size| 1,1 --side| 2 --order | toFront --light| 40,20 --sheet| GenericSpellAoE --ability| FlamingSphereDam }} This example is for casting a fireball with our GenericSpellAoE rollable table token. In this case, we don't want to automatically set the token size and side. Instead, it just spawns a bullseye as the spell origin point, and calls a chat menu that uses token-mod to set the token properties, potentially with hilarious results if the player didn't place it correctly. The fireball damage is run directly from the GenericSpellAoE token action button, so it can handle higher level casting. !Spawn {{ --name|GenericSpellAoE --qty|1 --offset|1,0 --size|1,1 --ability|SpellTemplate }} EDIT -- here's the SpellTemplate ability used in the example: &amp;{template:npcatk} {{attack=1}} {{name=Spell Templates}} {{rname=rname}} {{rnamec=rnamec}} {{r1=}} {{description=[Revert](!token-mod --set currentside|1 !token-mod --set width|70 height|70 light_radius|0 light_dimradius|0 !token-mod --order tofront) [Flaming Sphere](!token-mod --set currentside|2 !token-mod --set width|70 height|70 light_radius|40 light_dimradius|20 !token-mod --order tofront) [Silence](!token-mod --set currentside|3 !token-mod --set width|630 height|630 light_radius|0 light_dimradius|0 !token-mod --order toback) [Darkness](!token-mod --set currentside|4 !token-mod --set width|490 height|490 light_radius|0 light_dimradius|0 !token-mod --order toback) [Fireball](!token-mod --set currentside|5 !token-mod --set width|630 height|630 light_radius|80 light_dimradius|20 !token-mod --order toBack) [Spiritual Wpn](!token-mod --set currentside|6 !token-mod --set width|70 height|70 light_radius|0 light_dimradius|0 !token-mod --order toFront) [Dancing Lights](!token-mod --set currentside|7 !token-mod --set width|70 height|70 light_radius|10 light_dimradius|-5 !token-mod --order toFront) [Animate Objects](!token-mod --set currentside|8 !token-mod --set width|70 height|70 light_radius|0 light_dimradius|0 !token-mod --order toFront) }} Here's another one, used in conjunction with another of my scripts (DLDark) to cast a cloudkill that heavily obscures <a href="https://app.roll20.net/forum/post/8908015/magical-darkness-script-via-dynamic-lighting-layer/?pageforid=9157163#post-9157163" rel="nofollow">https://app.roll20.net/forum/post/8908015/magical-darkness-script-via-dynamic-lighting-layer/?pageforid=9157163#post-9157163</a>

That's a heck of an impressive script!

Yeah, definitely really neat!

Is the github link viewable for people? It's my first time using github and I just want to make sure it is available for public and I don't have to change some settings or anything. Also, I updated the example post to show another option and re-ordered properly so they are sequential in terms of what tokens are where.

Yup!

Nice script! Now I'm actually kind of curious. Is there any specific reason why you have to have a selected token for the script to function? Couldn't you have a "source" nullcheck (which I believe is the selected token) to get the source value from the targeted token (so source = target), something like: let sourceToken (!selectedToken) ? targetToken : selectedToken (I haven't understood the code in its entirety, and I know very little about JS, so forgive me if this has been addressed) So basically, even though the ability is "targetted", the script would use each token and itself as both the source and the target. Maybe I'm overthinking stuff, who knows.

Thanks for the feedback, Juan! Handling selected vs targeted is something I went back and forth about. One or the other is necessary to determine the origin(s) of the spawned tokens, and if a post-spawn ability is called, then identifying a character sheet is required (as there may be multiple abilities with the same name on different character sheets). I suppose I could do some more input validation to see if there is/are selected token(s), then check to make sure that, if there aren't, then --target is included in the list of commands. Then, if --ability is denoted and no selection, ensure that --sheet is also in the command line! Could be wrong, but I don't think there would be too many situations where the "target" would be the character sheet that would contain the ability to call. "Target" requires an extra click step so it's always easier to use selected if you can. However, it needed to be available to players, so targeting was also necessary. I figured it was pretty likely for a player to have their token selected already anyway due to either movement or to view token actions to call the script in the first place, etc. so it didn't seem like too much of burden to require it. All told, it just seemed easier to implement and less confusing to use (fewer rules to remember) to require a selection. However, this hasn't gotten much actual gameplay, though, so the jury is still out in terms of how things really flow. That's another reason why I put this out there to have people try it out. Thanks again for the feedback, I'll definitely keep your comments in mind as I get some more experience using this in an actual game!&nbsp;&nbsp; &nbsp;

Hi David, What am I doing wrong? When trying to use the script, I get this error message every time ( (From SpawnAPI): &nbsp;Unhandled exception: Cannot read property 'split' of undefined)

Can you post an example of the syntax that is generating the error?

!Spawn --name|Fireball I have a character sheet with the image of the Fireball as the default token. It doesn't work for any of the sheets I've created (not just Fireball). Oddly, however, if I try&nbsp; !Spawn --name|Strahd von Zarovich It works. Strahd von Zarovich comes from the default tokens from the Roll20 module (which I purchased).

Hmm, not much going on there with such a basic call. Since Strahd works, it sounds like an issue with how the token is set up. I've tried a few permutations, but can't seem to recreate the error on my system. I've sent you a PM.

We found the source of the error that Firebat was experiencing. Turned out to be a bug, after all. Late in my pre-release testing, I had changed the way I was handling the --sides command, and it looks like it broke the script for non-rollable table tokens, even if the sides command wasn't being used. I had never tested again with a "normal" token after that change (sigh). It's going to take me a bit to update the github, but in the meantime it can be manually patched by replacing lines 160-180 with the following: &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;//Check for rollable table token and side selection if (baseObj.hasOwnProperty('sides')) { sidesArr=baseObj["sides"].split('|'); if ( (currentSideNew !== -999) &amp;&amp; (sidesArr[0] !== '') ) { //check for random side if ( isNaN(currentSideNew) ) { currentSideNew = randomInteger(sidesArr.length) - 1; // Setting to random side. currentSide is 1-based for user } else { currentSideNew = parseInt(currentSideNew) - 1; //currentSide is 1-based for user } //set the current side (wtih data validation for the requested side) if ( (currentSideNew &gt; 0) || (currentSideNew &lt;= sidesArr.length-1) ) { newSideImg = getCleanImgsrc(sidesArr[currentSideNew]); //URL of the image baseObj["currentSide"] = currentSideNew; baseObj["imgsrc"] = newSideImg; } else { sendChat('SpawnAPI',`/w "${who}" `+ 'Error: Requested index of currentSide is invalid'); return retVal; } } } Thanks, Firebat! &nbsp;

Thank you for your help!

This may be a dumb question, but how did you get your Dancing Lights to appear smaller? I'm not using a rollable table, just a macro: !Spawn {{ &nbsp; --name|Dancing Lights &nbsp; --targets|1 &nbsp; --qty|[[4]] &nbsp; --offset|0,0 &nbsp; --placement|burst 1 &nbsp; --size|1,1 &nbsp; --order|tofront &nbsp; --light|10,-5 &nbsp; --force|yes }} And it works, I get four orbs around the token, but they each take up a full square. I've tried adjusting the size to 0.5, but they come out so minuscule they are effectively invisible. Side note, mine don't illuminate until I move them, I'm using UDL right now, would that matter?

Geoffrey, first of all, thanks for testing out the script! My base dancing lights image has transparent padding around the "ball", so a 1x1 token creates a roughly half square ball in the center of the square. I edit my images using Gimp, a free photoshop-esque application. If you don't want to mess with that yourself, I can post the one I'm using, or if you want to post yours to this thread, I can edit yours for you pretty easily. I'm on my phone now, but can get to it when I'm back on my pc.&nbsp; Currently the script only supports Legacy DL, but I will look into what I need to do to support UDL, as well. I'm personally waiting for all the bugs to get worked out of UDL before I switch over. I'm surprised the light shows up at all when you move the tokens. Does your default token have light emission already set up on it? And if so, when you drag it out from the journal, does the light immediately come on? Also, if the default token has UDL light emission, I'm curious what happens if you omit the --light command for !Spawn? I wonder if the VTT doesn't like having both LDL and UDL properties active on the same token.&nbsp; Edit- also, you don't need the online roll brackets around your qty parameter. Just --qty|4 should work :)&nbsp;

I can fiddle with the token myself. So when I drag the token from the journal, it is the default size I have set (about 25% of a square), and it automatically lights up, Dynamic Light settings are on (Low Light, 10'). When I !spawn the lights, they don't light up until they're moved, but the dynamic lighting low light is flipped on, though there's no radius set, but they still radiate 10', when I delete the "--light" portion they're still lit up, so it may just be the token that defaults to lit.

That definitely sounds weird. I'll have to look into that UDL support. Hopefully I can get something out soon.&nbsp;

Ok, v0.3 (found in above github link) was updated for UDL support! Seems to work for the several examples I tried, though UDL is new to me. Note there is one strange glitch that I can't seem to get around. Setting emitted low light for UDL works on the map/token, but the actual low light field in the token menu does not get updated. Really weird, since the bright light field updates fine and they are assigned the same way. &lt;shrugs&gt; Like I said, the token should still emit the desired low light, so not sure how critical this is. Note that the --light command parameters are used differently for LDL &amp; UDL, as described below. (also edited in original post above). -- light | &lt; #,# &gt;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;//Set light radius that all players can see. // For Legacy Dynamic Lighting (LDL): &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;//First # is the total radius of the light (light_radius)&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; //Second # is the start of dim light (light_dimradius) (so: 10,5 will be 10 ft of total light, with dim radius starting at 5ft) // For Updated Dynamic Lighting (UDL): //First # is the radius of bright light (bright_light_distance) //Second # is the additional radius of dim light (so: 10,5 will be 10ft of bright light + 5ft of dim light) Geoffrey, your UDL Dancing Lights macro would be the following: !Spawn {{ &nbsp; --name|Dancing Lights &nbsp; --targets|1 &nbsp; --qty|4 &nbsp; --offset|0,0 &nbsp; --placement|burst 1 &nbsp; --size|1,1 &nbsp; --order|tofront &nbsp; --light|0,10 &nbsp; --force|yes }} Note that if using UDL, if you are in Ctrl-L mode to view as that token when the cript is run, the UDL light emission will not actually emit until the token is moved. If in normal GM view or if logged in as a player, the light appears to emit instantaneously when the token is spawned. At least for me using Windows 10 &amp; Chrome with no extensions. LDL does not seem to have this limitation, and the light immediately emits even if in Ctrl-L mode.

Update v0.4 now supports decimal values for the --size command, allowing tokens to be sized to partial squares.&nbsp;

New update works like a champ, both the resize and UDL support. I will put this into practice for my Sunday game!

Great, thanks for the testing and the ideas for updates!&nbsp;

Added limited support for triggering FX at each spawn origin point, through the --fx command --fx|type-color Continuing our Dancing Lights example from before: &nbsp;!Spawn {{ --name| GenericSpellAoE --qty| 4 --placement| burst 2 --offset| 0,0 --force| yes --size| 1,1 --side| 7 --order | toFront --light| 10,-5 --fx| burn-charm }} Click for animated gif: &nbsp;

Just started testing this out, it's got so many great features! The --light parameter works fine in LDL, but doesn't seem to do anything to UDL. The command I'm testing is this !Spawn {{ --name| Dancing Lights --qty| 2 --placement| surround --force| yes --size| 1,1 --side| rand --order| toFront --light| 20,20 }} The default token has the light set to 20,20 already, but the spawned tokens end up with 20,0 no matter what I use in the --light parameter. Removing --light altogether still gives me tokens with 20,0. Trying when the default token has no light settings doesn't toggle those settings on, so the token emits no light, even with --light| 20,20 in the command.

Also, any plans to include compatibility with TokenNameNumber?

Thanks for trying it out, Persephone! Hmm, a couple things to check. First, you are using v0.3 or later (unlikely to be the case, but just checking :)) . The page is set up for UDL only, with no LDL settings simultaneously. Same for the token, making sure it doesn't have some LDL properties set in addition to UDL. Then,&nbsp; when you say it always has 20,0 light when 20,20 is called for, have you checked to see if the actual light radius is 40ft (count the squares) ? The difference between dim and bright light is kinda hard to see in UDL when both are on, IMO. I also mentioned in the edited original post that there is a slight glitch where the dim light field in the token property window doesn't get updated with the actual value, even when emitting properly. Still haven't figure that one out, but released anyway since it appeared to be "working" otherwise for me and some others. For the case where the --light command was not used (so the default token settings should be used) , did you happen to be looking through Ctrl-L on the token? For some reason with UDL, if in that viewing mode when spawned, you won't actually see the light until the token is moved. If logged in as player, or if not in Ctrl-L mode it should work immediately. If all that checks out but you are still having problems, if you want at some point for me to look at it, you can invite me to your game and promote me to GM and I can troubleshoot further if you want. It's 2:30am for me right now and I'm knackered, but we can set up a time sometime tomorrow after I've gotten some sleep. Just PM me if you want to go that route. This UDL business is new to me and seems a bit quirky, so I really appreciate the feedback. Let me know what you find, and thanks again for the testing!&nbsp; Edit - just saw the bit about Token NameNumber. I hadn't thought about it, but I can look into it to see what it would take.&nbsp;

Retested this on a new page and made sure only UDL was activated. Omitting the --light command uses the default token light settings, using the command overrides the light settings appropriately. The light emissions on the map are correct, even though the spawned tokens' settings show dim light at 0 no matter what, like you said. So looks like it's behaving as expected, the 0 dim light was all that was throwing me off I guess! I currently use a version of !Summon that's compatible with TokenNameNumber. The Aaron modified it here: <a href="https://app.roll20.net/forum/permalink/5335498/" rel="nofollow">https://app.roll20.net/forum/permalink/5335498/</a>

Good to hear, Persephone! I had just hacked out a TokenNameNumber mod, but I'll take a look at the one-off from theAaron after my game this afternoon

Spawn now supports TheAaron's TokenNameNumber script! Thanks for sharing the one-off for !Summon, Persephone. I didn't realize Aaron had made a global function available for other scripts to call, so that allows for a much cleaner solution than the TokenNameNumber "simulator" that I had written previously. Note: TokenNameNumber v0.5.12 or later is required for it to work. Since I'm sure most people have this installed through the one-click, don't think this should be a major issue. I also did a quick check, and it didn't seem like the order of installation affected the compatibility, unlike some dedicated utility scripts.&nbsp; Click for animated gif example of the two scripts playing nicely. Updated the github in the original post.

I'm glad I was able to help! Would it be much trouble to add one more placement mode, similar to burst, but placing the tokens in a horizontal/vertical crosshair pattern rather than diagonal?

Ok, that one was surprisingly tricky given all the combinations of origin token sizes, aspect ratios, and optional forcing to full squares or not, but v0.7 has added a new placement option: --placement| cross # This placement arranges the spawned tokens in an expanding vertical &amp; horizontal " + " pattern, as shown below. The usual behavior for offset &amp; origin token sizes still applies. The # parameter is the distance of the innermost spawned tokens (in squares) from the origin token(s).&nbsp; Below is the pattern for --placement|cross 1 for a 1x1 token. The github and documentation in the original post have been updated.

Thanks for finding a way to implement that! I'm surprised it was so tricky compared to the burst placement, I would've guessed it to be more simple. This is a big help tho since I'm running Pathfinder, where diagonals are measured longer. Effects like dancing lights would be outside their limits in a diagonal burst pattern.

Yeah, me too, haha! Anyway, I think it was a good addition, so thanks for the suggestion!&nbsp;

Just made an update to v0.8, after reading Adam T.'s forum post&nbsp; here &nbsp;regarding summoning creatures with variable hp &amp; ac. This version adds the ability to override the default token's bar values via&nbsp; --bar1| &lt;current&gt; / &lt;max&gt; . Max is optional. If command is used, then the corresponding&nbsp;bar "link" will be removed, if present. Values for current &amp; max can be formulas using attributes and/or queries.&nbsp; e.g. --bar1| [[ @{charName|constitution}+10*?{Spell Level?|1} ]] examples: --bar1| 5/5 --bar2| [[ @{charName|constitution}+10*?{Spell Level?|1} ]] / [[ @{charName|constitution}+10*?{Spell Level?|1} ]] --bar3|&nbsp;15ft walking, 50ft fly

Update v0.9 -- Animated spawning! Ported over some animation logic from my recent !radar script ( here ). Added the command "&nbsp; --expand| #,#&nbsp; ", an optional configurable animation option to have the spawned token(s) expand from their origin point to full size. Useful for magical effects (appearing from thin air!), explosions, expanding gas clouds, etc. Syntax --expand| &lt; #frames, delay &gt; //DEFAULT = 0,50. Animates the token during spawn. Expands from size = 0 to max size //#frames: how many frames the expansion animation will use. Start with something like 20 //delay: how many milliseconds between triggering each frame? Start with something like 50. Any less than 30 may appear instant e.g. --expand| 20,50 In the animated gif below, our heroes think they have the upper hand after surrounding a mad conjurer. Little do they know the table is about to be turned! Click image to play: Abilities used in this example: SummoningCircles !Spawn {{ --name| GenericSpellAoE --qty| 4 --placement| burst 3 --offset| 0,0 --size| 4,4 --side| 9 --order | toBack --light| 10,10 --expand| 30,50 }} SummonDemons !Spawn {{ --name| Balor --qty| 4 --placement| burst 3 --offset| 0,0 --size| 3,3 --order | toFront --fx| explode-death --expand| 15, 30 }}

That's amazing

So I LOVE this function, I am trying to get my head around how the heck to set it up. Obviusly this would be GREAT for all above GIFs which i would LOVE to use it for BUT also I have a player that is an Echo Knight and I think this would be a GREAT way, along with some sound effects to dipict the echo being summoned. I guess it would be similar to your summoning.&nbsp;

PosterBoiTellEM, yes I think this is a perfect application for the script!&nbsp;&nbsp; First, create a new character sheet named "Echo Knight", and assign permissions for the player. Give it the appropriate hp &amp; AC (you could also dynamically assign the bar2 value for AC via the script with a --bar2| [[14+ @{selected|pb}]] command, although note that this just overrides the bar value and breaks the link to AC from the character sheet, so this might not be good for you depending on if you have other macros that reference the AC of a target character. YMMV). Next, create a token for the Echo Knight. Make sure that the image you use for the token is in your personal art library and that you save the token you set up as the default token for the character (important!). Then, create a macro or ability called Echo-Knight and put something like the following in it. The first line is all you really need, though I would recommend including an offset since Roll20 has an annoying new "feature" that ignores z-order commands when PC-controlled tokens are involved. See note above about bar2 value vs AC. Also, sometimes there is server lag for the fx which can make things awkward. Again, this is just an example. !Spawn {{ --name| Echo Knight --offset| 1,0 --bar2| [[14 + @{selected|pb}]] --fx| bomb-smoke }} Since the Echo Knight just uses the PC's attack stats for everything, there is no need to do anything additional for that character sheet. For the sound fx, you can just add a line to the macro or ability as a separate line immediately before the !spawn call, using whatever script you would normally use.

FYI PosterBoi, a little off-topic for this thread, but relevant to you and other Echo Knights out there. I just happened to run across this script that swaps token positions, ala Benign Transposition. Useful for that sneaky Echo Knight class feature! I would put a call to it on your Manifested Echo character sheet as a token action ability. <a href="https://app.roll20.net/forum/post/6458744/script-to-swap-position-of-two-tokens-on-the-same-page/?pageforid=6458763#post-6458763" rel="nofollow">https://app.roll20.net/forum/post/6458744/script-to-swap-position-of-two-tokens-on-the-same-page/?pageforid=6458763#post-6458763</a> &nbsp;

Nice work on this David!

Good I found this thread! I stumbled upon the script in the API menu, but there was no info on how to use it there Few comments: The description/instructions in the one-click menu contained no info on how to use it, or even the command-name The explanation of the API is hidden in the source code, and on a quick look at the code, isn't accessable in-game with any " !spawn --help " -command or similar. There is no link to this thread in the API menu or the sourcecode I'll submit a PR to update the API's description, so it mention the name of the command used for teh API ( !spawn ), and add a link to this thread so the APi becomes possible to use without having to search the web or look at sourcecode. Occasionally I'm trying to learn more about how APIs are made, and intend to figure out how a --help command can be added to scripts that don't otherwise have in-game instructions for how to use them, making APIs more accessible to the average user. When I figure out how to add a --help command to existing APIs, I'll make a PR to add one to SpawnDefaultToken , which shows the explanation of each command, gives an example, and&nbsp; links to this thread. (general thoughts on Roll20 APIs in general, not specifically targeted to you) One of my main annoyance when I started trying out different APIs was when some didn't even mention what the API's command name was, let alone any instructions or links to more info on how to use them. I'm somewhat familiar with JS in general, and have created sheetworkers on character sheets, but if I need to look at the sourcecode to figure out the commands for an API, it's pretty annoying for me, while for the average user makes it basically impossible to use the API if found through the API menu.

Thank you for bringing this to my attention, Andreas. Funny story, I didn't even realize my script was available on one-click! So so sorry, it was not my intention to have it there. I was just looking for feedback on the forums, and expected all traffic to come through this thread were all the documentation is. I was also under the impression that one-click required some kind of separate request. In hindsight, it appears that merely having it in the Roll20 repository also pushes it to the one-click menu. I wish there was a more clear description of how all this works, in layman's terms so mooks like me could easily navigate everything. I had never even heard of Github before this, and was just trying to follow along the instructions. Don't remember seeing anything about one-click. :( Anyway, it is obviously not ready to be there, as I made no effort to make it ready to be there. I should probably figure out how to remove it until it has the appropriate features that one would expect. Thanks again, and sorry that this caused you and potentially others any grief. EDIT - Looks like I have two other ones on there, too: DLDark and Radar. Sigh...

David M. said: Thank you for bringing this to my attention, Andreas. Funny story, I didn't even realize my script was available on one-click! In hindsight, it appears that merely having it in the Roll20 repository also pushes it to the one-click menu. Think Roll20 adds new API to the one-click by default if you submit them to the repo, similarity to how it's with the character sheets. Then my criticism was unfounded, since the one-click wasn't even anything you had to do with. I'm sorry for having jump to conclusions. wish there was a more clear description of how all this works, in layman's terms so mooks like me could easily navigate everything. Yeah think the github process in connection to character sheets is better documented, and the API stuff is indeed less documented by both Roll20 and the API community. It's competently understandable that this ended up happening, as similar things have been seen with the character sheet, even though that process have much more guides and things. Anyway, it is obviously not ready to be there, as I made no effort to make it ready to be there. I should probably figure out how to remove it until it has the appropriate features that one would expect. I wouldn't go as far as say that, but if we add disclaimers/warnings to the API descriptions, and direct link to the sourcecode so people can read the code comments you've made, it's more than enough. Of course if you insist, you should request them to be hidden from the one-click until later. But, considering I'm the first person who found your scripts in the one-click(in the couple of month they have been there) and then found you to pester about things, it should be a very small chance this would happen again. Especially if we update the descriptions with a warning that the author doesn't fully think they are ready, and shouldn't be contacted, or something. When I know enough about API stuff, how the github &amp; one-click are all connected, I'll write a Guide on the Roll20 Wiki what can be used, or expand the guide that is dealing with Char Sheet submission process

I created&nbsp; this thread &nbsp;to ask for help in describing the process for getting my documentation available in the script library. That sounds like a much quicker path than in-chat help, since I'm not really familiar with html formatting. Updating the wiki sounds really useful. Thanks again! EDIT - For documentation on the script library page, looks like I just add to the description field in the script.json file. I'll add something and make a pull request. Not sure if this will go through in time for this Tuesday's release, but fingers crossed!

The sheet updates have deadlines on Mondays, so would assume it's the same for API, so as long as you submit a PR to update descriptions within the next 13 hours, you should be good. The description uses markdown formatting, and you can look at examples from other APIs on how to fill them out. I'll leave this to you as you managed to respond before I took the time to do this, but can later see if I can help out with these things or later PRs. That sounds like a much quicker path than in-chat help, since I'm not really familiar with html formatting.&nbsp; Just having the help command output an hyperlink to more info would make things easier than having to navigate to the API oneclick or to the github sourcecode to find the help. It can always be expanded by someone else than you, to make the help command contain some info posted in the chat, or add/open a handout with the stuff.

David M. said: Funny story, I didn't even realize my script was available on one-click! So so sorry, it was not my intention to have it there.&nbsp; The only reason to post a script to the roll20 github is to get it in the one-click library - thats what that githib is for*. It's the same with sheets and the roll20 sheet repository - you only post there in the hope of getting it into the dropdown sheet list when making a new campaign. *There are plenty of reports that scripts don't always get added to one-click, but thats a failure in their process, and a separate issue.&nbsp;

Thanks for the confirmation, GiGs.&nbsp; I think this script has been tested enough to leave it in there, I just need to get some documentation on the api library page, in chat, and/or in a handout for the user.

UPDATE: Put in a pull request for adding documentation on the script library page. We'll see if it made the cut for this week. I used existing scripts as a template for markdown, but wasn't able to find a markdown simulator that seemed to like the Roll20 \r line breaks, bullet points, etc. Fingers crossed that it turns out legible. As a fallback, I added a link to the forum thread as an additional path toward documentation.

OK, so there is now documentation of sorts for the script on the one-click. It is semi-legible, but some of the formatting is a bit wonky and will need to be updated for the next round of one-click releases (like only has single dashes instead of double-dashes before optional commands, sigh). I did eventually find a Github-specific markdown test page that should help with that. Also appears there is an issue with it auto-collapsing multiple spaces that I'll have to figure out. But, there is also a working link to this forum thread at the top of the description, so hopefully that will serve as a stop-gap solution until I can get things prettied up. Thanks to all that chimed in regarding this! EDIT - the documentation in the api script library has been updated with more readable formatting as of 10/27/20. &nbsp;

You can use the Custom Sheet Sandbox to test the json file and how the markdown shows up.