update-scene
Modify an existing Foundry VTT scene's name, background, grid, lighting, fog, weather, navigation, and linked documents for GM-only scene management.
Instructions
Update an existing Scene document — rename, swap its background image (Data-relative path), toggle navigation, set the navigation label, change dimensions/grid (size/type/distance/units)/padding, token vision, fog mode, lighting (darkness, global light), weather, a nav thumbnail, or the linked playlist/journal ("" clears a link). Also (parity with create-scene) deep-merges a full environment{}/fog{} mood object, re-points the saved camera (initial{x,y,scale}), or re-stamps document flags on an existing scene. Scene-document only: never touches placeables (walls/lights/tokens) and never activates the scene. GM-only.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| fog | No | A v12+ scene's full fog{} object (exploration, overlay, colors), carried whole (deep-merged). | |
| name | No | New scene name. | |
| flags | No | Document flags namespaced by scope — e.g. {"tom-cartos-import":{sourceModule,sourceId}} for import provenance/dedup. Deep-merged over any existing flags (re-stampable on update). | |
| thumb | No | Data-relative path to a pre-rendered navigation thumbnail (e.g. an uploaded <id>-thumb.webp shipped by a map pack). Foundry may regenerate it on a later in-app edit, so treat it as a nice-to-have, not load-bearing. | |
| width | No | Scene width in pixels. | |
| height | No | Scene height in pixels. | |
| fogMode | No | Fog of war: disabled | individual (classic per-player) | shared (party-wide). | |
| initial | No | The saved initial camera view {x,y,scale} to restore on scene load (deep-merged). | |
| journal | No | JournalEntry id or exact name to attach as scene notes. "" clears it. | |
| navName | No | Navigation label shown in the scene nav bar. | |
| padding | No | Scene padding fraction (0–0.5). | |
| weather | No | Weather effect key (e.g. rain, snow, fog, leaves, rainStorm, blizzard). "" = none. | |
| darkness | No | Darkness/day-night level: 0 = full daylight, 1 = full night. | |
| gridSize | No | Grid size in pixels. | |
| gridType | No | Foundry grid type (0 gridless, 1 square, 2+ hex). | |
| playlist | No | Playlist id or exact name to auto-play on scene activation. "" clears it. | |
| gridAlpha | No | Grid line opacity 0–1 (e.g. 0.2 for a faint grid). | |
| gridColor | No | Grid line color as a hex string, e.g. "#000000". | |
| gridUnits | No | Distance unit label per cell, e.g. "ft" (dnd5e default). | |
| navigation | No | Whether the scene appears in the navigation bar. | |
| environment | No | A v12+ scene's full environment{} mood object, carried whole (darknessLevel, globalLight{...}, cycle, base, dark{hue,luminosity}…). Deep-merged, so a partial mood patch layers onto the scene; prefer this over the flat darkness/globalLight knobs when importing or re-mooding a pack scene. | |
| globalLight | No | Globally illuminate the whole scene (turn the lights on). | |
| tokenVision | No | Require token line-of-sight to see the scene. Turn OFF for overland/illustration maps. | |
| gridDistance | No | Real-world distance per grid cell (dnd5e default 5). | |
| backgroundPath | No | Data-relative path to a new background/map image. | |
| sceneIdentifier | Yes | Scene id or exact name. |