Roll20 uses cookies to improve your experience on our site. Cookies enable you to enjoy certain features, social sharing functionality, and tailor message and display ads to your interests on our site and others. They also help us understand how our site is being used. By continuing to use our site, you consent to our use of cookies. Update your cookie preferences .
×
Create a free account

[Script] UniversalVTTImporter -- Import .dd2vtt files to create Dynamic Lighting Lines and Lights!

June 14 (4 years ago)

Edited November 11 (3 years ago)
The Aaron
Roll20 Production Team
API Scripter
UniversalVTTImporter

Update v0.1.9 -- Fixed bug causing all portals to be windows! (Thanks Graham R.)

Update v0.1.8 -- Added support for Opaque Objects, Window Portals, Colored Lights  (Thanks Edward R.)

Many new configuration options in the help:

!uvtt --help


Create Open Portals is renamed to Open Portals Mode.  There are now 4 options rather than just on and off:


  • Movement Blocking Window will draw a line that blocks movement but not sight. (Default)
  • Movement Blocking Window with Glass creates the line as above, but also creates a glass window pane on the map layer.
  • GM Layer Line is the old "On" setting, and just draws the portal on the GM Layer instead of the DL layer, ready to move back and forth to open and close it.
  • None is the old "Off", and draws nothing at all.

Window Color sets the color for the Window Pane on the map layer, and the color of open portal lines on the GM or DL layer.

Window Width sets the width of the Window Pane on the map layer.  Open portal lines on the GM and DL layers get the Door Width.

Object Color sets the color that Opaque Objects are drawn in on the DL layer.

Object Width sets the width that Opaque Objects are drawn in on the DL layer.

Object Transparent sets if Opaque Objects should just block movement and not sight.

Note that you can now specify --no-objects to not use Opaque Objects at all:

!uvtt --no-objects

Light Color has been renamed to DL Layer Light Marker Color to better reflect what it is and remove confusion.

Use Light Color toggles if you want to use the colors specified for lights in the import file.  DungeonDraw can export a map with the lighting color applied to the map, or with the map unlit.  Here's a comparison of the same map exported with and without lighting, and using Roll20 Light Colors and without:


Unless you plan to move lights, or turn them on and off, you might chose to just export the color and not import the color, so that's why there's an option.

One minor quality of life change, UniversalVTTImporter will now automatically clear previously created objects when you run it again.  That makes it easy to try different configurations and then reimport all your maps when you have the setting you like.  To be clear, running:

!uvtt

on a map you've already imported will now be the same as running this was:

!uvtt --clear
!uvtt


The new code should show up in the 1-click on Tuesday, or you can get it now from my repo.

Update v0.1.4 -- Fixed a bug where changing the exported scale of a map would cause the alignment of the objects created to be incorrect. (Thanks Dudemic)

Update v0.1.3 -- New --clear command and configurations options. (Thanks JesseStephen C.)

Added --clear command that removes all the lines and lights created for graphic. 

Configuration options for Wall Width, Wall Color, Door Width, Door Color, Light Color (aura on the DL layer), and creating open portals (generally, windows) on the GM layer.  All configuration options are available in the help from:

!uvtt --help

or directly from:

!uvtt-config


Update v0.1.2 -- Added UDL support.  Note that if you are using UDL, the UDL gets toggled off and on causing the map to be revealed briefly.  This is a bug in the way UDL lights are supported with the API.  I've reported it and will fix it when a fix becomes available.  (Thanks Elias. Ö. S.Ben M. )

Update v0.1.1 -- Added trimming of non breaking spaces to fix FireFox use.  Created and documented companion website (http://roll20api.net/uvtti.html) for preprocessing file for easier use.  (Thanks RyexandraCasey D.Justin S.)


UniversalVTTImporter provides a way to setup Dynamic Lighting lines and Lights stored in Universal VTT format, ala Dungeondraft.

Commands

!uvtt [--help]
  • --help -- Displays this help

Import Process

The process for importing is pretty straight forward, but there are several steps, as follows:

  1. From your Universal VTT supporting mapping program, such as Dungeondraft, export your map as a .png or .jpg file. The API cannot create images from the Universal VTT, so you will need to upload it manually.
  2. Next export the Universal VTT version into a .dd2vtt file.
  3. Drop your map image file onto a page and scale it as desired.
  4. Open the properties by double clicking the image.
  5. Visit http://roll20api.net/uvtti.html and sanitize and copy your .dd2vtt contents.  Load the Universal VTT file in a text editor and copy the contents.
  6. Paste the contents into the GM Notes section of the map graphic and save changes.
  7. With the graphic selected, run !uvtt

Your map should now have dynamic lighting lines, lines for doors and windows, and light sources from the original.

View before:

Adding .dd2vtt contents to the GM Notes:

After selecting the graphic and running !uvtt: (Note: the red line is an open portal on the GM layer)

View of the DL Layer, showing created light sources (purple aura), walls (brown) and doors (red).



Next up I'll be adding commands to change the colors, selectively create open portals on the GM layer, clear the created walls, etc.  Let me know if you have other feature requests or any issues!  This should be in the 1-click on Tuesday.


Github: https://github.com/shdwjk/Roll20API/blob/master/UniversalVTTImporter/UniversalVTTImporter.js


If you use my scripts, want to contribute, and have the spare bucks to do so, go right ahead. However, please don't feel like you must contribute just to use them! I'd much rather have happy Roll20 users armed with my scripts than people not using them out of some sense of shame. Use them and be happy, completely guilt-free!
Disclaimer: This Patreon campaign is not affiliated with Roll20; as such, contributions are voluntary and Roll20 cannot provide support or refunds for contributions.
June 14 (4 years ago)
GiGs
Pro
Sheet Author
API Scripter

Very nice!

June 14 (4 years ago)
keithcurtis
Forum Champion
Marketplace Creator
API Scripter

Mister Clever!

This is super clever, amazing.

June 14 (4 years ago)

Edited June 14 (4 years ago)

So smart... and from now on, nobody can't complain there is no universal VTT importer. 
:) Oh Joy

And btw... to me this script is so educational. thank you

One question, anyone have a problem when pasting long strings of text that causes Roll20 to crash? I use Chrome, is it just a Chrome issue?

June 14 (4 years ago)

Edited June 15 (4 years ago)
The Aaron
Roll20 Production Team
API Scripter

I wondered if that would become an issued.  If you delete the line that starts with "image": and all the base64 stuff after it, it will drastically reduce the file size.  Warning: Be sure to remove the preceding comma (,) to maintain a valid JSON format. The API can't use that image data (and the script will remove it from the GMNotes if it's there).

June 14 (4 years ago)
The Aaron
Roll20 Production Team
API Scripter


Martijn S. said:

And btw... to me this script is so educational. thank you

Oh yeah?  You're welcome!


I use inkscape to compose maps out of assets and this gives the inspiration to add walls into the workflow. Probably its as easy as an inkscape extentions to generate .dd2vtt. 
June 14 (4 years ago)
The Aaron
Roll20 Production Team
API Scripter

Ah, cool!

Tried running it and get: "Error:Universal VTT Data is missing or corrupt."

June 14 (4 years ago)
The Aaron
Roll20 Production Team
API Scripter

Make sure you put the JSON data from the .dd2vtt file in the gmnotes in the selected graphic. The format is persnickety, so be sure you got all of it and that you replaced everything in the gmnotes with it. 

June 14 (4 years ago)

Edited June 14 (4 years ago)

Thanks, I did do that, and also tried again without the "image" line & stuff that follows, but no luck.

June 14 (4 years ago)
The Aaron
Roll20 Production Team
API Scripter

If that doesn't work, pm me a link where I can grab the files and I'll try it. 

PM sent.

June 15 (4 years ago)

Aaron, we figured it out.  Had a rogue comma from removing the image tag section.

Thanks Howard & The Aaron.  If anyone else sees this and doesn't know how to code (like me),

If you delete the line that starts with "image": and all the base64 stuff after it

In my files the preceding line had a comma that needs to be deleted as well.

June 15 (4 years ago)
The Aaron
Roll20 Production Team
API Scripter

Ah!  Great catch!  I didn't even think about that. JSON format only permits a , when it separates entries, I just naturally remove them without thinking about it. Unfortunately the JSON decoder is very picky and there's not much alternative. Glad you got it working!  

June 15 (4 years ago)
David M.
Pro
API Scripter

The Aaron strikes again!!! Very cool

June 15 (4 years ago)
The Aaron
Roll20 Production Team
API Scripter

=D  I'm definitely interested in any enhancement ideas or ways to make it easier to use!

I was just playing with dungeon draft this weekend, this makes it sooooo much nicer. Thanks for implementing this!.

June 16 (4 years ago)
The Aaron
Roll20 Production Team
API Scripter

No problem!

One thing I found is that Dungeondraft now prettyprints the json in the universalVTT files meaning lots of white space that gets converted to   Non-breaking spaces when pasted into the gmnotes. I had to add a .replace(/ /g,'')  to the line that pulls out the json to be parse to makes this useable without some preprocessing.

Also, I didn't didn't get properly scaled and positioned walls the first time, this may be because I was using a Roll20 map with the first and second floor maps of a building placed side by side. for me the lines were properly aligned with the tokens upper left corner but not scaled to the token.

June 17 (4 years ago)
The Aaron
Roll20 Production Team
API Scripter

I'll have to look into the pretty printing issue, but that's probably a reasonable way to address it.  It's unlikely that the   is in the source file as that string would not be valid JSON in the places where it must be appearing.  It's more likely it's getting introduced by some intermediate step such as a local editor, or the browser when you put it in the text box, or Roll20 when they encode it into the notes field.  My guess would be it's whatever editor you're using to pull it up.  If you're loading it with a web browser that formats it for display and copying that output, it would definitely get introduced.  I'll add something to deal with that case, but if you can speak to your process getting it into the box, that would help track down and address any issues with the format.

As for the DL lines, it expects the selected image to represent just the exported portion of the map.  I had to make a choice between drawing the lines at the scale they were in the file and ignoring the image, or scaling the lines to the image.  i went with scaling the lines to the image so as to support putting your map in at double size, or a different aspect ratio.  Since I can't determine where the lines would need to be offset on a composite graphic without some sort of intermediate input or positioning landmark, I chose not to support that option, favoring a simple interface.  In the case of multiple floors, placing them individually as exported is the most reasonable and viable option, in my opinion. That said, if you have some thoughts on ways to support a composite image, I'd love to hear them!

Thanks for the feedback!

June 17 (4 years ago)
The Aaron
Roll20 Production Team
API Scripter

UniversalVTTImporter is now available in the 1-click!

I tried copying from multiple text editors from Notepad++, sublimetext, plain Notepad using Firefox as the browser. all of these resulted in &nbsp being introduced.

Your assumption of using only the exported region is completely reasonable but I then don't understand why what I did didn't work. both images were the same size with the same aspect ratio and covered the full map export. I was able to scale out the lines and align them so it wasn't a big deal just odd.

June 17 (4 years ago)
The Aaron
Roll20 Production Team
API Scripter

hmm.  If you want to PM me an invite to your game and GM me, I can jump in tonight and take a look.

What OS are you using?  Can you try Chrome?  If you want to send me a link to your exported files and possibly the source file if it doesn't contain anything proprietary, I can attempt an export and see if I get the same results.  What version of DD are you using?

June 21 (4 years ago)

I also ran into an issue using this script while running the VTT from within Firefox.  Followed the appropriate steps of copying the JSON from the dd2vtt file into the GM Notes of the map image and saving, then running !uvtt.

In Firefox, it returned an error stating that the data was missing or invalid/corrupt.  I started over and followed the exact same steps using Chrome, and the script ran just as expected, generating the dynamic lighting layer lines and light tokens.  I'm not sure where the disconnect is between Firefox and Chrome, but I can vouch that the script does work beautifully in Chrome at least.  Thanks for your work on this!

June 21 (4 years ago)
The Aaron
Roll20 Production Team
API Scripter

Thanks for the info!  I'll try it out on Firefox tomorrow and see if I can figure out the issue. 


Ryexandra said:

One thing I found is that Dungeondraft now prettyprints the json in the universalVTT files meaning lots of white space that gets converted to   Non-breaking spaces when pasted into the gmnotes. I had to add a .replace(/ /g,'')  to the line that pulls out the json to be parse to makes this useable without some preprocessing.

Also, I didn't didn't get properly scaled and positioned walls the first time, this may be because I was using a Roll20 map with the first and second floor maps of a building placed side by side. for me the lines were properly aligned with the tokens upper left corner but not scaled to the token.


Where do you place .replace(/ /g,'')  in the text? I have no idea.



The Aaron said:

Make sure you put the JSON data from the .dd2vtt file in the gmnotes in the selected graphic. The format is persnickety, so be sure you got all of it and that you replaced everything in the gmnotes with it. 


I'm having this same problem. The "image" and "," issue doesn't seem to be the cause, but I am sure I'm doing something absolutely wrong.


June 21 (4 years ago)
The Aaron
Roll20 Production Team
API Scripter

Can you describe your workflow for getting the text from the .dd2vtt file into the GMNotes field?  What program are you viewing the text in, how are you copying it, what operating system and browser, etc

Opening it in notepad. Copying all the info down to the "]" before image (making sure the comma is gone too.) Copying that over on to the picture of the map on the map under the GM text. Saving. Clicking the picture and running !uvtt in the chat.


I might be able to send you some pictures in a bit.

June 21 (4 years ago)

Edited June 21 (4 years ago)

The Aaron, I was recreating the issue and figured out what the issue is and hopefully someone else can use this info.

I had no issues with the pretty formatting coming out of notepad.

The problem was, after the "]" at the end before the ", and image" I needed to put on another line a "}" That solved it and worked perfectly!

I deleted everything after that containing the Image data as recommended.

June 21 (4 years ago)
The Aaron
Roll20 Production Team
API Scripter

Glad you sorted that out.  Editing those files is way to tedious, so I created a page that does it for you (all in your local browser, so fast with no uploads), and updated the instructions:

5. Visit http://roll20api.net/uvtti.html and sanitize and copy your .dd2vtt contents.

All you have to do is load your file and it will parse it, remove the image, format it more compactly, and select it for you so you can just hit ctrl-C or cmd-C and copy it.  Easy peasy!


The Aaron said:

Glad you sorted that out.  Editing those files is way to tedious, so I created a page that does it for you (all in your local browser, so fast with no uploads), and updated the instructions:

5. Visit http://roll20api.net/uvtti.html and sanitize and copy your .dd2vtt contents.

All you have to do is load your file and it will parse it, remove the image, format it more compactly, and select it for you so you can just hit ctrl-C or cmd-C and copy it.  Easy peasy!

Umm, that's awesome! You are awesome!


June 21 (4 years ago)
The Aaron
Roll20 Production Team
API Scripter

Ok, I've verified that Firefox does have the nasty habit of inserting   all over so that it can pretty print in the pasted box.  The webpage I created prevents this from happening as it does not pretty print the output, but I will also adjust the script to trim those out.  Thanks everyone for pointing out that issue!!

June 22 (4 years ago)
The Aaron
Roll20 Production Team
API Scripter

Update v0.1.1 -- Added trimming of non breaking spaces to fix FireFox use.  Created and documented companion website (http://roll20api.net/uvtti.html) for preprocessing file for easier use.  (Thanks Ryexandra, Casey D.Justin S.)

July 03 (4 years ago)
The Aaron
Roll20 Production Team
API Scripter

This update is now in the 1-click!  Cheers!

Hello there!


I just tried this script out and it worked flawlessly except it didn't add the light to the light sources. Might I be doing something wrong?

August 15 (4 years ago)
The Aaron
Roll20 Production Team
API Scripter

Are you using Legacy Dynamic Lighting or Updated Dynamic Lighting?  I need to add UDL support as it wasn't ready yet when I created the script. I'll try and prioritize that. 

Ah, yeah, it's due to the updated dynamic lighting then!

Gotta say, BIG thanks for this script, it's awesome!

August 15 (4 years ago)


The Aaron said:

Are you using Legacy Dynamic Lighting or Updated Dynamic Lighting?  I need to add UDL support as it wasn't ready yet when I created the script. I'll try and prioritize that. 


Any idea roughly how long that'll take? I have a map I'm using in a few weeks (I assume it'll take longer) but if it's actually not that hard to implement, I'll hold off doing the lighting manually

August 20 (4 years ago)
The Aaron
Roll20 Production Team
API Scripter

Update v0.1.2 -- Added UDL support.  Note that if you are using UDL, the UDL gets toggled off and on causing the map to be revealed briefly.  This is a bug in the way UDL lights are supported with the API.  I've reported it and will fix it when a fix becomes available.  (Thanks Elias. Ö. S.Ben M. )

Deepl translation:

Hello, I put the JSON on the GM's notes in my graph of the map (on the background layer), I launched !uvtt but nothing happens.

I have also activated Dynamic Light.

Exported from Dungeondraft.


JSON : https://pastebin.com/f3QQs3gx

August 25 (4 years ago)
The Aaron
Roll20 Production Team
API Scripter

Ok. Some things to check:

  1. You are in a game created by an Active Pro Subscriber
  2. You have the API script installed
  3. You have Either LDL or UDL enabled on the page
  4. You have the graphic selected when you run !uvtt command

I tried your JSON and it created DL lines and lights for me, so I suspect either you don't have DL of some type enabled, or you don't have the graphic selected when you run the command.


August 29 (4 years ago)
AquaAlex
Sheet Author
Translator
API Scripter

WHAT A GUY!

The Aaron said:

UniversalVTTImporter



The Aaron said:

Ok. Some things to check:

  1. You are in a game created by an Active Pro Subscriber
  2. You have the API script installed
  3. You have Either LDL or UDL enabled on the page
  4. You have the graphic selected when you run !uvtt command

I tried your JSON and it created DL lines and lights for me, so I suspect either you don't have DL of some type enabled, or you don't have the graphic selected when you run the command.




It's ok, bad graphical element selected. ^^'

Ty for your help :)

September 06 (4 years ago)

Works like a dream!  Thanks, @The Aaron.

September 06 (4 years ago)
The Aaron
Roll20 Production Team
API Scripter

Woot! Glad to hear it!


September 15 (4 years ago)

So this isn't working for me.

I created a map in Dungeondraft

I exported the .png and the universal vtt files

Uploaded the graphic to my game and put it on the map & background level

Ran the vtt file through the roll20api link above - copied the ext

Doubly clicked on the map graphic - added the text in the GM notes section

ran !uvtt with the map token selected

Nothing - have tried it a few times now

page has UDL enabled and I am a pro subscriber - am I missing a step somewhere?

Thank you in advance for any help you can offer. Maybe I am not setting up my dungeondraft file right?