How to Import Battle Maps into Foundry VTT (Universal VTT .dd2vtt, Walls and Lighting)

A battle map is only half the job. Foundry VTT also needs to know where the walls are, where the doors open, and where the light sources sit, or your players will see through walls and stand in total darkness. This guide covers creating a scene, understanding the Universal VTT format, and the actual import steps, plus a shorter section for Roll20 and Fantasy Grounds.

Step 1: create a scene

In Foundry, open the Scenes tab and create a new scene. Set the background image to your map, then open Scene Configuration to set the grid size in pixels, 100 is Foundry's default, matched to whatever pixels per square value your map was built at, and the grid type: square, hex, or gridless. Save the scene before moving on to walls and lighting, since Foundry needs the correct grid and dimensions in place first.

What the Universal VTT format actually contains

Universal VTT is a JSON based file format, usually saved as .dd2vtt, .df2vtt, or .uvtt depending on which tool exported it. Dungeondraft, DungeonFog, and Arkenforge use those three extensions respectively for what is functionally the same format. A file that follows this format typically carries a version number in a field called format, commonly 0.2 or 0.3, followed by:

• resolution: the map's pixel dimensions (map_size), where the map's origin sits (map_origin), and how many pixels represent one grid square (pixels_per_grid).
• line_of_sight: a list of coordinate points that define wall segments blocking sight and movement.
• portals: door positions, usually flagged as open, closed, locked, or a secret door.
• lights: light source positions with a range and color, if the exporting tool included them.

The map image itself is stored inside the same file as encoded text, so a single .dd2vtt file is really the map plus all its structural data bundled together. Source: Arkenforge's explanation of Universal VTT files.

Step 2: install the importer module

Foundry doesn't read Universal VTT files natively out of the box. You need the community module Universal Battlemap Importer, built by the Foundry community developer known as moo-man. Install it from Foundry's built in Add-on Modules browser, enable it in your world, then open the Scenes Directory and click the Universal Battlemap Importer button to select your .dd2vtt file. The module creates a new scene automatically, complete with the map image, grid size, walls, doors, and lights already placed according to the file's data.

Walls and doors

Walls in Foundry are what make its dynamic lighting and vision system work: a token can't see past a wall, and light doesn't pass through one either, unless a door is open. If your Universal VTT file included line_of_sight and portal data, the importer places these for you automatically. If you're working from a plain image without that data, you'll need to draw walls manually using Foundry's Wall Controls, tracing along the map's own architecture, and mark doorways as door type walls so players can open and close them during play.

Lighting basics

Foundry scenes support two lighting approaches. Global illumination lights the entire scene evenly, which is simple but removes the tension of exploring a dark dungeon with a torch. Individual light sources, either carried by a token, a lit torch, or placed directly in the scene, a wall sconce, a window, light only their immediate area and leave the rest of the map dark until a token's own vision or a light source reveals it. Most dungeon crawl scenes use individual lights with global illumination turned off, while a sunny outdoor map often just uses global illumination since there's no darkness to manage.

Tile versus scene background

A scene's background image is the base layer that fills the entire canvas and sets the grid. A tile is a separate image placed on top of that background, useful for things like a movable object, a collapsed section of floor, or a decorative overlay that shouldn't be baked into the base map. Import your main battle map as the scene background, and reserve tiles for elements you want to move, resize, or toggle independently during play.

Testing an import before your session

After running the Universal Battlemap Importer, walk a test token around the new scene before the table sees it. Check that walls actually block the token's vision where the map's own artwork shows a solid wall, that doors open and close correctly, and that the grid lines up with the map's own floor tiles rather than sitting slightly offset. A grid that's off by even a few pixels becomes obvious the moment a player tries to measure a spell's range against it.

If walls seem to be in the wrong place after import, the most common cause is a mismatch between the file's pixels_per_grid value and the grid size Foundry actually applied to the scene. Re-check the Scene Configuration grid size against the value the Universal VTT file specified rather than assuming the importer read it correctly on the first try.

Common import problems

• The scene imports with no walls at all: the source file likely didn't include line_of_sight data. Some export tools only include the image and grid, leaving wall data empty; you'll need to draw walls manually in that case.
• The map appears at the wrong scale: double-check the grid size Foundry assigned during import against the map's intended pixels-per-square value, and adjust it in Scene Configuration if needed.
• Doors don't function as doors: a portal in the Universal VTT file needs to map to a Foundry wall segment flagged as a door type, not a plain wall. If the importer placed it as a solid wall, select it with Wall Controls and change its door setting.

Performance tips

Large, uncompressed map images slow Foundry down for every player at the table, not just the GM. A few habits keep things smooth: export maps as WebP when your source tool supports it, since it holds detail at a fraction of PNG's file size; avoid uploading a map at a much higher resolution than the platform actually needs, a 6000 pixel print resolution map has no benefit on screen; and delete or archive scenes you're no longer using rather than leaving dozens of full resolution maps loaded in your world.

What Sprixen's battle map generator exports

Sprixen's free battle map generator exports the map image together with grid data in Universal VTT format, so the pixel size and grid alignment come through correctly on import. Wall placement and lighting are left for you to add inside Foundry once the scene exists, since where a table wants doors, secret passages, and light sources to sit is a table specific creative choice rather than something a generator should guess at.

Sharing a finished scene with your players

Once a scene is imported, walls placed, and lighting set, Foundry keeps all of that configuration attached to the scene itself, so any player who joins the world sees the same walls and lights without needing to do anything on their end. If you're handing off a world file to another GM, or archiving a finished campaign, export or back up the scene along with its linked journal entries and actor tokens rather than just the raw map image, since the image alone loses the wall, door, and lighting work you did during import.

Importing into Roll20 and Fantasy Grounds

Roll20 does not read Universal VTT files natively out of the box either. A community API script, commonly called UniversalVTTImporter, adds that capability by parsing a .dd2vtt file and generating matching Dynamic Lighting lines, light sources, and door objects on the page. Custom API scripts are a Roll20 Pro feature, so this route needs a Pro subscription and the script installed in your game's API script library. Fantasy Grounds doesn't have equivalent native or module based Universal VTT support as of this writing, so importing there generally means uploading the plain map image and setting up the grid and lighting by hand using Fantasy Grounds' own tools, or using a community conversion tool first.

For the size and pixel math behind picking a grid value before you even get to import, see the battle map size and grid guide, and for a wider survey of map tools beyond a single generator, check the best D&D map makers comparison.

FAQ

What is a .dd2vtt file?

It's a Universal VTT file, a JSON based format that bundles a battle map image together with its grid size, wall positions, door positions, and light data in one file. Dungeondraft, DungeonFog, and Arkenforge all export it, using the extensions .dd2vtt, .df2vtt, and .uvtt respectively for functionally the same format.

Does Foundry VTT support Universal VTT files natively?

Not out of the box. You need the community module Universal Battlemap Importer to read .dd2vtt, .df2vtt, and .uvtt files and turn them into a fully configured scene.

Do I still need to draw walls if my map file includes wall data?

No, if the Universal VTT file includes line_of_sight and portal data, the importer places walls and doors automatically. You'd only need to draw walls manually for a plain image that doesn't carry that structural data.

Does Roll20 support .dd2vtt files?

Yes, through a community API script rather than a built in feature. It requires a Roll20 Pro subscription, since custom scripts are a Pro tier capability, plus installing the script in your game's API script library.

Why does my imported map look dark or completely black?

Check whether global illumination is enabled for the scene, and whether any tokens or scene lights are placed. Without global illumination and without a light source, a scene renders as unlit until a token's own vision radius or a placed light reveals part of the map.