All about Universal VTT files

Hey folks! Today we’re going to be talking about something you may have seen around but not quite understood – the Universal VTT (UVTT) file format.

What is it?

The Universal VTT file is a file format created by Megasploot. You may know him as the developer of Wonderdraft and Dungeondraft. UVTT files come in a few different flavours; .dd2vtt, .df2vtt, and .uvtt, but underneath these are all the same file.

At its heart, the Universal VTT file is an image with a bunch of extra data attached to it. This data tells software what size the image is, what colliders/obstacles exist, and what lights are in the scene (among other things). We’ll go into detail on the exact data structure of this file at the end for you developer folk.

This is a rather convenient format as it allows sharing of complex map data in a single file, rather than having to do a lot of work yourself when moving your map between your platforms of choice.

An important thing to note with this format is that as the map is a single image, UVTT files can not contain animated content, nor individually selectable map images/tokens. The map itself is a single flat image.

 

How do I create a Universal VTT file?

A few different map creation tools can create Universal VTT files. At the time of publishing there are 4 map builders that can create UVTT files.

Master’s Toolkit

The Master’s Toolkit is an offline, all-in-one GM and map building tool that can export UVTT files. When exporting a map, select the ‘Universal VTT’ option.

These are exported with the .uvtt extension

 

Dungeondraft

Dungeondraft is an offline map building software created by Megasploot. When exporting your map, the ‘Universal VTT’ option should be selected by default. If not, click on the ‘Export Mode’ dropdown and select it.

UVTT files exported from Dungeondraft take the form of .dd2vtt files.

Dungeon Fog

Dungeon Fog is a online map builder. It has both a free tier and multiple subscription options. When exporting your map, click on the file extension dropdown and select ‘Universal VTT’.

Dungeon Fog UVTT files have the .df2vtt extension.

 

Dungeon Alchemist

Dungeon Alchemist is a 3D map builder that uses AI to procedurally generate rooms. When exporting your map, select ‘Universal VTT Export’ in the ‘Format’ section.

Dungeon Alchemist UVTT files use the .dd2vtt extension.

 

Where can I use Universal VTT files?

You’ve exported your beautiful map as a UVTT file, but what now? Below is a list of all platforms that currently accept Universal VTT files. Some may need some extra work to import them.

Master’s Toolkit

That’s right, the Master’s Toolkit is the only platform that can both import and export Universal VTT files! This support is 100% native, so all you need to do is head to the ‘Import Content’ section and select the ‘UVTT’ option. This can be a useful way to flatten your maps for extra performance.

 

FoundryVTT

While FoundryVTT does not have native support for Universal VTT files, its incredible mod support has led to Foundry user ‘Moo Man’ creating the Universal Battlemap Importer module.

Instructions on how to get this module set up and ready to import your maps can be found in this video.

 

Roll20

Roll20 does not have native support for UVTT files. If you have a Pro subscription however, Roll20 user ‘The Aaron’ has created a custom user script that can pull UVTT data into your Roll20 scenes.

You can find more information about the script and how to use it in this thread.

 

Fantasy Grounds Unity

Unfortunately FGU does not have native support for Universal VTT files. To overcome this, Github user ‘Imagix’  has created a custom Python script that can convert your UVTT file into FGU’s native format.  This script can be found here.

As running Python scripts can be a bit daunting for less technically-minded users, we would recommend importing the UVTT file into the Master’s Toolkit and then exporting it to native Fantasy Grounds Unity.

 

MapTool

MapTool supports .dd2vtt map files. Instructions can be found on their wiki here: https://wiki.rptools.info/index.php/MapTool_User_Interface#Map_Menu

Non-documented Tools

These tools have native UVTT support, however at the time of writing this article no tutorials or documentation on the import process could be found.

D20Pro

 

Encounter Plus

 

 

Universal VTT developer info

Are you a developer who wants to create a tool for UVTT files? Or are you wanting to add support to your own map builder or VTT? Read on to learn the specifics of the format.

The UVTT format is a JSON string with a hip new rebrand. While you can add some of your own tags to the file as we have, there is a core set of tags that is supported throughout all VTT software. These are documented below. All positions and sizes are in the unit of ‘Squares’. The format is as follows:

• [Format] : decimal. This is essentially a version number
• [Resolution]
  • [map_origin]
    • [x] : float (usually 0)
    • [y] : float (usually 0)
  • [map_size]
    • [x] : float (size in squares)
    • [y] : float (size in squares)
  • [pixels_per_grid] : int (number of pixels per square)
• [line_of_sight]
  • [Array of [x][y] values per object]
• [objects_line_of_sight]
  • [Array of [x][y] values per object]
• [portals]
  • [array]
    • [position]
      • [x]
      • [y]
    • [bounds]
      • [array of x,y values]
    • [rotation] : float (Radians)
    • [closed] : bool
    • [freestanding] : bool
• [environment]
  • [baked_lighting] : bool (Is lighting baked into this image?)
  • [ambient_light] : colour code hex (Ambient lighting colour to apply over the entire scene)
• [lights]
  • [array]
    • [position] : {x,y} float
    • [range] : float
    • [intensity] : float
    • [color] : colour code hex
    • [shadows] : bool
• [image] : base64 encoded PNG or WEBP.

If you would like a sample UVTT map to test your code out on, we’ve provided one here. We have added in a ‘software’ and ‘creator’ field for our own use, and we hope it catches on for other platforms as well.

 

That covers everything you need to know about Universal VTT files up to this point. If there’s any platforms we’ve missed on both the import and export side of things, leave us a comment and let us know.

Go out and create some amazing maps! See you in the next one 🙂