[Script] Light-Crumb Trail (to let players see where they've been with dynamic lighting on)

It seems the help command message is broken as this is what is shown when it is used. This is shown in normal chat and not whispered. : <div style="border: 1">/w gm LightCrumb is a script to create light-trails behind character tokens.This allows them to see where they have been on maps with dynamic lighting enabled.To use it, make a token action macro with the text: !LightCrumb selected|token_id.Register a token to leave light trails with: !LightCrumb-register selected|token_idYou can also enter !LightCrumb-clear to remove all LightCrumb tokensNote: clearing will also remove token names from the list of registered trailmakers. Register them again if you need them to be active.</div> I noticed that I had to refresh my browser after I registered my token so that the torches would show their light. They are dropping fine behind the character token but I was originally puzzled by the lack of light from them till I refreshed my browser then they were working.

Also in the above highlighted code text ... there seems to be missing { and } in the command instructions as well (that's how I missed them earlier in this thread).

plexsoup said: Stephen, any chance of adding an intersect (or raycast) function to your vector math library? I need to check to see if the vector defined by [currentLocation, lastLightCrumbLocation] instersects with any nearby paths on the dynamic lighting layer. If they intersect, then I know light is occluded, so I should drop a new LightCrumb. Actually, I do have some segment intersection algorithms available in my Path Math script, including classes for shapes and testing intersections between them in the latest version (not yet merged into the upstream repo):&nbsp; <a href="https://github.com/Cazra/roll20-api-scripts/blob/t" rel="nofollow">https://github.com/Cazra/roll20-api-scripts/blob/t</a>... All this is done by using Path Math to convert paths into a series of segments, then testing intersections between those segments using // The segments' points should be homogeneous coordinates. E.g. [x,y,1] let intersection = PathMath.segmentIntersection(segment1, segment2); let pointOfIntersection = intersection[0]; let segment1IntersectionScalar = intersection[1]; // This will be in the range of [0,1]. let segment2IntersectionScalar = intersection[2]; // This will also be in the range of [0,1]. // intersection will be undefined if segment1 and segment2 are parallel or don't intersect. Path Math currently doesn't have ray casting, but it would be trivial to use code from PathMath.segmentIntersection to implement that. Path Math has the additional requirement of Matrix Math. plexsoup said: @Stephen L: That sounds pretty good! I see you even have a distance function. So, forgive my ignorance... How do I include functions from another script? Also, how do I make sure people have both scripts installed? To include functions from another script, just use whatever global variables they expose. For example, to use Vector Math, just call something like let v = VecMath.sub(pt2, pt1); To make sure that other people have both scripts installed, you can set up Vector Math as a dependency for your script in its script.json file if you are putting it in the Roll20 repository. When the script is installed through the One-Click installer, it will automatically install those dependencies. If you plan on releasing this as a gist, just add a note to users to install the dependency scripts.

This sounds really promising if you make it all work as expected. I'd love to see it automatically drop based on distance from last drop. Not sure how you're doing automatic drop now. I'd also love to see a configuration option to make the light dim, not bright. Fog of War should be dim like Warcraft 3 imo.

plexsoup said: (I'm not comfortable doing 1-click installs yet. Plus, it's not my script. It's The Aaron's script with a few small modifications.) I'm totally fine with you pushing this into 1-click, particularly since you noted it was based on one of mine in it. =D &nbsp;It's sufficiently different from the original and super useful to the community. &nbsp;Cheers!

Scott C. said: plexsoup said: And what's this thing for? (At the end of the primary function.) }()); (I get why there's a curly brace and a round bracket, but why the extra pair of brackets? ) I'm not a great programmer knowledge wise, but I believe this is so that you can return your functions from the self-invoking function LightCrumb. I fully expect a certain Arcane Scriptomancer to hop in here and give a better explanation. Sorry for the delay. &nbsp;=D It looks like you've got this all mostly figured out, but here's a review anyway: var script = script || (function(){ var func = /* some function */ /* stuff */ return { thing: func }; })(); There's several things going on here. &nbsp;First is the Singleton aspect of the module pattern: var script = script || &lt; definition logic &gt; ; Because of the unique properties of javascript's || (or) operator, along with the standard short circuiting logic in most procedural programming languages, the practical upshot of this code is "If there's something named script already, assign that to my variable script , otherwise assign the results of executing this &lt; definition logic &gt; " Second is that &lt; definition logic &gt; : (function() { /* stuff */ }()); This is called an IIFE (iffy): Immediately-Invoked Function Expression. &nbsp;Normally, you call a defined function by using it's name followed by the parameter list (): &nbsp; foo(); You'd normally see a function like that defined as either: function foo(){ /* stuff */ }; // or var foo = function(){ /* stuff */ }; In this case, we're using an anonymous function by just providing the definition of the function instead of a name for the function (everything in Javascript is an object, functions are not different): function(){ /* stuff */ }; You'd normally see these anonymous functions passed as call backs ( like what is passed to the on() function: &nbsp;on('ready, &lt;anonymous function&gt; ); ), but in this case, we're just taking that function and executing it in place by appending the parameter list (): (function(){ /* stuff */ }) (); Parenthesis are necessary to properly parse the expression. &nbsp;The () can either be inside them or outside them: (function(){ /* stuff */ } () ); The convention I follow puts them inside as a notation that this is an IIFE. So, the result of this &lt; definition logic &gt; is an object that is used as the external interface to the real script. &nbsp;The most important concept here is that the object that is returned can reference everything inside of the function that created it. &nbsp;This is called a Closure , and is perhaps one of the hardest concepts to understand in Javascript. The practical upshot of all of this is that your script's code is safely nestled away inside a private space (the closure, the insides of the IIFE) and can't conflict with other code. &nbsp;It can have a variable named bob, instead of script_bob. &nbsp;It can define a function named test(), instead of script_test(), etc. &nbsp;It makes it very clean and easy to deal with. &nbsp;You never end up with having a function in one script that is accidentally being used in another, or a global variable, etc. Hope that helps!

Wow! Thanks for the fantastic explanation Aaron! It's super helpful.

Actually, I do have some segment intersection algorithms available in my Path Math script Sweet! The future is bright! (Or dim, depending on how you like your options.)

New version available: 0.42 (Mostly just fixes to the help text. Also added a simple gui with clicky&nbsp;buttons.) Get it while it's hot. <a href="https://gist.github.com/plexsoup/64852540504101b52" rel="nofollow">https://gist.github.com/plexsoup/64852540504101b52</a>... Let me know if there's any problems. Now I need to add a deregister command, so you can remove one token from the list of active trailmarkers without removing them all. Then, some options for light radius and dimness, frequency of drops, etc.

Any configuration for how the light of the dropped torches looks? Or adding it to the dynamic lightning layer instead of the map layer?

@Kryx: Not yet.. light configuration is on my list. It never occurred to me to put the torches on the dynamic lighting layer. Would that mess with the controlled-by aspect?

I just put the LIGHT_RADIUS and DIM_RADIUS near the top of the script, so you can change them in the script. I still plan to add a dynamic in-game way to change the settings, but this'll work for now. updated&nbsp; the gist

The most optimal way to determine the radius is to read the radius of the player. For example my warlock would leave a radius of 120 because of his devil's sight, while another character would leave a radius of 60. You can get these values by reading from the token.

Did you mean to have the help message whisper to everyone as soon as they entered the game? If not then it is doing so.

Kryx said: Any configuration for how the light of the dropped torches looks? Or adding it to the dynamic lightning layer instead of the map layer? Adding the light to the DL layer would not allow sight unfortunately.

Scott C. said: Adding the light to the DL layer would not allow sight unfortunately. Unfortunate. Then map layer is fine.

Kryx said: Scott C. said: Adding the light to the DL layer would not allow sight unfortunately. Unfortunate. Then map layer is fine. Unfortunately, the object layer is the only one that allows sight. I ran into the same problem with my Share vision script.

Scott C. said: Unfortunately, the object layer is the only one that allows sight. I ran into the same problem with my Share vision script. Ah, the items I add to other layers (map or dynamic lighting, I forget) give light but not vision.. true. Well that's unfortunate!

Kryx said: Scott C. said: Unfortunately, the object layer is the only one that allows sight. I ran into the same problem with my Share vision script. Ah, the items I add to other layers (map or dynamic lighting, I forget) give light but not vision.. true. Well that's unfortunate! Yep, it really is. There's lots of cool things we could do if we could utilize more layers.

Pat S. said: Did you mean to have the help message whisper to everyone as soon as they entered the game? If not then it is doing so. No. I'll have to look into that. Thanks!

I've updated the script again.&nbsp; Get it on the gist . New feature: Image selection: Torch, Transparent, Beacon Video in Action Some of the parameters are near the top of the script, so you can change them if they don't suit you. var LIGHT_RADIUS = 20; var DIM_RADIUS = 0; var DROP_DISTANCE = 200; // in pixels = grid units * 70 (that's probably right?) Question for scriptomancers: What's the best way to expose a lot of configuration options in-game? Can I make text entry fields so they can type in distances? I could tell GMs to make macros with queries like: !LightCrumb-setOptions ?{distance|200}. But that seems kinda clunky. It's almost like each api script needs it's own character sheet for parameters.

I really love the changes! &nbsp;And the addition of the image options is fantastic. &nbsp;I'd use the transparent image, but for me the image is still dropping on top of the player token such that I'm grabbing the transparent lit image when I am intending to grab the player token image to move them.

DM Robzer said: for me the image is still dropping on top of the player token I can't explain that. In the dropLightCrumb function, around line 499, we send the new object "toBack". Do you have any other scripts running which might be forcing your character token to the front? It's possible there's some lag between lightcrumb creation and going "toBack". Maybe that small window of time is when we get the lightCrumb instead of the character token? (Confirmation: At 4m17s in the video, I grabbed a torch that was still on top of the character token. <a href="https://www.youtube.com/watch?v=h52-ZbVfbd4&t=4m15" rel="nofollow">https://www.youtube.com/watch?v=h52-ZbVfbd4&t=4m15</a>... ) Anyone else have any ideas? I could probably tweak it.. get the direction of token travel, then drop the torch some offset away from the character token. Thanks for testing the script!

Kryx said: The most optimal way to determine the radius is to read the radius of the player. For example my warlock would leave a radius of 120 because of his devil's sight, while another character would leave a radius of 60. You can get these values by reading from the token Was this something you'd consider implementing?

Kryx said: Kryx said: The most optimal way to determine the radius is to read the radius of the player. For example my warlock would leave a radius of 120 because of his devil's sight, while another character would leave a radius of 60. You can get these values by reading from the token Was this something you'd consider implementing? For sure. Sorry I didn't respond earlier. That seems like a good way to get a light radius for the lightcrumbs. I still have to refactor things so individual characters can have ownership of their own light trails. That'll solve the split-party problem. Trying to wrap my head around how that's going to work.

I will test for the lag idea and get back with you. &nbsp;That very well may be the case.

plexsoup said: I've updated the script again.&nbsp; Get it on the gist . New feature: Image selection: Torch, Transparent, Beacon Video in Action Some of the parameters are near the top of the script, so you can change them if they don't suit you. var LIGHT_RADIUS = 20; var DIM_RADIUS = 0; var DROP_DISTANCE = 200; // in pixels = grid units * 70 (that's probably right?) Question for scriptomancers: What's the best way to expose a lot of configuration options in-game? Can I make text entry fields so they can type in distances? I could tell GMs to make macros with queries like: !LightCrumb-setOptions ?{distance|200}. But that seems kinda clunky. It's almost like each api script needs it's own character sheet for parameters. That's pretty much exactly how I do it, but I hide the ugliness inside a button (note that standard &lt;a&gt;&lt;/a&gt; links from HTML become API buttons, allowing you to give them better style.). &nbsp;Here's one of the functions from GroupInitiative: &nbsp; &nbsp; getConfigOption_DieSize = function() { &nbsp; &nbsp; &nbsp; &nbsp; return '&lt;div&gt;'+ &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; 'Initiative Die size is currently &lt;b&gt;'+ &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; state.GroupInitiative.config.dieSize+ &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; '&lt;/b&gt; '+ &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; '&lt;a href="!group-init-config --set-die-size|?{Number of sides the initiative die has:|'+state.GroupInitiative.config.dieSize+'}"&gt;'+ &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; 'Set Die Size'+ &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; '&lt;/a&gt;'+ &nbsp; &nbsp; &nbsp; &nbsp; '&lt;/div&gt;'; &nbsp; &nbsp; }, That button shows up in the Help and clicking it pops up a roll query prompt for what size of Die to roll, defaulting to the current setting. &nbsp;When they finish the entry at the prompt, it executes the !group-init-config command passing it the name of the parameter and the new value, which is then parsed later like this (some argument parsing has already occurred): &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; case 'set-max-decimal': &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; if(opt[0].match(/^\d+$/)) { &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;state.GroupInitiative.config.maxDecimal=parseInt(opt[0],10); &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; } else { &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; omsg='&lt;div&gt;&lt;b&gt;Error:&lt;/b&gt; Not a valid decimal count: '+opt[0]+'&lt;/div&gt;'; &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; sendChat('','/w gm '+ &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; '&lt;div style="border: 1px solid black; background-color: white; padding: 3px 3px;"&gt;'+ &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; omsg+ &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; getConfigOption_MaxDecimal()+ &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; '&lt;/div&gt;' &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; break; You can also use the drop down box version of roll queries to give a fixed number of options, or provide multiple buttons (like you have for the image) if that makes more sense (and then style the selected one differently). For allowing selection of their own image for the light nodes, you could use the selected token's image when they click the button. &nbsp;Just be sure to check that it's in the User Library (see:&nbsp; <a href="https://wiki.roll20.net/API:Cookbook#getCleanImgsr" rel="nofollow">https://wiki.roll20.net/API:Cookbook#getCleanImgsr</a>... )

plexsoup said: DM Robzer said: for me the image is still dropping on top of the player token I can't explain that. In the dropLightCrumb function, around line 499, we send the new object "toBack". Do you have any other scripts running which might be forcing your character token to the front? It's possible there's some lag between lightcrumb creation and going "toBack". Maybe that small window of time is when we get the lightCrumb instead of the character token? (Confirmation: At 4m17s in the video, I grabbed a torch that was still on top of the character token. <a href="https://www.youtube.com/watch?v=h52-ZbVfbd4&t=4m15" rel="nofollow">https://www.youtube.com/watch?v=h52-ZbVfbd4&t=4m15</a>... ) Anyone else have any ideas? I could probably tweak it.. get the direction of token travel, then drop the torch some offset away from the character token. Thanks for testing the script! toBack an toFront have some serious race conditions issues. (See:&nbsp; <a href="https://app.roll20.net/forum/post/1986741/slug%7D" rel="nofollow">https://app.roll20.net/forum/post/1986741/slug%7D</a>) Fixing that is a little complicated. You could try doing: _.defer(()=&gt;toBack(currentLightCrumb)); or _.delay(()=&gt;toBack(currentLightCrumb),50); But those might not work all the time. Another option would be to only create the light node the next time the current token is moved. &nbsp;You'd have to setup some queues and an event handler on('graphic:change',...), etc. &nbsp;That might be more complicated than you want to get into. Yet another option would be to create the light node slightly offset from the token, probably back along the .get('lastmove') path a token's width. I can help with the more complicated options if you need it, just let me know.

The slight offset idea sounds interesting.

Thanks for all your help Aaron and Scott. One more question: &nbsp;&nbsp; Is it safe to routinely pull values from state.LightCrumb or should I store them in a local variable and only check state occasionally?

It's safe to use them directly from state. The state object is just like any other object in the global scope. The only thing that makes it special is 1) it is copied into the FireBase DB on an interval (every few seconds?) and 2) it is copied out of the FireBase DB on API startup.&nbsp; Because of the persisting to FireBase, it has a maximum size (2MB) so you don't want to go crazy with what you've got in there (That is, don't store static data, just dynamic data. &nbsp;Don't store transient dynamic data like you would in a cache.). Also, you can only store simple data (numbers, strings, arrays, objects (of the associative map variety)), storing functions and complex objects (class instances, Roll20 objects) will appear to work but will be garbage on restart of the API.&nbsp;

Awesome. Thanks!

I would stick to storing Roll20 object IDs to avoid using up the state, especially since the state as a whole is limited 2mb. That means that lightCrumb and any other scripts all use the same 2mb storage space. It took me several scripts to get this through my head.

Thanks. That's good to know. So far I've just got config options and a list of token_ids (those who are registered as active mappers).

Minor change today: added config options for light_radius, light_dimradius, and drop_distance. <a href="https://gist.github.com/plexsoup/64852540504101b52" rel="nofollow">https://gist.github.com/plexsoup/64852540504101b52</a>... Next steps: Offset the dropped crumbs so they sit on top of PC Tokens Make option for trails unique to each character, only visible to the character which laid them.

DM Robzer said: I believe it may have to do with the Player Ribbon. &nbsp;When I have the Player Ribbon on my sign in screen map page and just move to the dungeon map as the GM, LightCrumb does not work for me. &nbsp;But when I move the Player Ribbon over to the dungeon map and still operate as the GM, then the LightCrumb functions are working. Some of the other API scripts that I have, experience the same limitation. Only working when I run the API command on the page that the Player Ribbon is on. &nbsp;I'm thinking of the Waypoint Patrol script. &nbsp;I don't know if that is an API limitation or something that can be fixed in the code. Thanks Robzer for providing feedback and testing for Plexsoup. I look forward to trying this Lightcrumb API.

I think I've sorted the player ribbon problem. The lightcrumbs should go to the token's page instead of the player's page. Let me know if it's still not working.

Another update: &nbsp;Offsets are in. <a href="https://gist.github.com/plexsoup/64852540504101b52" rel="nofollow">https://gist.github.com/plexsoup/64852540504101b52</a>... Let me know if you have any problems. Video

Thank you very much. I just woke up and saw you did an update so I did a quick run through. I have a little bit of feedback. Your script is awesome. Did you mean to have the script whisper as soon as someone entered the room? I noticed that as soon as I entered the room I received the help whisper with the lightcrumb button displayed. Might want to place a how to instruction for disabling that feature at the top in your commented out area. Did you mean for the offset distance to ignore the dynamic light settings? I have my settings enabled to do the following: enforce line of sight and restrict movement. If the offset distance is set to a distance greater than a square (70 pixels), it will ignore the walls sometimes and place the lightcrumb token outside the wall. Other than those few things, I don't have any more feedback at the moment.

Pat S. said: Did you mean for the offset distance to ignore the dynamic light settings? I have my settings enabled to do the following: enforce line of sight and restrict movement. If the offset distance is set to a distance greater than a square (70 pixels), it will ignore the walls sometimes and place the lightcrumb token outside the wall. Offset is inherently flawed unless this behavior can be prevented 100% of the time which I expect would be very difficult to do pragmatically. I don't see the need for offset. I expect a solution to always placing the light source below a token is the better long term strategy.

I figured that but it was still worth noting.

Probably placing the light when the token is moved a significant distance for the point where it requested the drop would work better.&nbsp;

The Aaron said: Probably placing the light when the token is moved a significant distance for the point where it requested the drop would work better.&nbsp; Indeed a better choice. How do you handle it with the floaty image for things like turnmarker? Is that token on the map layer?

Yes. I can see those problems now. Aaron, that's a good idea about placing the light on departure instead of on arrival. I'll work on that tomorrow. I'll just switch it to use last location instead of current location. In the meantime, clicking the config button and setting the offset distance to 0 should make it behave like before. I also just realized that I should lock non-gms out of the config settings. Regarding the whisper, I'll try and change it so it only whispers to the gm when the gm joins the game (and not the other players). I can definitely add a button to disable that feature.

I should also mention that the offset uses the token's movement vectors, so it should land behind the pc along their path of movement. If they're trying to go around corners, you could ask them to use the space bar to set a waypoint at the turn.

plexsoup said: I should also mention that the offset uses the token's movement vectors, so it should land behind the pc along their path of movement. If they're trying to go around corners, you could ask them to use the space bar to set a waypoint at the turn. This can't be guaranteed though. For example I, as the GM, now have to move creatures around every corner instead of dragging them straight across a map when I do such an action

You're absolutely right Kryx. I'll work on a better fix. Creatures? I didn't expect anyone to use lightcrumb on NPCs. Can you tell me more about how you're intending to use it? Maybe there's a creative use case I hadn't thought of.

plexsoup said: Creatures? I didn't expect anyone to use lightcrumb on NPCs. Can you tell me more about how you're intending to use it? Maybe there's a creative use case I hadn't thought of. I have no intention of using it on creatures, just PCs. Replace "creatures" with "PCs" above. Apologies. Once you've implemented using the vision of the current token I'll be sure to give it a whirl.

Kryx said: The Aaron said: Probably placing the light when the token is moved a significant distance for the point where it requested the drop would work better.&nbsp; Indeed a better choice. How do you handle it with the floaty image for things like turnmarker? Is that token on the map layer? I think I just toBack(marker); or _.defer(()=&gt;toBack(marker)); &nbsp;However, in my case, the marker has been long since created so it's implicit insertion into the stacking won't be conflicting with the explicit reordering from toBack(). Still, I think using a _.delay(()=&gt;toBack(marker), 100); should allow it to work correctly for Plexsoup.. I've not tried it out yet though.

plexsoup said: Regarding the whisper, I'll try and change it so it only whispers to the gm when the gm joins the game (and not the other players). I can definitely add a button to disable that feature. You could whisper something like: LightCrumb v1.0.3 -- [Help](!light-crumb --help)