FVTT to Fantasy Grounds map export/import

[Trenloe]

Universal extension (works in all rulesets) available on the FG Forge here: https://forge.fantasygrounds.com/shop/items/2340/view

I support a lot of cartographers who crowdsource their maps - on Patreon, via Kickstarters and similar campaigns, etc.. Many of these cartographers provide Foundry VTT maps with LoS and lighting setup. Few do this for Fantasy Grounds. (Shout out to Angela Maps and Grim Press who provide FG maps through their Patreon pages - I'm sure there are more too!)

I've written a work-in-progress FG extension that allows you to import maps exported from FVTT into Fantasy Grounds - including LoS and Lighting.

There are some setup steps that *must* be carried out to successfully use this extension - please refer to post #3 below for details.

In order to export the map data from Foundry a licensed locally installed copy of the Foundry application is needed. I'm not aware of a way of doing this without a license - but I'm not that familiar with Foundry. If someone knows of a way to do this with the Foundry demo, please let me know how!

A few gotchas/comments:
1) Requires a locally installed, licensed copy of Foundry.
2) You must own the maps and have them installed in Foundry - there are a number of ways to do this: manifest URL, manual installation, Patreon sync, Moulinette sync.
3) You must only use the exported maps for your own use - unless you have permission from the copyright owners to use their work otherwise.
4) Foundry maps will frequently exceed the recommended FG image size of 4k x 4k pixels. Use maps larger than this at your own risk! The larger the map the higher the load on Fantasy Grounds - even though it may work fine on the GMs computer, it may overload players computers.
5) I've only tested this on Windows. It may not work on MacOS or Linux.
6) The import process into Fantasy Grounds can be done while you're running a campaign - once you've done the process a couple of times, you'll be able to quickly export maps from FVTT and into Fantasy Grounds quickly and easily - even while running a game!
7) This is a work-in-progress. I'm fully expecting issues with certain maps and/or user's installations. I'll try and fix issues as they occur.
8) This is a work-in-progress. Foundry has some LoS options that don't directly map to FG LoS options, and I've noticed different cartographers do things differently in FVTT than others. I've made an attempt to map these as best I can, but some LoS components might not be exactly the right type once imported into FG. Please manually change once in FG. If there's a regular occurrence of mismatching LoS in FG compared to FVTT, please provide details and I'll update the extension if I can.
9)A lot of data is output to the FG console - this is for debugging purposes. Please ignore any console debugging, except actual errors.
10) Other than the little FVTT2FG import button in the campaign Images list, this is a standalone extension. It shouldn't clash with other extensions.

[Trenloe]

Videos

1) Technical setup and first examples: https://youtu.be/j91NiJCUBww
2) New Import GUI and "Do Not Import Tiles" option: https://youtu.be/Gzld8X3b9Gc
3) Example using map content synched into FVTT from a Patreon account: https://youtu.be/PRG4bTCdBOo
4) How FVTT sound links appear in the Fantasy Grounds imported maps: https://youtu.be/m_kqmdJnP1s Note: for the token sound functionality to work the name of the symbolic link directory within the FG App Data directory must be FVTT
5) v1.1 update: https://youtu.be/WUlKrQ-F0J4



Versions
11/13/2025 v1.1.1 - Fix for error when double-clicking on CT tokens within a map.
9/9/2025 v1.1 - expanded import GUI, ability to rename assets (allows support of FVTT maps with the same image filenames), log window, support for FVTT Monks Active Tiles maps.
8/24/2025 - added a GUI window with "Do Not Import Tiles" option. Details here: https://www.fantasygrounds.com/forums/showthread.php?85659-FVTT-to-Fantasy-Grounds-map-export-import&p=749871&viewfull=1#post749871 Existing assets will be used if an image file of the same name is found within the campaign images directory. This could have unwanted functionality if an existing asset not related to the imported image already exists.
8/21/2025 - addition of sound link tokens.
8/21/2025 - Initial release.

[Trenloe]

Detailed in this video: https://youtu.be/j91NiJCUBww


Install a licensed copy of the Foundry application
Create a "FGMapExport" or similarly named, folder within the FVTT Data directory - usually C:/Users/<username>/AppData/Local/FoundryVTT/Data
Within Foundry:
- Install a game system.
- Add a Game World.
- Install one, or more, map modules.
- Load the Game World created earlier and activate your map modules.
- import some maps from the modules into the game world.
- export the maps (scenes within FVTT) into the directory created in step #2 above.
Only needed for linking FVTT map sounds to FG maps Create a symbolic link directory called FVTT from the Fantasy Grounds data directory to the FoundryVTT directory. This is needed to allow FG to access the assets of the FVTT map exported. Do not use a Windows shortcut, it needs to be a symbolic link. For example, using a command prompt running as Administrator from within the FG App Data directory: mklink /d FVTT "C:/Users/<username>/AppData/Local/FoundryVTT"
Load a Fantasy Grounds campaign with the FVTT to FG Map import extension enabled.
Use the FVTT2FG image import button within the campaign Images list - select a JSON file exported from FVTT in step #9 above.
Wait a few moments for Fantasy Grounds to parse through the map data a create a new map in FG with LoS and lighting imported.

[Trenloe]

Placeholder 4

[MrDDT]

Thanks Trenloe, this is awesome news. Very nice work.

[bayne7400]

Nicely done!

[Trenloe]

The extension has been approved and is now available in the FG Forge - link in post #1.

[Tempered7]

Videos:

1) Technical setup and first examples: https://youtu.be/j91NiJCUBww

Great news! Thanks Trenloe!

If I may add: There is an easier way to create Symbolic Links in Win10-11 for users who don't want to use command line.
(I don't know if the option is in every version, if it's not there) After installing Link Shell Extension https://schinagl.priv.at/nt/hardlinkshellext/linkshellextension.html
You just right click a file, then choose "Pick Link Source". Then just "drop" into desired folder.

https://winaero.com/blog/wp-content/uploads/2016/08/pick-link-source-for-folder.png
https://winaero.com/blog/wp-content/uploads/2016/08/Drop-as-for-folder.png

Note: Images are taken from here (https://winaero.com/manage-symbolic-links-hard-links-and-junctions-easily-with-link-shell-extension/).

[Trenloe]

If I may add: There is an easier way to create Symbolic Links in Win10-11 for users who don't want to use command line.
(I don't know if the option is in every version, if it's not there) After installing Link Shell Extension https://schinagl.priv.at/nt/hardlinkshellext/linkshellextension.html
You just right click a file, then choose "Pick Link Source". Then just "drop" into desired folder.
Thanks for that information. That's not standard Windows functionality, that's a third party extension. For the one-off symbolic link needed for this FG extension it's probably overkill to install a third party Windows extension - but if people don't want to use the command line it's a possible option. Thanks.

[Trenloe]

New build uploaded introducing sound link tokens within the FG map - see video 3 in post #2 for details.

[dmbrown]

Trenloe, you sir are a legend. I’ve gotten it to work on my Mac with some free maps and for Patreon: LOVEMAPS Cthulhu, but not DM Andy’s, because I think he is using a bunch of mods in his maps that are probably causing issues.

[Trenloe]

Trenloe, you sir are a legend. I’ve gotten it to work on my Mac with some free maps and for Patreon: LOVEMAPS Cthulhu
Great! Thanks for the feedback - good to know it works on a Mac. Also nice to know that Lovemaps Cthulhu works - I support them, but haven't tried any imports yet.


...but not DM Andy’s, because I think he is using a bunch of mods in his maps that are probably causing issues.
Guess what? I also back DM Andy! What's not working - do you have an example? I may be able to do some work around coding.

[dmbrown]

The map I tried was the blue water inn and I got an error when trying to import. I haven’t tried any of his other ones yet. I believe that his maps use a bunch of other mods, so I don’t know if that is causing the errors.

[Trenloe]

The map I tried was the blue water inn and I got an error when trying to import. I haven’t tried any of his other ones yet. I believe that his maps use a bunch of other mods, so I don’t know if that is causing the errors.
The main reason for the errors is that the maps use the Monk's Active Tile Triggers mod and there's no base background image defined. I've updated the code to do a work around of using the image in the first defined tile, but there's now further errors as on my install it can't find some images in an <FVTT>\Data\icons directory - for example: icons/magic/fire/flame-burning-campfire-rocks.webp

Unfortunately, the current code to import graphical assets raises errors if the image doesn't exist, and I can't check this within the limited FG LUA implementation (for security reasons) before I try the asset import. I've reached out to SmiteWorks devs to see what can be done about this.

I'm not sure where these icons come from, so I can't full complete testing right now using the Blue Water Inn - Level 1 map.

I've just uploaded a new build that should allow further progress - even with errors. I get errors for the non-existing icons, but at least the first layer is added with LoS and Lighting:

https://www.fantasygrounds.com/forums/attachment.php?attachmentid=65228

[Trenloe]

@dmbrown - Moon Wizard got back to me very quickly with a work around. The current build should allow the Blue Water Inn to be imported into FG. Run and update and see what happens!

The main gotcha with my work around for this particular set of images is that the first tile is the same in a couple of Blue Water Inn images - so you can't import the exterior, floor 1 and floor 2 without doing a little bit of editing to change the filename of one of the images.

Plus, tiles that previously worked won't import (e.g. the rooves on Oleg's Trading post) - working on a fix for that.

EDIT: I've uploaded a new build that includes an option to turn off tile importing, which can be used if errors are occurring. Refer to post #17 below.

[dmbrown]

Thanks for looking into this and continuing to update it for DM Andy’s maps. I’ll try again when I have a chance and let you know.

[Trenloe]

A new build is available - this introduces a GUI window to handle the import process - see the screenshot below.

Also see this video for an overview: https://youtu.be/Gzld8X3b9Gc

Existing assets will be used if an image file of the same name is found within the campaign images directory - a chat message will indicate when this is occurring. This could have unwanted functionality if an existing asset not related to the imported image already exists.

Referring to the screenshot below:

Click this button to open an "Open File" window that allows selection of the FVTT Map JSON file that will be used for the import process. The complete file path will be displayed to the right of the button.
Once a file is selected, click this button to start the import process.
If errors relating to tiles are encountered, select this option to disable tile importing. This can help with errors but will result in no tiles being imported - only the base background/foreground images.
If you need to process a map again and you encounter the "Image file already exists in campaign. Skipped." chat message, and an incorrect asset file is used, use this button to access the campaign data directory. Navigate to the "images" directory and delete the images in question (be careful not to delete image files used by existing FG image records).

https://www.fantasygrounds.com/forums/attachment.php?attachmentid=65232

[Trenloe]

The map I tried was the blue water inn and I got an error when trying to import. I haven’t tried any of his other ones yet. I believe that his maps use a bunch of other mods, so I don’t know if that is causing the errors.


The main reason for the errors is that the maps use the Monk's Active Tile Triggers mod and there's no base background image defined. I've updated the code to do a work around of using the image in the first defined tile, but there's now further errors as on my install it can't find some images in an <FVTT>\Data\icons directory - for example: icons/magic/fire/flame-burning-campfire-rocks.webp

I've been working with the SmiteWorks devs to allow more functionality with the FG image import API. Once this base FG Application functionality is released to live I will provide an update to this extension.

I've expanded the base import window to provide more information and allow some changes/options: change image name when imported into FG, ignore tiles (in case they are causing issues), rename assets (for map imports that use the same filename but in different directories). The grid and width/height information are read-only.

https://www.fantasygrounds.com/forums/attachment.php?attachmentid=65367

Here's an example of importing a FVTT map that had multiple layers using Monk's Active Tile Triggers - imported as different layers, with the LoS and lighting being on the bottom layer. Enable the one layer you want visible, delete those you won't use:

https://www.fantasygrounds.com/forums/attachment.php?attachmentid=65368

[dmbrown]

This sir is awesome! Thanks for continuing to update this extension with great features and functionality. This will allow me to import a number of Foundry maps I have into FG.

[madman]

Masterful...

[Trenloe]

9/9/2025 v1.1 - expanded import GUI, ability to rename assets (allows support of FVTT maps with the same image filenames), log window, support for FVTT Monks Active Tiles maps.

See the v1.1 functionality here: https://youtu.be/WUlKrQ-F0J4

[chatty]

@dmbrown I also am using a Mac but have have no success. Could you link me to the free ones that worked so I can try to figure out if the problem is me or the maps I chose?

And @Trenloe: super cool. I have a LOT of Foundry content I would love to leverage once I get this working.

[Trenloe]

@dmbrown I also am using a Mac but have have no success. Could you link me to the free ones that worked so I can try to figure out if the problem is me or the maps I chose?

And @Trenloe: super cool. I have a LOT of Foundry content I would love to leverage once I get this working.
I've been converting a lot recently, but I use windows. A smile crosses my face every time I see a cool Foundry map pop up "magically" within FG!

What issues are you coming across on the Mac? Does FG even create the image, or something else? I've written the extension with a lot of debug output to the console, just for such instances as this (i.e. to help us narrow down issues locally or with a specific type of Foundry map). Can you try a conversion and then compile the logs (link in my signature) and post those here with details of the map/s you're trying to convert?

[Trenloe]

@chatty - additionally, I assume you've carried out the steps outlined in post #3? What is the directory path for the FVTT JSON file you're selecting in the FVTT2FG Import window within FG?

[chatty]

I got it working. I had reversed the direction of the symlink. I will test with a few other maps and then resume spending far too much money on map related Patreons. This is super cool. Thank you!

[Trenloe]

I got it working. I had reversed the direction of the symlink. I will test with a few other maps and then resume spending far too much money on map related Patreons. This is super cool. Thank you!
Great! Let us know how it goes for you.

[Trenloe]

Bugfix release:

11/13/2025 v1.1.1 - Fix for error when double-clicking on CT tokens within a map.