Foundry Virtual Tabletop has two primary ways to set configuration options, command line flags and directives in options.json. In most cases, options set via command line flag will override the corresponding directives in options.json, however, the number of flags available is comparatively limited.
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.
- This specifies the port Foundry will listen on for incoming connections. If not specified, Foundry will use the port defined in options.json, or
- This 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.
- 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.
Example usage of the command line syntax to launch the application for various environments are:
node main.js --port=30000 --world=myworld --dataPath=/local/data/foundryvtt
FoundryVTT.exe --port=30000 --world=myworld --dataPath=D:\FoundryVTT
foundryvtt --port=30000 --world=myworld --dataPath=/local/data/foundryvtt
Foundry's behavior can also be customized via editing the options.json file stored in the Config directory located in 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.
- 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.
- Boolean -- 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 comply with operating system expectations (most notably on Windows and MacOS), it is important not to store actively updated user data inside the application directory itself. Therefore Foundry Virtual Tabletop relies upon the concept of a user data path which defines the location that user data is saved. There are four ways that the user data location can be set.
- Command Line Flag. See the Command Line Options above.
- Environment Variable. Set
- Config Data Override. See the Application Configuration Options section above.
- Default OS Application Data. See below for details.
These options are evaluated in the above order, so if multiple options are set, the first valid option will be used. The default application data location for each operating system is the following:
Note that when configuring a custom path in Windows you need to either use forward slashes, for example
D:/path/to/appdata or escaped backwards slashes,
Linux (in order of availability)
/home/$USER/.local/share/FoundryVTT /home/$USER/FoundryVTT /local/FoundryVTT
These default locations may not be ideal for many users, so it is recommended to use one of the above alternative methods to point Foundry VTT to a different data location as suits your preferences. 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.