create-scene
Create a Foundry VTT scene from a background image, auto-detecting dimensions. Configure grid, lighting, fog, weather, walls, and lights in one call.
Instructions
Create a Foundry Scene from a Data-relative background image path (e.g. an uploaded map). Width/height auto-detect from the image when omitted. Places it in a folder (created if absent) and sets navigation (false = a DM-only scene off the player nav bar) in the same call. AUTO-GENERATES the navigation thumbnail from the background (Foundry-native) when no explicit thumb is given — no more thumbnail-less scenes. Optionally set grid size/type/distance/units/color/alpha, token vision, fog mode, lighting (darkness, global light, or a whole environment{}/fog{} mood object + saved camera for pack imports), weather, a linked playlist/journal, a nav thumbnail, padding, provenance flags, and activate it. Can also IMPORT walls + ambient lights from a map sidecar JSON (the walls/lights arrays many battlemaps ship alongside the image): pass them and they are placed on the new scene (legacy or v14 shapes both accepted, normalized to v14). 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 | Yes | 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. | |
| walls | No | Walls to import from a map sidecar JSON (the `walls` array of a Foundry scene-export sidecar that ships next to a map). Created after the scene exists; coordinates are absolute canvas pixels, so pass the sidecar width/height/gridSize/padding too. | |
| width | No | Scene width in pixels (optional — auto-detected from the image when omitted). | |
| folder | No | Scene folder id or exact name to place the scene in (created if absent). | |
| height | No | Scene height in pixels (optional — auto-detected from the image when omitted). | |
| lights | No | Ambient lights to import from a map sidecar JSON (the `lights` array). | |
| 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. | |
| padding | No | Scene padding fraction (optional). | |
| regions | No | Regions (v12+ RegionDocument incl. teleporters) to import from a scene-pack payload. Created after the scene exists; each is stamped with its source id, and cross-scene teleporter destinations are rewritten afterward by a single remap-teleporters call. | |
| weather | No | Weather effect key (e.g. rain, snow, fog, leaves, rainStorm, blizzard). "" = none. | |
| activate | No | Activate the scene after creating it. | |
| darkness | No | Darkness/day-night level: 0 = full daylight, 1 = full night. | |
| gridSize | No | Grid size in pixels (default 100). | |
| gridType | No | Foundry grid type (0 gridless, 1 square, 2+ hex). Default 1. | |
| 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 player navigation bar. Set false for a DM-only scene (keeps it off the nav bar). Omit for Foundry default. | |
| 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 | Yes | Data-relative path to the background/map image. | |
| placeablesPath | No | Server-local path to a JSON file of {walls,lights,regions} to place (as written by read-pack for a scene-pack import). Read SERVER-SIDE and merged with any inline placeables — this routes a pack's hundreds of walls/lights/regions tool→tool without passing them through the agent (the MCP response cap makes inline placeables infeasible at scene scale). |