Foundry Virtual Tabletop offers a number of layers of configuration allowing you to customize the application and server to suit your specifications. Whether you are changing these configuration options via the command line when launching FVTT, by editing the options.json configuration file, or by way of the main setup menu. This article will introduce you to the concepts of:
- Command Line Flags
- A very simple way to instruct a program that a configuration option needs to be changed. Best used for temporary changes as they have to be specified every time the program launches. These instructions override the options.json file.
- Options.JSON Directives
- Foundry VTT loads instructions, or directives, from the options.json file every time it launches, allowing you to make more permanent changes to its configuration without having to specify those changes each time you launch.
It is strongly recommended that all users set an Administrator Access Key in order to protect their setup screen from unwanted access.
The Configuration Menu
The simplest way to adjust configuration options for Foundry VTT is through the configuration tab found on the Setup menu. Changing values on this tab alters them in the
options.json file without having to edit the file directly.
This menu contains the most common options you may wish to change and is most commonly used for adjusting the port number used for hosting or the User Data path.
Any change made to the Foundry VTT's directives through the Setup menu requires a restart of the program before it will take effect, choosing Save Changes will write the data to
options.json and cause Foundry VTT to shut down.
- Administrator Password
- This is the password used to access the Setup menu, whether at first launch or when clicking Return to Setup from the login screen of a world. This password is encrypted and stored within the
admin.txtConfig folder in your User Data directory.
- Designates the TCP port for Foundry VTT to listen on
- Enable UPnP
- Universal Plug & Play (UPnP) allows Foundry VTT to attempt to automatically configure your network to allow inbound connections. If this is checked, any firewall or router on your network which allows UPnP configuration will be automatically updated with a port-forwarding rule, removing the necesessity to manually port forward. For more information, see Port Forwarding.
- User Data Path
- This directive instructs Foundry VTT to store its data in a different location than default. Please note that the folder you point this to must already exist when you direct to it.
Note that custom paths for Windows need to either use forward slashes, ex:
D:/path/to/appdataor escaped backwards slashes, ex:
- Default World
- Setting this option will cause your Foundry VTT to automatically launch your Game World when the program is started.
- Default Language
- As may be expected, this setting configures the localization of the program and can be leveraged by localization modules to ensure that the interface is translated to the language of your choosing wherever possible.
- Compress Static Files
- When checked Foundry will attempt to minify and compact all files (over 10 KB) sent to clients when they connect, resulting in less network bandwidth consumption for most users.
- SSL Certificate
- Primarily used when configuring your Foundry VTT to use Audio/Video Chat Integration, this directive points Foundry VTT to the certificate file used for SSL in order to enable HTTPS transfers.
- SSL Private Key
- Primarily used when configuring your Foundry VTT to use Audio/Video Chat Integration, this directive points Foundry VTT to the private key file used for SSL in order to enable HTTPS transfers.
- AWS Configuration Path
- This directive points Foundry VTT toward the
aws-s3.jsonfile used when configuring S3 File Storage Integration.
Foundry's behavior can also be customized via editing the
options.json file stored in the Config directory within the User Data directory. The directives take one of three data types:
- Alphanumeric characters enclosed in double-quotes. Example:
- Numbers without decimal points or other punctuation. Example:
- The values
false, all lower-case, without punctuation.
trueenables a given option,
All options can also be set to
null, which disables that option. Do not set a value to null unless you're certain it can be disabled.
Note: JSON is syntax-sensitive, and a malformed options.json file may cause Foundry to not start.
It is strongly advised that you back up options.json before editing it manually.
- Integer -- defines the default port used by the application unless one is explicitly provided using the --port flag.
- Boolean -- determines whether to run the Electron application in fullscreen mode.
- String -- you may specify an explicit path to the user data directory which should be used as the source for packages and other content. This option is only used of the command line flag with the same name is not also passed.
- String -- a custom hostname to use in place of the host machine's public IP address when displaying the address of the game session. This allows for reverse proxies or DNS servers to modify the public address.
- String -- a path which is appended to the base hostname to serve Foundry VTT content from a specific namespace. For example setting this to
demowill result in data being served from
- String -- an absolute or relative path that points towards a SSL key file which is used jointly with the
sslCertoption to enable SSL and https connections. If both options are provided, the server will start using HTTPS automatically.
- String -- an absolute or relative path that points towards a SSL certificate file which is used jointly with the
sslKeyoption to enable SSL and https connections. If both options are provided, the server will start using HTTPS automatically.
- String -- an absolute or relative path which points to an optional AWS configuration file in JSON format containing accessKeyId, secretAccessKey, and region properties. This file is used to configure integrated AWS connectivity for S3 assets and backup. For more information, see S3 File Storage Integration
- Boolean -- allow Universal Plug and Play to automatically request port forwarding for the Foundry VTT port to your local network address. Default is true.
- Boolean -- indicates whether the software is running behind a reverse proxy that uses SSL. This allows invitation links and A/V functionality to work as if the Foundry Server had SSL configured directly.
- Integer -- informs Foundry that the software is running behind a reverse proxy on some other port. This allows the invitation links created to the game to include the correct external port.
Where Is My Data Stored?
In order to protect your data, and to comply with operating system expectations, Foundry VTT secures the data for your Game Worlds, Systems, and Add-on Modules in a separate, user-specific folder stored in referred to by Foundry VTT as the User Data folder.
When Foundry VTT is launched it checks for any directive that might change where to find its User Data folder in the following order:
- Command Line Flag. See the Command Line Options below.
- Environment Variable. Set
- Config Data Override. See the Configuration Menu section above.
- Default OS Application Data.
If multiple options are set, the first valid option will be used. The default application data location for each operating system is the following:
Linux (in order of availability)
Managing Your User Data
Users frequently ask for best practices for managing their existing User Data folders to ensure that they're maintaining good backups of their worlds or in some cases to move their user data to a new location.
Backing Up Your User Data
The easiest way to backup your User Data folder is to simply copy or create a zip file of your User Data folder in entirety. Our partners over at Encounter Library have produced a short video on this which details the process perfectly: Encounter Library - Backing up your User Data Folder
About Sync Services
Incorrect configuration of automated backup services can result in permanent data loss.
The use of data syncing services such as Dropbox, OneDrive, Google Drive, iCloud, and others is attractive as a method to be certain your data is backed up as expected. However, failure to correctly set up these services can prevent Foundry VTT from accessing necessary files in your UserData folder at best, and result in data loss at worst.
If you are going to set up a data syncing service for your UserData folder, please follow these recommendations:
- Make sure that your sync service is set to only upload. Do not set the sync software to download from the service to your UserData folder.
- Backup the Data subfolder of your UserData only.
- Ideally, set the syncing service to only perform the synchronization during a time when you will not be actively using the Foundry VTT software.
Moving Your User DataThe steps for migrating the User Data folder vary slightly depending on which OS you are using, but can be reduced to the following steps (please note that these steps are over-cautious in the interest of protecting your data):
- Close FVTT if it is open. Open your current User Data path in a file browser.
- Open a second file browser and create a new folder wherever you plan to store your data. This location can be anywhere, but must not be within the Foundry VTT Application folder.
- COPY the Config, Data, and Logs folders from your current User Data folder to your new location.
- Open Foundry VTT and on the configuration tab of the main menu, set your User Data path to the new location and click Save Changes .
- Foundry VTT will shut down. Relaunch it.
- Check to see that your Worlds still appear and that the User Data Path still shows correctly on the Configuration Tab.
- Temporarily move the Data folder from your previous (or default) User Data folder to a new location.
- Close and Relaunch Foundry VTT.
- If your worlds still appear in this list, you have successfully moved your User Data to a new location and you may delete the copy of the Data folder you moved in step 7.
The user data folder contains the following basic directory and file structure.
Config/- The configuration directory
options.json- Application configuration options
Data/- User data directory
systems/- Installed game systems
modules/- Installed add-on modules
worlds/- Installed game worlds
Logs/- Server log files
When referencing data from within the virtual tabletop application, any content stored inside the Data directory is publicly available to be served directly. This is where you should put your content that you intend to use inside the application. You are free to create any folder or directory structure that you want inside this data directory. For example, if you have the following file in your file system:
<User Data Path>/Data/worlds/my-world/maps/dungeons/deadly-dungeon-01.jpg
When using that map image inside Foundry VTT, you can reference it as a web-accessible URL using the path relative to the Data folder
Regarding File Naming Conventions
Since Foundry VTT works as a web server, you should be sure to use directory and file names which conform to web file and URL encoding conventions. You should generally avoid using spaces or special characters as these are likely to cause issues when serving your content to other players. See the Google URL Guidelines for more detail.
Using Command Line Flags
Foundry has four command-line flags that can be passed when the application is run at the command line. These work with both the packaged Electron executable as well when starting Foundry via Node.js.
Example usage of the command line syntax to launch the application for various environments are:
node main.js --port=30000 --world=my-world --dataPath=/local/data/foundryvtt
FoundryVTT.exe --port=30000 --world=my-world --dataPath=D:\FoundryVTT
foundryvtt --port=30000 --world=my-world --dataPath=/local/data/foundryvtt
- Launching Foundry in demo mode allows you to configure a world which will be automatically launched and reset at a frequency of your choosing. When the world is reset, it is deactivated. The source data for the world is restored to its original state using a provided .zip file, and the next reset is automatically scheduled. Details on configuring demo mode are provided below.
- This specifies the port Foundry will listen on for incoming connections. If not specified, Foundry will use the port defined in options.json, or
30000. This is the port you should use for Port Forwarding.
- This flag allows for a specific world to be opened immediately as Foundry launches. Note that this option will not work if some setup steps are not completed, such as EULA acceptance.
The expected value is the Foundry-generated ID of the world, not the user-facing name of the world. For example, if your campaign was named
My PF2E Campaign, Foundry assigns an ID for that world by setting all characters to lowercase and replacing spaces with hyphens, resulting in
Because the ID for a world is also used as its datapath, so you can easily look up the ID for a world using the Setup screen. Just locate your world, right-click it, and select the "Edit World" option. The world's ID is listed in the "Data Path" field.
- This lets you specify the user data directory that Foundry will load up to source systems, modules, and world data.
- This disables universal plug and play. If this flag is set, port forwarding will need to be set up, or the server Foundry is running on will need to have a public IP in order for Foundry to be externally accessible by your players.
- This disables the package updating system for the core software, preventing Foundry VTT from checking if there are new core software updates available.
- Set a default administrator access key for the application which will be required if an admin access key has not been defined. If an admin key has already been set, this option will be ignored.
options.json file used to configure the server in the following way:
Alternatively, you can use
--demo=demoConfig.json which provides an absolute or relative path to a separate
.json file containing the data structure of the above example. This usage is helpful if you sometimes want to run a demo and sometimes want to run a non-demo on the same server. In this case the
demoConfig.json would look as follows: