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.


This directory can contain folders to organize your world's scenes. For details on how to create and use them please see the Folders article.

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

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 scene configuration menu is broken up into four sections: Basic settings, Grid settings, Lighting settings, and Ambience settings.

Basic Settings

Scene Config - Basics Tab
The basic scene settings tab contains many important options that determine fundamental aspects of the scene itself.

The Basic setting tab contains all of the most commonly used and fundamental settings for how a scene is configured.

Grid Settings

Scene Config - Grid Tab
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.

Grid Types

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

Understanding Foundry Grids

Configuration of the Grid in Foundry uses three key concepts:

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.

Determining Existing Grid Sizes in Images

As not all pre-gridded maps may include their grid scale and will require you to guess or otherwise determine their intended grid scale. It is possible to get a fairly accurate grids scale by examining the dimensions of the intended background image and counting the number of grid spaces and dividing the width and height by the number of vertical and horizontal squares present. For example, a map with a pre-drawn square grid which has 22 grid spaces in width and 18 grid spaces in height with dimensions of 3080px by 2520px will have an intended grid size for this map is 140px per square.

Lighting Settings

Scene Config - Lighting Tab
The vision and lighting section of the scene configuration screen allows you to tune what tokens see on the grid.

Ambience Settings

Scene Config - Ambience Tab
The ambience and atmosphere section of the scene configuration screen allows you to keep notes, set music, and weather effects.

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: