[Script] DLTool - A Dynamic Lighting Control Panel and Troubleshooter

Dynamic Lighting Tool I originally titled this script DLTool, but once I sent it to One Click decided that " Dynamic Lighting Tool " was a more descriptive term for people looking through the dropdown list. Look for it there under that name. "DLTool" is still a shorthand way of referring to it. DLTool is a script that performs a host of Dynamic Lighting tasks. It allows you to change most Dynamic Lighting settings on tokens and pages in real time, without needing to call up dialog boxes. It also analyzes many common Dynamic Lighting issues and suggests solutions. Code Available on One-Click install Video Tutorial by the illustrious Nick Olivo! Features: A full report of all current relevant Dynamic Lighting information on the current page and the selected token. A "Why can't this token see?" button that performs a detailed analysis of the selected token and tries to pinpoint what the problem might be. A list of things to check manually that cannot be handled by mod scripts. Preset buttons for common lighting solutions. Identifies controllers and represented sheet (if any) of selected token. Extensive hover text over most labels and settings with explanations and tips. If the checkLightLevel script is installed (Auto-installed by One Click, or get it here ), it will inform you of whether the token has light shining on it and how much. Dependencies: Token Mod (available from One Click). This is used for setting token values. There are many idiosyncrasies in the Mod system for tokens, and the Aaron has already done the hard work of accounting for them. checkLightLevel (by Oosh,  soon in One Click) DLTool will install these as dependencies, along with any of their own dependencies, if installed from One Click. Command: !dltool or !dltool --report For sub-reports (will show only the relevant: !dltool --vision !dltool --light !dltool --page Report Screen "Why can't this token see?" Function Goes through list of common issues and reports on each, as well as suggesting solutions. Each test is color coded. Green = No problem. Amber = Caution. This may give problems in some circumstances. Example. Token has no controller. This is only a problem if it is not a GM NPC, but might be a problem if it is intended for player use. Red = Problem that will likely prevent this token from using Dynamic Lighting. Updates: Page Plus There is now a "Page Plus" option that controls some page settings that are tangential to Dynamic Lighting, such as controlling the grid settings. For example, a common procedure in setting up lighting is to divide the grid into 8ths, so you can snap the lines to just inside the normal intersection, allowing players to see part of the wall. There are now preset buttons for that, as well as buttons for controlling grid color and opacity, page background color, grid type, diagonal measure and more. To access these settings, press the little "+" button next to the page button in the footer. Fit Scale to Map The in-game instructions explain how to use this function: Often a map will have a printed scale that does not correspond to a grid setting. This is typically true of city and overland maps. To set the page scale to correspond to the printed scale, first use the Measurement Tool to measure the printed scale. You may need to hold down the alt/opt key to avoid snapping and get a precise measurement. Remember this number, then press the button below and enter that number into the dialog box. (click for animation) Color Picking: Anywhere you can set color ( token night vision, token light, grid color , or  page color ) already has a swatch box. Currently, you can click on the entry for any color definition and enter the new definition manually. With this new version, you can also click on any of the swatches to call up a color picker. The buttons on the color picker match the Roll20 pallet. You can try out multiple options very quickly. Need to find the perfect green for that ghost light? Click-click-click to find the perfect one. Where applicable, you can also control the opacity on this screen. (click for animation)

Animation of DLTool Report panel in use

Nice - I'm loving this.  BTW, had to find the code for the  checkLightLevel  mod, as it wasn't loading from One-Click.

I jumped the gun on that.  It's in a PR right now. Here's the current code if anyone needs it. Update: This is in One Click Installation.

How useful! Thanks Keith, another great script  mod!

Minor update: Improved the diagnostic wording and display. Added Directional Light and an arc indicator. Indicator is pretty simple. It displays the chosen arc to the nearest 90° increment. NOTE: This was further fixed. See this post .

You all amaze me, great job

Added code to allow tinting of light, and setting the light multiplier, along with hover text explanations of what each setting does. Improved the logic of light presets. Added more diagnostic testing Improved hover help text in many instances Included a screen to explain how to save a default token properly, so that your settings are preserved. Code in top post is updated.

Hi Keith, this script is amazing. I'm wondering if there is a way to produce a limited report for example just the output on Token Vision or Token Light or Dynamic Lighting

Heh, I just sent a pull request to send it to One Click with the next merge. I can put that in the next version, though.

FFR said: Hi Keith, this script is amazing. I'm wondering if there is a way to produce a limited report for example just the output on Token Vision or Token Light or Dynamic Lighting They are behind on merging into the repo, so I was able to get in the change. Code is updated in link at top, and will be in one-click soon. !dltool --report|vision !dltool --report|light !dltool --report|page All report only that section. Clicking a button on that report will respect your last choice and keep it on just that section until you run  !dltool --report There are new buttons at the bottom to trigger these reports:

Keith, Thank you for doing this. Much appreciated

Thank you this Keith.

This is all really cool, Keith! Thanks for this. 

Excellent. I've been using this in our home game, where we have four players who each run their own campaigns. The feeling of satisfaction when they had a "blind" player and were able to diagnose and fix the problem almost instantly is indescribable.

Update: Much like the presets for light, there are now a handful of vision presets, allowing you to quickly set: Normal: Standard vision for humans and other characters without darkvision Darkvision 60ft: Standard darkvision for most characters with this trait 90: Many monsters have 90ft of darkvision. Example: Trolls or Night Hags 120: Enhanced darkvision used by races such as Drow or Duergar The buttons are set so that if you choose a darkvision preset and then turn vision or night vision off, the settings should be persistent. If you re-enable night vision, the darkvision settings for that character should be restored. Another benefit of this is that if a character has any of the standard visions, a green preset button should indicate a correct basic setting.

This is probably the final format for the report. I moved things around a little bit, partly to make room for the last few features, and partly to organize a little more clearly. To make more room, I deleted the "Gem of Brightness" lighting preset (it is identical to a hooded lantern or the daylight spell). I moved the less common features of lighting to a slightly offset subsection I added a field for the intensity of dim light ("low light brightness" is a little obtuse)  I bolded the Master Switch for each section I added and cleaned up more of the hover text for all of the buttons. (Not visible) Code is updated, and some day, there will come a merge and it will be in One Click.

Dynamic Lighting Tool is now in One Click. It will automatically install Token-Mod and checkLightLevel as dependencies, if not already installed.

And there was much rejoicing in the land, for all was as it should be.

It's a relief, mostly because of handling the dependencies, and their dependencies. Installing one script actually installs six.

Minor update merged today. The "Why can't my token see?" report has some improved logic and now contains numerous "fixit" buttons so you don't have to re-rerun the main report, but can fix the issue directly from the problem description.

The amazing Nick Olivo has just released a video tutorial for this script. Thanks, Nick!

This is awesome. I am having an error however. I have the following scripts installed:  DeathTracker, Aura/Tint HealthColors,  libInline,  SmartAoE,  Vector Math,  MatrixMath,  Path Math,  checkLightLevel,  TokenMod,  Dynamic Lighting Tool. I haven't been having any errors before using the DL tool. It works for a few clicks then stops. The error:  TypeError: Cannot read property 'get' of undefined TypeError: Cannot read property 'get' of undefined at apiscript.js:14450:129 at Array.forEach (<anonymous>) at apiscript.js:14449:49 at Array.forEach (<anonymous>) at apiscript.js:14412:22 at eval (eval at <anonymous> (/home/node/d20-api-server/api.js:168:1), <anonymous>:65:16) at Object.publish (eval at <anonymous> (/home/node/d20-api-server/api.js:168:1), <anonymous>:70:8) at /home/node/d20-api-server/api.js:1762: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)

Hi Amy Jordan! Hmm. Can you tell me which command you are running that causes the crash? Can you consistently cause the error? It looks like some script (certainly could be mine) is trying to get a value from a missing token id. Or perhaps a value that doesn't exist. If you would like to PM me an invite to your game and promote me to GM, I would be happy to investigate.

Okay I've been testing it out for 10 minutes now and seemingly there are no errors. I just disabled everything then turned it all back on and it's cooperating for now. Thanks for the offer of help!

If the error crops up again, you might get some good info from installing ScriptInfo and then feeding the line from the error to it, in this case that would be: !ScriptInfo 14450 That can help pinpoint the line where the error is encountered.

timmaugh said: If the error crops up again, you might get some good info from installing ScriptInfo and then feeding the line from the error to it, in this case that would be: !ScriptInfo 14450 That can help pinpoint the line where the error is encountered. And if you installed through One Click, you can always find the latest code here . 

I just experienced the exact same error condition. Disabling then re-enabling all scripts had no effect. I removed the DLTool script that I installed from one-click and replaced it with your latest script on github and the problem went away. This happened with two different games. Is it possible that the script on the one-click hasn't been updated? keithcurtis said: And if you installed through One Click, you can always find the latest code here . 

Hmm. I can't reproduce on a new campaign, with only installing DLTool and its dependencies (through One Click). Can you give me some specific repro steps? If I can pin down the line that is being reported and match it to an event, that would help figure out what might be going on. The one from One-Click should always be the latest. Nevertheless, I just ran a text compare between the one at the top level of the repro, and the one in the latest version folder, and they read as identical.

I wish I would have copied a screen shot of the error that I got. I believe it was the exact one that Amy Jordan copied in their post earlier. TypeError: Cannot read property 'get' of undefined TypeError: Cannot read property 'get' of undefined at apiscript.js:14450:129 at Array.forEach (<anonymous>) at apiscript.js:14449:49 at Array.forEach (<anonymous>) at apiscript.js:14412:22 at eval (eval at <anonymous> (/home/node/d20-api-server/api.js:168:1), <anonymous>:65:16) at Object.publish (eval at <anonymous> (/home/node/d20-api-server/api.js:168:1), <anonymous>:70:8) at /home/node/d20-api-server/api.js:1762: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) I first installed it though one-click along with its dependant scripts. I then opened the game and ran !dltools without selecting a token and it displayed the map's lighting settings. I then by mistake selected a token that wasn't assigned to a character sheet and gotr no response in the chat window but saw that API HeartBeat showed that the sandbox had stopped; when I opened a new tab to check the sandbox I saw the error message that I believe was the same as the one posted above. I then restarted the sandbox, went back to the game and tried again, but this time making sure to select a token attached to a character. Again, no response, and the same error in the sandbox window. I then restarted the game and tried again: with no token selected, I get the map settings report. with a token selected I got nothing but the error messsage. I get out of the game, disable all mods, re-enable all mods, restart the game ... same results. I get back out of the game, remove DL Tools and  checkLightLevel;  get your script from github and add it, then also manualy add  checkLightLevel. I restart the game and all is good. I go back to my other game and run through the same routine and got the same results. Here are my currently installed MODs:

And if you install ScriptInfo and run that error line? Can you share the result? !scriptinfo 14450 Make sure the line stays the same after you install ScriptInfo by generating the error again.

I can repeat the error by selecting a token that is not associated to a character or NPC sheet. I have installed Scriptinfo. I'm not completely sure what you mean by "run that error line" Here is the screen shot:

Sorry if that wasn't clear: I meant for you to run the line that I shared right after that statement (though now I'll change it to match the number in that screenshot): !scriptinfo 14617 Run that through chat and see what it tells you about that line.

I don't think it's checkLightLevel - it does a heap of iteration but there's no anonymous forEach in there - mostly 'for' loops to allow early breaking. Haven't looked in this thread for a while - Keith, that infographic from 3 weeks back is amazing, and puts any and all documentation I've ever attempted to absolute shame. 10/10

Ah, OK. The output is " Line 14617 corresponds to line 412 in dltool." Line 412 is: label(`${caution}This token represents the character <b>${char.get("name")}</b>, but has no specified controller. Only the GM can use it for dynamic lighting vision, by pressing Cmd/Ctrl-L.`, `It does not represent a character sheet. If you are setting up a PC, be sure to assign the sheet to the token before saving this as the default token for the sheet. Saving as default should always be the last step. If this is meant to be an NPC it is fine as-is, but you may want to consider assigning control to the GM to avoid some transparency issues when using Exploration Mode.`))

Ah. That might indeed cause an error. I'll do some testing and see what I can turn up.

I've looked at the code, and I don't think that's the issue. That line number lies in the diagnosis section, not the report section, and specifically tests for data in the represents field before it runs that line.  Rick, if you'd like to shoot me an invite to a game with the issue and promote me to gm, I'd be happy to investigate and see what I can find out.

Link sent in DM Additional info: The problematic tokens seem to be ones that have been brought over when I've used transmogrifier to copy a map between games. Even of I've copied over the associated character sheet, DL Tools throws the error. If I delete the token and drag a new one to the VTT from the character sheet in the journal, DL Tools works again. If the token's character sheet already exists in the game that I'm copying the map into, DL Tools also fails unless I delete the token thatr was imported with the map and replace it with one that's dragged from the character sheet in the journal. keithcurtis said: I've looked at the code, and I don't think that's the issue. That line number lies in the diagnosis section, not the report section, and specifically tests for data in the represents field before it runs that line.  Rick, if you'd like to shoot me an invite to a game with the issue and promote me to gm, I'd be happy to investigate and see what I can find out.

I'll hold off from joining for the moment, because that report gave me enough info to duplicate. It appears that the transmogrifier copies over the id that exists in a represents property, regardless of whether that character id exists in the game. I can't do anything about that behavior, I'm guessing that it is intended for repairing the link if the character is brought in later. However, I can try to test for it and escape if it does not exist.

OK, I'm going to hold off submitting this to the repro for the moment, but if you want to test, replace line 407: ((tokenData.get("represents")) ? with ((tokenData.get("represents") && typeof getObj('character', tokenData.get("represents")) !== "undefined") ? This basically tells the script that if the represents character can't be found, treat the token as generic.

Since I now know what (probably) causes the error, I can allow for it when I transmogrify maps with pre-positioned tokens. I hope you can find a way to detect the condition to prevent borking the sandbox; that thing is unstable enough :) Thanks for the patch! It worked like a charm. Let me know if you still need to join. keithcurtis said: I'll hold off from joining for the moment, because that report gave me enough info to duplicate. It appears that the transmogrifier copies over the id that exists in a represents property, regardless of whether that character id exists in the game. I can't do anything about that behavior, I'm guessing that it is intended for repairing the link if the character is brought in later. However, I can try to test for it and escape if it does not exist.

Don't worry, I don't think I need to join. Glad it's working!

I missed the merge deadline for today, but this should be fixed with the next pull.

Thanks for jumping on this so quickly!

Thanks for finding the issue!

Update: Fixed a bug where instead of setting Directional Light, the script was setting Field of View. This was repeated by the presets such as bullseye lantern. There is now a line for Field of View in the vision section, and a line for Directional Light in the Light section, and presets work accordingly. "Why Can't This Token See?" analysis has been updated to include an usual condition where all settings seem good to go, but the token cannot see because its Field of View has somehow been set to zero. I ran into that situation during a game, and it was NOT immediately obvious. Hopefully this will spare someone else the confusion. Also, The little gear icon next to a few entries has been enlarged to make them more obvious. Hovering over them will tell the user their purpose, but they are basically next to settings that the Mod script system sets poorly. I.e. They require you to open and close the settings panel manually in order to take effect. Finally (and this is not a change, but a discovery). The Mod system has properties for controlling Directional Light independently for both dim and bright light. This appears to be a placeholder, since it cannot be set through the token interface, and setting it with a script has no discernible effect. This would be an excellent solution to relieve the player claustrophobia caused by directional light by allowing a tiny bit of spillover in their immediate vicinity. If it is ever enabled, I will add the functionality to DL Tool.

I really like this script!! One change I'd like: the ability to change the color tint in the darkvision/nocturnal setting. 

I can include that. I haven't until now because I have found the implementation problematic. But I suppose enough people use it. I'll put it into the next release.

This will be in the next pull:

I can't seem to find the script in One Click... Edit: Found it! I was looking for "DLTool", but it is listed as "Dynamic Lighting Tool".

keithcurtis said: Update: Fixed a bug where instead of setting Directional Light, the script was setting Field of View. This was repeated by the presets such as bullseye lantern. There is now a line for Field of View in the vision section, and a line for Directional Light in the Light section, and presets work accordingly. "Why Can't This Token See?" analysis has been updated to include an usual condition where all settings seem good to go, but the token cannot see because its Field of View has somehow been set to zero. I ran into that situation during a game, and it was NOT immediately obvious. Hopefully this will spare someone else the confusion. Also, The little gear icon next to a few entries has been enlarged to make them more obvious. Hovering over them will tell the user their purpose, but they are basically next to settings that the Mod script system sets poorly. I.e. They require you to open and close the settings panel manually in order to take effect. Finally (and this is not a change, but a discovery). The Mod system has properties for controlling Directional Light independently for both dim and bright light. This appears to be a placeholder, since it cannot be set through the token interface, and setting it with a script has no discernible effect. This would be an excellent solution to relieve the player claustrophobia caused by directional light by allowing a tiny bit of spillover in their immediate vicinity. If it is ever enabled, I will add the functionality to DL Tool. I was meddling with a macro of yours for token-mod that seems to be the basis of this mod and I encountered the same issue there that I find here: directional lighting doestn't seem to be working. Whenever I use the bullseye preset or try to set an arc for the light it simply outputs a standard circle around the token. I tried many combinations of configurations, but none worked. The vision field of view works fine, though. Edit: I figured it out, the little gear next to the setting and the need to open the token's settings manually, for it to take effect. Sorry.