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

Edit: I've updated the LightCrumb script on Gist (sorry it's not 1-click install yet).
https://gist.github.com/plexsoup/64852540504101b52...

(For newcomers, it's a script to leave a trail of torches behind characters, with control set to "all players". That way, they can see where they've been, even when dynamic light is turned on. No more sea of blackness. Video here)


It now accepts these macros:
!LightCrumb (show help)
!LightCrumb-status (show who's registered to leave an automatic light trail)
!LightCrumb-register @{selected|token_id} (register a new token as a trail mapper)
!LightCrumb @{selected|token_id} (drop a new lightcrumb)
!LightCrumb-clear (remove all the lightcrumbs and clear the register so no one's authorized to leave automatic trails)



Still To Do:

• Accept distance parameters for the automatic trails.
• Accept an option to limit trails to a certain number.. reuse the oldest ones.
• Implement better error checking on inputs. (Right now the script could break if the commands aren't exactly right.)
• Do some testing to check edge cases and errors.
• fix the problem where gm isn't always on player page
• add option to use dim light for torches, or a smaller radius
• offload math functions to VectorMath and PathMath
• implement light-occlusion detection (to detect dynamic light walls between current location and the last known lightcrumb)
• fix the help text. it's showing divs and not showing curly braces
• Implement 1 click installation.
• update !LightCrumb-register to drop a lightcrumb token right away
• add an option to use invisible tokens instead of dropped-torch tokens
• add more gui buttons, for when a token is already selected instead of target-clicking.
• consider an option to have the trails only visible to the player who dropped them. Then everyone would have to drop their own trails. Solves the split-party problem.

would it be cool if there was an option to have them burn out over time?

Whoops: I just read this info about the Mark script:


That means the light-crumb trails will disappear unless you also comment out (add // before the line) the reset() commands in the script.
All but the one under case "!mark-clear".

Designate someone to "mark the path" using the drawing tool, this needs to be someone who will not mess up your maps too much. If there are intelligent beings in there with your victims, um players, they can erase sections and change markings. I would use a color that is very similar to the one the players used, but not an exact match, the smarter players will catch on...

I've modified the script and posted it on Gist so you can copy/paste into your scripts without editing anything.
https://gist.github.com/plexsoup/64852540504101b52...
(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.)

Also, I've updated the video, so you can see it on a bigger dungeon:
https://youtu.be/iIZxO9NPN4g

For reference, the error message generated was: ReferenceError: LightCrumbImageURL is not defined

Oh dang. Sorry that didn't work. And here I thought I had it all figured out.

Anyone know what's wrong with LightCrumbImageURL in the script?

You're coding in strict mode which means you need to declare variables using "var" or "let".

Awesome! Thanks Scott. I've updated the script.

Nice mod to torch.  Very handy.  This cause much lag?

Not sure about the lag yet. I haven't tried it in an actual live game. Seemed ok in testing. I'd probably want to keep the extra light sources down to 20 or less.

Right now, someone has to click the macro button to place a lightcrumb, but I'm planning to modify the script so it automatically pops out a lightcrumb every 100' or so for the official trailmarking character.

Instead of a set distance of 100', why not just a set number of hex or squares or even allow the gm to set the variable. This would allow for a variable scale as I could use this in a hex crawl exploration that I'm tinkering with.

Very cool.  Feature thought:  Maybe after X amount of drops the oldest drop gets removed?  ;-)

Vince said:

Very cool.  Feature thought:  Maybe after X amount of drops the oldest drop gets removed?  ;-)

That would be nice but I would think that should be an optional feature to be enabled. I know with what I'm working on, a crumb drop light would have to remain pretty much pemenantly.

Definitley an option.

I don't know if I'm running into an issue because I also have Mark API installed, but here is the error message I'm getting now:

For reference, the error message generated was: TypeError: Cannot read property 'count' of undefined TypeError: Cannot read property 'count' of undefined at _.each._.each.ops.*./.+.ops.*./._.each.state.Roll20AM.playLists.(anonymous function).currentTrack._.some._.some._.each.msg.playerid.dropLightCrumb (apiscript.js:8603:28) at apiscript.js:8570:6 at Function._.each._.forEach (/home/node/d20-api-server/node_modules/underscore/underscore.js:153:9) at _.each._.each.ops.*./.+.ops.*./._.each.state.Roll20AM.playLists.(anonymous function).currentTrack._.some._.some._.each.msg.playerid.handleInput (apiscript.js:8569:7) at eval (eval at <anonymous> (/home/node/d20-api-server/api.js:144:34), <anonymous>:65:16) at Object.publish (eval at <anonymous> (/home/node/d20-api-server/api.js:144:34), <anonymous>:70:8) at /home/node/d20-api-server/api.js:1394:12 at /home/node/d20-api-server/node_modules/firebase/lib/firebase-node.js:93:560 at hc (/home/node/d20-api-server/node_modules/firebase/lib/firebase-node.js:39:147) at Kd (/home/node/d20-api-server/node_modules/firebase/lib/firebase-node.js:93:546)

Hmm. That's good to know. Thanks. I'll look into it.

I probably need to do better input checkung.

To help me troubleshoot it, are you sending it "!LightCrumb @{selected|token_id}" or "!LightCrumb@{target|token_id}" ?

 

DM Robzer said:

I don't know if I'm running into an issue because I also have Mark API installed, but here is the error message I'm getting now:

For reference, the error message generated was: TypeError: Cannot read property 'count' of undefined TypeError: Cannot read property 'count' of undefined at _.each._.each.ops.*./.+.ops.*./._.each.state.Roll20AM.playLists.(anonymous function).currentTrack._.some._.some._.each.msg.playerid.dropLightCrumb (apiscript.js:8603:28) at apiscript.js:8570:6 at Function._.each._.forEach (/home/node/d20-api-server/node_modules/underscore/underscore.js:153:9) at _.each._.each.ops.*./.+.ops.*./._.each.state.Roll20AM.playLists.(anonymous function).currentTrack._.some._.some._.each.msg.playerid.handleInput (apiscript.js:8569:7) at eval (eval at <anonymous> (/home/node/d20-api-server/api.js:144:34), <anonymous>:65:16) at Object.publish (eval at <anonymous> (/home/node/d20-api-server/api.js:144:34), <anonymous>:70:8) at /home/node/d20-api-server/api.js:1394:12 at /home/node/d20-api-server/node_modules/firebase/lib/firebase-node.js:93:560 at hc (/home/node/d20-api-server/node_modules/firebase/lib/firebase-node.js:39:147) at Kd (/home/node/d20-api-server/node_modules/firebase/lib/firebase-node.js:93:546)

Hi DM Robzer. Based on that error message it looks like you might be having an issue with my Roll20AM script actually, although I'll have to refresh my memory as I don't remember a count variable in there. It is weird that it is saying it has an issue in both scripts tho.

!LightCrumb @{selected|token_id}

I am now in the process of removing the Roll20AM and will reinstall this script and report back.  Thanks for the prompt replies!!

I have removed Roll20AM and reinstalled the LightCrump script.  I do have Mark installed as well during these last two attempts.  This is the error message:

TypeError: Cannot read property 'count' of undefined TypeError: Cannot read property 'count' of undefined at dropLightCrumb (apiscript.js:7475:28) at apiscript.js:7442:6 at Function._.each._.forEach (/home/node/d20-api-server/node_modules/underscore/underscore.js:153:9) at handleInput (apiscript.js:7441:7) at eval (eval at (/home/node/d20-api-server/api.js:144:34), :65:16) at Object.publish (eval at (/home/node/d20-api-server/api.js:144:34), :70:8) at /home/node/d20-api-server/api.js:1394:12 at /home/node/d20-api-server/node_modules/firebase/lib/firebase-node.js:93:560 at hc (/home/node/d20-api-server/node_modules/firebase/lib/firebase-node.js:39:147) at Kd (/home/node/d20-api-server/node_modules/firebase/lib/firebase-node.js:93:546)

Ah, realized what the problem is (at least in LightCrumb). Plex, you need to define the lightcrumb variable in the state. Right now it's seeing "state.LightCrumb.count=0" at line 74 and/or "count=++state.LightCrumb.count;" 197, but as far as the API knows, there isn't a state.LightCrumb defined.

Before this:
state.LightCrumb.count=0;

Or this:

count=++state.LightCrumb.count;



You need something like this:
state.LightCrumb = state.LightCrumb || {
	count:0
};

I'd recommend putting a checkInstall function in that confirms things like that are created. See pretty much any of Aaron's scripts for an example of it -- I completely copied my script architecture off of him.

EDIT: I'm pretty sure this was the problem, and it was saying there was an issue with Roll20AM due to some screwiness with not being able to find the LightCrumb object in the state (only a WAG though) because I've confirmed there is no variable named count in the Roll20AM script, inside state.Roll20AM or just in the code.

The macro I'm using is set up as a token action and is:    !LightCrumb @{selected|token_id}

Thanks for the script development work on this. I plan to try it. Will this be coming to the one-click API repository of Roll20?

That would be really cool if it does. Right now I don't know what type of dependencies it requires so I have not tried to install it yet.

Thanks for your help Scott and everyone!

I'd like to make it a 1-click install. But first I have to make the script better / more reliable. Right now it's still essentially:
Once I get it fixed, and especially when I can make it drop light-tokens automatically, then I'll start worrying about the 1-click process.

(I would love to get my API scripter badge, but I feel like I don't deserve it yet.)

Heh, I'm still not sure why I got a badge. It just appeared one day.

I think you need to allow the script to accept parameters.  You may not always want the light crumb to have the same pre-programmed values for light radii.

For instance, on an overland hexcrawl map, you may want it to have a small radius, so as to reveal only adjacent hexes (which may be in miles or other large units).  Then when you're indoors, you may want it to give torch-light radius or similar.

I could be wrong (Javascript is not a strong suit for me), but I only see a fixed configuration in the script, which means you'd actually need 2 different scripts to do that now in the same campaign.

Good idea Anthony! Thanks

I'm still trying to figure out the basic script architecture..  Can anyone explain the purpose of this statement at the end of the primary function?


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? )


Also: what happens when you include the logical or ( || ) in a variable assignment?

    state.LightCrumb = state.LightCrumb || { count:0 };

or

    var LightCrumb = LightCrumb || (function LightCrumbTrailMaker() {

Does it try one then try the other if the first fails?
Nevermind the last one: Found the answer... http://stackoverflow.com/questions/2100758/javascr...

plexsoup said:

return {
    RegisterEventHandlers: registerEventHandlers,
    CheckInstall: checkInstall,
    Reset: reset
};

This is how you can call these functions from outside of the script's namespace, particularly in your on("ready",...) section at the very end.

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.

For any other amateur coders paying attention, that little }()); dealie at the end is part of the "Javascript Module Pattern"

http://stackoverflow.com/questions/17776940/javasc...

From what I can tell, it basically ensures that a script is only instantiated once (like a singleton). Then that instance of the script continues to operate and serve up requests while it's listening for events.

Thanks for everyone's help.
Big update. Automatic light trails!

You still have to get it on the Gist

Let me know if you have any problems.
(It's not super well tested.)

Sounds like a handy script. Do you plan to publish it to the Roll20 scripts repository (and to the One-Click install library)?

Also, to shorten your script a little bit, you could leverage the Vector Math script (https://github.com/Roll20/roll20-api-scripts/tree/... to do your vector mathematics operations. It already handles adding and scaling vectors, getting the distance between points of arbitrary dimension, and more. (It is super well tested)

@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?

I updated the Gist with a bugfix. (top and left coordinates were reversed for some tokens, so reused light crumbs were dropping in the wrong place)

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.

I am no longer getting a error message when I install the script.  However I am not seeing any functionality.  I may be dense.  I select a player token and enter in the command !LightCrumb-register selected|token_id to register the token (no visual confirmation anything happened) and then I have a token action macro with the command line !LightCrumb selected|token_id and I see nothing.  Am I not using this properly?

Try
    !LightCrumb-register @{selected|token_id}

With the curly braces and the at sign

it works best if you make a macro and put it on the token bar

you can also do:

   !LightCrumb @{selected|token_id}
to drop a single torch

    !LightCrumb-clear
to remove all the torches

  !LightCrumb-status
to show which token_ids are registered to leave light trails

Good point about the lack of user feedback when registering a token. I need to improve that.

If I enter !LightCrumb-register @{selected|token_id} into chat without a token selected, I do get an error message in chat: 
"You attempted to use a roll command looking for the value of a selected token, but no tokens are selected."

If I select a token and then I enter !LightCrumb-register @{selected|token_id} into chat I see nothing (so I assume the token is registered properly).

Then I have a token macro set up that executes !LightCrumb @{selected|token_id} and I see nothing different.  I move the token and I see nothing different.  I run the token macro again and I see nothing different.

I am about three or four days into being a Pro subscriber and this is my first time working with API scripts, so I apologize if I am not using your script properly.  But I am still confused as to how to use this script.

No need to apologize. If it seems like it isn't working, it's my fault for making it either broken, or obtuse.

try putting your !LightCrumb-register @{selected|token_id} inside a token action macro

I have two token actions now ... the LightCrumb Register, and the LightCrumb.  Not seeing a difference at this point.  

Do I need to have a specific torch graphic in my art library or something?

I don't think you need a specific torch icon. But i could be wrong about that.

This is the link I used to grab your script ... https://gist.github.com/plexsoup/64852540504101b520b25f7c3fa84e5f

Also, I am signed in as the GM, not as a player.  Would this explain what I'm seeing?

YEP !!!  Sheeshhh.  I resigned in as a player and it looks like it is working for me.

Strange. I can't explain that.
It was working for me as player or gm

I'll have to do more troubleshooting.
Do you see the little torches appear when you move the token around?

Yes, the automatic drop is working very well now.  Another odd observance is now that I've signed back in as the GM, it seems to be working for me as a GM now.  That boggles my mind.

I believe it may have to do with the Player Ribbon.  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.  But when I move the Player Ribbon over to the dungeon map and still operate as the GM, then the LightCrumb functions are working.

Another thought .... when the torch icon drops, it drops on top of the registered token.  Because of this, when I go to grab the player token to move it, I am actually grabbing the torch first.  Is it possible to have the torch drop but "to the back" on the token layer?

That makes sense... i didn't account for the player ribbon adequately.
I still have lots to learn!

You are doing great!  You are Light(crumb) years ahead of me in scripting, for sure!

> when the torch icon drops, it drops on top of the registered token.

Weird. It was going to the back for me.
i'll have to investigate that tomorrow.

Thanks for testing it, and providing me with all the awesome feedback!