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 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.
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.
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:
- The width (in pixels) of the image.
- The height (in pixels) of the image.
- The grid size (in pixels); the number of pixels which represent a single grid space.
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
- 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
- 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
- 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.
- 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.
To interact with Scenes programmatically, you will primarily use the following API concepts: