---
name: create-map-art
description: Create illustrated map backgrounds during location setup, or standalone location illustrations and portraits, using the host's built-in image generation and campaign-local asset registration.
---

For a map background, follow the reference-and-overlay workflow below. For a standalone location illustration or portrait, omit reference mode and the background field when registering; it stays separate from the positional map.

Read campaign_status, get_campaign_entity for the saved map and relevant locations/characters, and relevant saved descriptions. Choose the intended audience before building a prompt. For player artwork, use only audience=party context and revealed locations; do not send private source material into the player illustration. Call render_location_map with mode=reference at the saved revision and intended viewport to get the clean geometry guide. This reference contains the selected terrain/layout, grid cell outlines and feature shapes, but no transient markers, map title, legend or text labels. Its viewport is the exact coordinate extent for the image edges. The ordinary mode=map remains the default for player-facing and DM map views.

Use the host's built-in image-generation tool when available, following its input and file handling instructions. Ask it to preserve the reference layout and aspect ratio, use a top-down view, and create an evocative terrain/architecture background, with no writing, labels, markers, compass, legend or UI. Inspect each result against the reference. If important layout or landmark placement is poor, revise the prompt and retry at most twice (three generation attempts total); minor visual geometry differences are acceptable. If no usable result remains after three attempts, keep the schematic and continue play. The image is an aesthetic background, while the saved map remains authoritative for coordinates, topology and rules. Coordinates, labels, character markers and precise geometry are drawn by the deterministic renderer over the background.

For a party-visible grid or graph background, make the entire image party-safe: never include hidden rooms, unrevealed paths, secret features or other DM-only information. Grid rendering masks unrevealed cells with opaque party fog. Graph rendering withholds the party background while any original graph nodes or edges remain hidden; fully revealed/all-public graphs can show it. DM-only artwork can include private context, but is never used in a party render. Register the exact viewport extent used for the reference so the image edges map to those map-coordinate cell boundaries.

If host generation is unavailable, continue with the schematic and explain that limitation. Never substitute a paid API or add model calls to the plugin.

Save the chosen generated output under the bound campaign's assets/ directory, using available host file tools and a unique filename. If the tool returns only a conversation image and no downloadable local artifact, explain that registration requires a saved file; do not invent a path or claim it was saved. Do not place campaign artwork in the plugin source repository. Copying an image into assets is file handling; register its metadata with register_map_art using a fresh operationId, current expectedRevision, mapId and art {path, purpose, sourceRevision, visibility, background:{extent:{x,y,width,height}}}. Use the reference viewport coordinates for extent; sourceRevision is the saved map revision used for the prompt, even if generation took time. Preserve exact input and operationId on retry. Then render the ordinary composite at that viewport and inspect the result. If art is absent, invalid or stale, rendering falls back to the schematic with a warning. If generation or saving fails, keep using the schematic and continue play.

Verify the registration with get_campaign_entity. Reuse registered art during later play. If a reviewed map change affects movement or topology, update the typed map state through the appropriate reviewed/admin path, then create and register a new background from a fresh reference. Never derive or silently change saved map geometry from artwork. Original assets participate in export/import; derived PNGs can be regenerated.

For party backgrounds, concealing a feature inside an otherwise visible cell (or a graph background extent) also withholds the artwork and falls back to the schematic. A painting cannot selectively erase that feature. Concealed grid features already covered by opaque cell fog do not suppress the rest of the background.