Scenes represent the areas of a World that the players may explore. Scenes may depict a variety of settings ranging from world or regional maps all the way down to small buildings or dungeons. At each point in time, one Scene is classified as the active scene. The same scene is active for all users. For each individual user a different Scene may be treated as the viewed scene, which is the area currently rendered on the game canvas for that user.

Scenes Directory

Scenes - Directory
The Scenes Directory holds all of your world's collected scenes.

Scenes are created and managed from the Scene Directory sidebar.

Like the Journal, Actors, and Items Directories, this directory can contain folders to organize your world's scenes. To organize scenes into folders, you can click and drag them directly into the desired folder, or when editing the scene, you can select the folder it belongs to. You can click on folders to expand them, showing all of the contained scenes, or click an expanded folder to collapse it, hiding the contained scenes.

The quill icon on a Scene folder will create a new scene inside that folder, and the "plus folder" icon will create a new subfolder.

Creating New Scenes

To create a new Scene click Create New Scene, you'll be prompted to give the scene a name. Once you've named your scene you will see the Configure Scene dialog, which allows you to set all of the specific details about your scene from the artwork used to its dimensions, and grid scale.

Scenes default to an empty canvas area with a gray background, light gray grid, and basic vision settings. A scene created from the default settings can be edited easily to become whatever sort of scene is needed by reopening the scene configuration window from the scene sidebar, or by right clicking the scene in the upper navigation bar and selecting configure scene.

Scene Configuration

Scene Configuration
The Scene configuration sheet contains many important options. Each supported configuration option is described on this page.

The Scene configuration menu allows you to customize the structure and appearance of each area within your world. This configuration is displayed automatically when a new Scene is created, but can always be accessed by left-clicking on the Scene in the sidebar directory, or by right clicking on the Scene in the top navigation bar and selecting Configure.

The fields which you can customize while configuring a Scene are detailed below:

Details and Dimensions

Scene Name

The title of the scene that will appear in the Scenes directory in the sidebar and in the Scene navigation bar at the top of the screen.


Scenes may be kept as "GM Only" in which case players will not be able to access them unless a Gamemaster user activates the scene or uses the 'pull to scene' function on a player. If accessibility is set to All Players, then players may choose to view the scene themselves if it is available in the navigation bar. You probably want to keep your secret dungeon level set to "GM Only" while alternatively it makes sense to set region map the party is exploring to be viewed by "All Players".

Toggle Navigation

If this setting is enabled, the scene will appear in the Navigation bar at the top of the screen. This navigation menu is best used for scenes you plan to actively use during the course of a game session for convenient access. You can also add or remove scenes from the navigation menu by right clicking on the Scene in the sidebar directory.

Navigation Name

Override the text of the Scene Name that is displayed in the Navigation Bar for cases when it is important to avoid spoilers from revealing the true Scene name. The Scene Directory sidebar will continue to show the scene name.

Background Image

The file path or web address of the background image you wish to use for your scene. The icon to the right of the field will open a File Picker that helps you to locate images within your public directory.

Foreground Image

The file path or web address of the foreground image you wish to use for your scene. The image must be the same size as the background, and will be resized to fit automatically if it's not. As with the background image, the icon to the right of the field will open a File Picker that helps you to locate images within your public directory. Foreground images are always drawn with no occlusion and are always visible on top of the background, no matter what is below the art, so care should be taken when designing the foreground image to avoid it ruining visibility of the map. More information on the foreground and occlusion modes can be found in the Canvas Layers and Tiles articles.

Scene Dimensions

Set the the rendered width and height of your scene in pixels. If you do not fill this field out, the application will figure out both automatically once the image is loaded.

Padding Percentage

Creates a border region around the background image that is a percentage of the total scene dimensions. This padding space treats everything as unlit and hidden unless lights and an actor with vision is in that padding area. The padding otherwise functions as normal map space. The padding is intended to be used for staging tokens and tiles waiting to be used in a scene, or as extra side-rooms or hidden spaces.

Note: When editing a scene's padding after a scene is created Foundry will attempt to keep placed tokens and tiles in the padding space if its area is reduced, but the change in overall scene dimension will displace walls, lights, tokens, tiles, and notes. It is advised that you not change a scene's padding once you begin detailing a scene unless you're willing to rework any out of place assets.

Background Color

A background color to fill behind the Scene background image.

Grid Configuration

Scenes - Configuration, Grid
The grid section of the scene configuration screen allows you to tune to appearance and nature of the map grid.

This configuration section is used to modify the grid type and alignment which is displayed as an overlay atop the Scene. Even if you are using a map that has a pre-drawn grid it is important to configure this section because the Foundry grid dictates the positions where Tokens are placed, how distance is measured, or how Measured Templates identify target spaces. Configuration of the Grid in Foundry uses three key concepts:

For example, suppose you have a map with a pre-drawn square grid which has 22 grid spaces in width and 18 grid spaces in height. The original map image is 3080px by 2520px. By knowing the dimensions of the image and by counting the number of grid spaces displayed on the map we can learn that the intended grid size for this map is 140px per square.

Foundry Virtual Tabletop enforces a minimum grid size of 50px. If your map uses a grid size lower than 50px you can still use it by increasing the background size. The easiest solution is to multiply all 3 of the width, height, and grid size by two to double every dimension.

If your background image has a visible grid already incorporated into the image and you are having trouble aligning the Foundry grid with the pre-existing one, be sure to use the Grid Alignment Tool by clicking the angled-ruler icon to the right of the Grid Type dropdown which has a specialized tool and workflow to assist with this process.

Grid Type

Foundry Virtual Tabletop supports multiple grid types which can be configured on a per-Scene basis. The following options are supported:

  • Gridless - No fixed grid is used on this Scene allowing free-form point-to-point measurement without grid lines.
  • Square - A square grid is used with width and height of each grid space equal to the chosen grid size.
  • Hexagonal Columns, Odd - A column-wise hexagon grid (flat-topped) where odd-numbered rows are offset.
  • Hexagonal Columns, Even - A column-wise hexagon grid (flat-topped) where even-numbered rows are offset.
  • Hexagonal Rows, Odd - A row-wise hexagon grid (pointy-topped) where odd-numbered columns are offset.
  • Hexagonal Rows, Even - A row-wise hexagon grid (pointy-topped) where even-numbered columns are offset.
Grid Size

The grid size (in pixels); the number of pixels which represent a single grid space. Foundry's default is 100 pixel squares, and has a minimum of 50px squares. Most maps use grid sizes of 70, 100, 140, or 200 pixels per square.

Note: Changing the grid size of a map may change the alignment of walls, lights, notes, and tiles. It is recommended you decide on grid size and set it before you begin adding details to the scene to avoid having to do additional work.

Offset Background

Shift the background image horizontally or vertically by a number of pixels to better line up pre-drawn grid lines. Positive numbers shift the image to the right or down, negative numbers to the left or up.

Grid Scale

The unit of measure that each square of space represents in this map. For battlemaps this may be on the order of feet or meters, for a large region map each individual grid space could represent miles or kilometers. You may put whatever string value you wish in this field, it is only used for tooltip displays when measuring.

Grid Color

Customize the color of the rendered grid.

Grid Opacity

Customize the transparency of the grid. Higher opacity results in a less transparent grid, and vice versa. If you set this slider all the way to zero (left) the grid will not be visible at all.

Lighting and Vision

Scenes - Configuration, Vision & Lighting
The vision and lighting section of the scene configuration screen allows you to tune what tokens see on the grid.
Token Vision

If this setting is enabled, visibility of the scene will require ownership of a Token which is placed in the scene and has a vision setting. If this setting is disabled, players will be able to see a scene even if they do not have a token present. This setting must be enabled to make use of Fog of War and Dynamic Lighting features.

Fog Exploration

If this setting is enabled, fog-of-war exploration will be tracked on a per-User basis and stored to the database as the Scene is explored. If this setting is disabled, fog exploration does not occur and instead Tokens are limited to only see their current vision polygon.

Unrestricted Vision Range

If this setting is enabled, tokens with vision toggled on will be able to see everything within their line-of-sight. If the setting is disabled, tokens with vision will have what they can see restricted to only locations that are lit by a light source of some kind. In both cases walls will continue to obstruct vision as expected. This setting will have no effect if Token Vision is disabled for the scene or if the token does not have vision toggled. This setting was known as "Global Illumination," in prior versions of the software.

Darkness Level

Control a day/night transition for the Scene where a darkness level of zero corresponds to full daylight and a darkness level of one corresponds to the strongest level of darkness.

Note: setting a Darkness Level has no effect on Unrestricted Vision Distance.

Vision Limitation Threshold

When toggled, this slider determines the darkness level required for Foundry to automatically disable Unrestricted Vision (see above).

Ambience and Atmosphere

Scenes - Configuration, Ambience & Atmosphere
The ambience and atmosphere section of the scene configuration screen allows you to keep notes, set music, and weather effects.
Journal Notes

An existing Journal Entry which is linked to this Scene as a set of notes which can be conveniently accessed through the context menu from the navigation or sidebar.

Audio Playlist

With the dropdown menu you can select one of your world's Playlists which will begin automatically playing when this Scene is activated.

Playlist Sound

If a playlist has been selected for the scene, this dropdown list will let you select a specific sound from that playlist which will start playback when this scene is activated.

Weather Effect

Define an available ambient weather effect which should be applied to this Scene.

Initial View Position

Define the coordinates of an initial camera position which would define the starting view position for a character which does not have a controlled Token in the Scene. Players who have a Token in the Scene will begin their view centered on their Token location.

Scene Context Options

Scenes which are displayed in the Navigation bar will appear at the top of the screen. The navigation bar is intended to act similarly to "bookmarks" for commonly used Scenes which are expected to be used during the game session. You may have many more Scenes in your World than you wish to keep in the Navigation bar at any given time. Remember that players can access Scenes in the navigation bar also if they are not set to GM Only.

Navigation Bar Context Menu

Scene Navigation Context Menu
Scenes in the Navigation Bar have context menu options available on right-click.
Set a Scene as active, immediately loading and pulling all Users to the Scene.
Open the Scene Configuration sheet.
Preload Scene
Request that all connected Users begin loading the image and video assets needed to display this Scene in the background.
Toggle Navigation
Remove the Scene from the Navigation bar if it is not active.

Scenes Sidebar Context Menu

All Scenes, including those not displayed in the Navigation Bar, are available in the Scenes sidebar directory which is denoted by a tri-fold map icon. Each Scene in the sidebar has additional context menu options available.

Scene Sidebar Context
Scenes in the scene sidebar listing have context menu options available on right-click.
Set a Scene as active, adding it to the Navigation Bar and immediately loading and pulling all Users to the Scene.
Open the Scene Configuration sheet.
Toggle Navigation
Add or remove the Scene from the Navigation bar if it is not active.
Regenerate Thumbnail Image
Rebuild a thumbnail image for the Scene background which is displayed as a preview in the Sidebar.
Permanently delete the Scene, you will be prompted to confirm your choice if you click this option.
Copy this Scene and all its contained data to create a new Scene which can be independently configured.
Export Data
Save the contents of the Scene to a JSON file which can be saved on your own computer.
Import Data
Load stored data for a Scene from a file on your computer, updating the Scene with the stored settings.

API References

To interact with Scenes programmatically, you will primarily use the following API concepts: