A FoundryVTT module for managing background image variations per scene — switch between Day/Night, Seasonal, or GM/Player maps with a single click. Scene elements like lights, walls, and tiles are saved and restored automatically with each variation.
- Foundry VTT: Version 13 or higher
- Node.js: Version 20 or higher (if running via Node.js)
- Variations — assign multiple background images to a scene and switch between them instantly
- Separate GM/Player backgrounds — each variation can show a different image to GM and Players (e.g. a map with hidden rooms for the GM)
- Scene element management — lights, walls, tiles, sounds, drawings, templates, regions, and notes are captured and restored per variation
- Smart scan — automatically discover, classify, and pair map files from a directory with a single click
- Copy elements — copy scene elements (lights, walls, etc.) from one variation to another with granular selection
- Global element settings — mark element types as global so they persist across all variations instead of being switched
- Variation labels — scene directory shows a badge for scenes with multiple variations (can be disabled in settings)
There are two ways to open the Scenery configuration:
-
Header Button (highlighted above): Click the Scenery button in the Scene Directory header. This opens the configuration for the currently active scene. The button visibility can be disabled in the module settings.
-
Context Menu: Right-click any scene in the Scene Directory sidebar or the scene navigation bar at the top, then select "Scenery". This allows you to configure any scene, not just the active one.
Each scene can have multiple variations. The first variation is always the Default — its Player background is locked to the scene's background image (set in Foundry's core scene configuration). The GM background on the Default can be set independently, allowing the GM to see hidden information while players see the normal map.
Additional variations each have their own GM and Player background fields. When switching to a variation, each user sees the background assigned to their role.
When the GM switches between variations on the active scene, Scenery automatically saves the current scene elements (lights, walls, tiles, etc.) and restores the elements stored for the target variation. This means each variation can have its own lighting setup, wall layout, and tile configuration.
Non-default variations without any previously captured data start empty — add elements to the canvas and they will be saved when switching away.
Click the copy button on a variation card to open the Copy Dialog. This lets you select a source variation and choose which element types to copy (lights, sounds, tiles, walls, drawings, templates, regions, notes). Optionally enable Reset unselected elements to clear all element types that are not being copied.
By default, Scenery manages all scene element types per variation. In the module settings, you can mark specific element types as global — these will stay on the scene and not be affected when switching variations.
Defaults:
| Element type | Default |
|---|---|
| Lights | per variation |
| Sounds | per variation |
| Tiles | per variation |
| Walls | per variation |
| Drawings | global |
| Templates | global |
| Regions | per variation |
| Notes | global |
A Reset to Defaults button in the settings restores these values.
Scenes with multiple variations (2+) show a badge in the Scene Directory with the variation count. This can be toggled via the Show Variations Label setting.
Click Scan for Variations in the Scenery dialog to automatically discover map files in the same directory as the scene's default background.
Scenery uses fuzzy matching to decide which files in the directory belong to the same scene. A file is considered a variation if any of these conditions are met:
- Its name contains the default's base name (e.g.
Forest_Camp_NightcontainsForest_Camp) - The default's base name contains the file's name (minimum 4 characters)
- Both names share a common prefix of at least 60% of the shorter name (minimum 4 characters)
This works with a wide variety of naming conventions:
MyCoolMap_Autumn.webpfindsMyCoolMap_Summer.webp,MyCoolMap_Winter.webpBlacksmith1.jpgfindsBlacksmith2.jpg,Blacksmith3.jpg
Files that will not match:
- Files in a different directory
- Files with no significant name overlap (e.g.
night.jpgfor a scene namedForest_Camp)
After discovering files, Scenery automatically detects and pairs GM-specific and Player-specific versions of a map. This is controlled by two settings:
- GM Map Identifiers — default:
gm, dm - Player Map Identifiers — default:
player, pl
Tokens are matched as whole words between filename separators (-, _,
., space). A file called Enigma_Chamber.webp will not match the gm
identifier — enigma is a single token, not gm inside a larger word.
Each discovered file is classified and grouped:
| Category | Meaning |
|---|---|
| GM | Filename contains a GM identifier token (e.g. _GM) |
| Player | Filename contains a Player identifier token |
| Neutral | No identifier token found |
Files are grouped by a clean key — the normalized filename with the identifier token stripped. Files sharing the same clean key are paired into a single variation.
Given a scene with default background Forest_Clearing/Forest_Clearing.webp and
the following files:
Forest_Clearing/
Forest_Clearing.webp ← scene default
Forest_Clearing_GM.webp ← GM
Forest_Clearing_Player.webp ← Player
Forest_Clearing_Night.webp ← Neutral
Forest_Clearing_Night_GM.webp ← GM
Forest_Clearing_Night_Player.webp ← Player
Forest_Clearing_Rain.webp ← Neutral
Forest_Clearing_Snow_DM.webp ← GM (token: dm)
Forest_Clearing_Fog_PL.webp ← Player (token: pl)
Scenery produces:
| Clean key | Files in group | Result |
|---|---|---|
forest_clearing |
_GM + _Player |
Default enhanced — the default variation's GM background is set to _GM.webp |
forest_clearing_night |
_Night + _Night_GM + _Night_Player |
Variation "Night" — GM sees _Night_GM, Player sees _Night_Player |
forest_clearing_rain |
_Rain |
Variation "Rain" — both see the same file |
forest_clearing_snow |
_Snow_DM |
Variation "Snow" — GM sees _Snow_DM, Player sees the scene background |
forest_clearing_fog |
_Fog_PL |
Variation "Fog" — both see _Fog_PL |
When a group contains multiple file categories, Scenery assigns backgrounds as follows:
| Group composition | GM background | Player background |
|---|---|---|
| GM + Player | GM file | Player file |
| GM + Neutral | GM file | Neutral file |
| Neutral + Player | Neutral file | Player file |
| GM only | GM file | Scene background |
| Player only | Player file | Player file |
| Neutral only | Neutral file | Neutral file |
When a group's clean key matches the scene default, no new variation is created. Instead, the default variation's GM background is updated — this lets GMs see a version with hidden information while players see the regular scene background.
Clear both identifier settings (leave them empty) to disable GM/Player detection. All files will be treated as Neutral and each will become its own variation with identical GM and Player backgrounds.
- Start Foundry and head to the Add-on Modules tab.
- Click Install Module.
- Search for "Scenery".
- Click the Install button when it comes up.
- Start Foundry and head to the Add-on Modules tab.
- Click Install Module.
- Paste the following link into the "Manifest URL" field at the bottom: https://github.com/marcstraube/foundryvtt-scenery/releases/latest/download/module.json
- Click Install.
