Scenery - Background Image Variation Manager

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.

Requirements

• Foundry VTT: Version 14 or higher
• Node.js: Version 22 or higher (if running via Node.js)

Features

• 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)

Opening Scenery

There are two ways to open the Scenery configuration:

1. 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.

2. 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.

Variations

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.

Scene Elements

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.

Copying Elements Between Variations

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.

Global Element Settings

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.

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.

Scanning for Variations

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:

• Its name contains the default's base name (e.g. Forest_Camp_Night contains Forest_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

This works with a wide variety of naming conventions:

• MyCoolMap_Autumn.webp finds MyCoolMap_Summer.webp, MyCoolMap_Winter.webp
• Blacksmith1.jpg finds Blacksmith2.jpg, Blacksmith3.jpg

GM/Player Map Detection

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.

Installation

Method 1:

Start Foundry and head to the Add-on Modules tab.
Click Install Module.
Search for "Scenery".
Click the Install button when it comes up.

Method 2:

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.

Translations are managed via Weblate. Feel free to contribute translations for your language.

If you enjoy this module, consider supporting its development on Ko-fi or Patreon.