alex3rq/vtt-battlemap-forge

vtt-battlemap-forge

Unified VTT battlemap, token, and scene-art assistant.

View source

How to use

  1. Copy the installation command and review the source package before installing it in your own agent environment.
  2. Check the source document for required tools, credentials and supported hosts.
  3. Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/alex3rq/vtt-battlemap-forge --skill vtt-battlemap-forge

Before you start

  • Installation does not include a model subscription, API allowance or permission to access your files.
  • Repository stars and installation counts describe activity, not an independent quality or security test.
Original skill document

Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.

VTT Battlemap Forge

Unified VTT battlemap, token, and scene-art assistant. Five operating modes: Prompt, Generation, Correction, Scene Art, Token.

Reference Map

Load only the references needed for the active mode. Do not load all files by default.

FilePurposeLoad when
references/aesthetic-styles.md18 rendering style definitionsAny mode requiring style selection
references/environment-presets.md11 biome/terrain presets; High-Detail Textures section at bottom loads conditionallyAny mode requiring environment selection; High-Detail section only loaded when mode=generation AND detail=high
references/vtt-core-rules.mdPerspective, grid, contrast, creatures, lighting, narrative dressing, traps, correction rules, DM map variant, quality checklistPrompt, Generation, or Correction mode
references/prompt-templates.mdCompact and Verbose prompt templates with narrative dressing fields — player and DM variantsPrompt mode only
references/scene-art-mode.mdScene Art flow, moment suggestions, cinematic prompt template — player and DM variantsScene Art mode only
references/token-mode.mdToken rules, composition, border breakout, frame, background, prompt templates, quality checklistToken mode only

Mode Selection

Prompt Mode — user asks to: create/write/rewrite/compact a prompt, describe style, prepare instructions for another image AI, convert room notes or area descriptions into a prompt.

Generation Mode — user asks to: generate an image, create a battlemap, make/redraw a map, repaint a reference, turn a description or reference into a VTT map.

Correction Mode — user requests a change after seeing a generated result: fix/adjust/change a specific area, brighten/darken lighting, add/remove/replace a prop, make a path or door clearer, change mood/contrast/detail globally.

Scene Art Mode — user asks for: splash art, key art, scene illustration, cinematic view, player handout art, alternate perspective of the map, art showing the environment from inside the location, or a dramatic moment based on the map. Scene Art is not a VTT battlemap mode.

Token Mode — user asks to create a VTT token, creature token, NPC token, monster token, portrait token, circular token, Roll20/Foundry token, or asks to convert a character/creature image into a 1:1 token. Also triggers for top-down tokens, isometric standee tokens, frameless portrait tokens.

Token Mode is inherently creature-focused — there is no DM variant. The token itself is the subject.

Token Mode triggers: "token", "VTT token", "creature token", "monster token", "NPC token", "portrait token", "circular token", "make a token", "create a token", "Foundry token", "Roll20 token", "focus on the face", "face token", "1:1 token", "character token", "generate a token", "top-down token", "overhead token", "isometric token", "standee", "standee token", "frameless token", "borderless token", "no frame token".

For full Token Mode rules, see references/token-mode.md.

If intent is ambiguous → infer the most likely mode from context. Ask for clarification only if the request cannot be interpreted usably.

DM Variant Flag

DM variant is an optional modifier available in Prompt, Generation, and Scene Art modes. Player-facing is always the default. Only activate DM variant when clearly requested.

DM variant triggers: "DM version," "DM view," "GM version," "game master map," "show the creatures," "include monsters," "with NPCs," "DM facing," "for the DM," "DM layer," "encounter map with creatures," or any explicit request to show creature or NPC placement.

Correction mode inherits the variant of the previous output — do not switch player↔DM unless the user explicitly asks.

Execution Procedure

vtt_battlemap_forge(user_request, reference_image=None, creature_images=None,
                    adventure_notes=None, zone_context=None):
    # adventure_notes = markdown, module text, room notes, or area descriptions.
    # zone_context = { label: "E2", description: "...", adjacent: [...] }
    # Applies to Scene Art only. See references/scene-art-mode.md.

    # 1. Mode
    mode = select_mode(user_request)
    # "prompt" | "generation" | "correction" | "scene_art" | "token"

    # 2. DM variant flag — default False (player-facing)
    dm_mode = detect_dm_mode(user_request)

    # 3. Style — references/aesthetic-styles.md
    style = select_aesthetic(user_request)
    # Default: Style R (Premium Painterly Tactical)

    # 4. Environment — references/environment-presets.md
    env = select_environment(user_request)
    # Default: derive from concept, or generic stone/earth dungeon

    # 5. VTT platform and cell dimensions
    platform, cell_px = detect_vtt_platform(user_request)
    # Default: Owlbear Rodeo, 100px per cell
    # See references/vtt-core-rules.md — Grid Dimensions Math

    # 6. Grid painted — default OFF
    paint_grid = user_explicitly_requested_grid(user_request)
    # Only paint a grid if user says "with grid", "show the grid", etc.

    if mode == "scene_art":
        load(references/scene-art-mode.md)
        execute_scene_art_flow(user_request, style, env, dm_mode,
                               creature_images, reference_image, zone_context)
        return

    # Token mode — see references/token-mode.md
    if mode == "token":
        load(references/token-mode.md)
        token_type = select_token_type(user_request)  # default: portrait_pog
        # "portrait_pog" | "frameless_portrait" | "top_down" | "isometric_standee"
        frame_color = select_frame_color(user_request)   # default: red; portrait_pog only
        framing    = select_framing(user_request)        # portrait_pog and frameless only
        build_token_prompt(user_request, token_type, style, env, frame_color, framing,
                           reference_image)
        output_in_code_block(prompt)
        if token_type == "isometric_standee":
            append_standee_warning()
        return

    # VTT modes only
    detail   = select_detail(user_request)          # Default: Medium
    lighting = select_lighting(user_request, env)   # references/vtt-core-rules.md
    dressing_fidelity = select_dressing_fidelity(user_request, adventure_notes, dm_mode)
    # Default: Reference Faithful. If adventure_notes are provided and the user
    # does not choose a fidelity level, default to Balanced Narrative Dressing.

    load(references/vtt-core-rules.md)

    if mode == "prompt":
        load(references/prompt-templates.md)
        variant = "dm" if dm_mode else "player"
        dims = snap_to_cell_grid(reference_image, user_request, cell_px)
        dressing = extract_narrative_dressing(user_request, adventure_notes,
                                              dm_mode, dressing_fidelity)
        anchors = extract_mandatory_visual_anchors(
            user_request,
            adventure_notes,
            dressing_fidelity,
            dm_mode
        )
        prompt = build_prompt(user_request, style, env, detail, lighting,
                              reference_image, variant, creature_images, dims,
                              dressing_fidelity, dressing, anchors)
        output_in_code_block(prompt)
        output_vtt_import_block(dims, platform, cell_px, map_concept, paint_grid)

    elif mode == "generation":
        assert_perspective_rules()
        if detail == "high":
            load(references/environment-presets.md, section="high-detail-textures")
        dims = snap_to_cell_grid(reference_image, user_request, cell_px)
        # dims = { cols, rows, width_px, height_px, estimated: bool }
        # See references/vtt-core-rules.md — Grid Dimensions Math
        apply_grid_policy(reference_image, paint_grid)
        apply_contrast_policy(style)
        apply_environmental_dressing(env, detail)
        dressing = extract_narrative_dressing(user_request, adventure_notes,
                                              dm_mode, dressing_fidelity)
        anchors = extract_mandatory_visual_anchors(
            user_request,
            adventure_notes,
            dressing_fidelity,
            dm_mode
        )
        apply_mandatory_visual_anchors(anchors)
        apply_zone_dressing_priority(dressing_fidelity, dressing)
        if reference_image:
            preserve_layout_and_topology_exactly(reference_image)
            # dimensions come from snap_to_cell_grid, not raw image size
        if dm_mode:
            apply_dm_creature_layer(user_request, creature_images)
        else:
            assert_no_text_or_creatures()
        generate_image(dims)
        output_vtt_import_block(dims, platform, cell_px, map_concept, paint_grid)

    elif mode == "correction":
        apply_correction(user_request, previous_result)
        # Change only what was requested. Preserve everything else.
        # Preserve player/DM variant of previous output unless user explicitly switches.

    verify_checklist(dm_mode)

Global VTT Priorities

Every VTT output (Prompt, Generation, Correction) must prioritize, in this order:

  1. Player-facing usability
  2. Tactical readability and clear walkable spaces
  3. No painted grid by default — VTT overlays its own grid
  4. Clean top-down orthographic presentation
  5. Long-session visual comfort
  6. Controlled prop density
  7. Professional quality appropriate to chosen style
  8. VTT Import block always present at end of output (filename, cell count, cell size, dimensions)

Gameplay clarity beats cinematic drama unless the chosen style explicitly calls for dramatic presentation (Diablo-like, Darkest Dungeon-like, Grimdark).

Reference Image Priority

If a reference image is provided, treat it as a spatial blueprint only — a 2D coordinate map for layout boundaries. It is the absolute source of truth for: geometry, topology, room shapes, cave silhouettes, wall placement, corridor width, path placement, entrances, exits, stairs, bridges, elevation cues, inset rooms, separated regions, overall playable structure, and navigation flow.

Do NOT treat it as a paint-over, redraw, or style transfer. The reference image's visual content — its art style, surface textures, linework, and colors — must be completely replaced. Only the spatial structure is preserved.

Two-pass model: Structure vs. Surface

Structure (preserve exactly): S-curve and path routing, cliff-line tiers, clearing shapes, rock formation coordinates, room boundaries, corridor widths, entrances, exits, stairs, bridges, elevation breaks, and navigation flow.

Surface (replace entirely): All internal visual content must be rebuilt from scratch. Erase the source image's art style and generate entirely new, high-fidelity textures appropriate to the target aesthetic style and environment. The reference image's painted surfaces, flat colors, and illustrative details are not carried over.

Source style erasure (conditional)

When the reference image has a distinct illustrative art style (hand-drawn, cartoon, ink linework, stylized cross-hatching, flat painted) that differs from the target aesthetic style, inject these negative instructions:

No hand-drawn linework, no baked-in ink contours, no stylized cross-hatching, no cartoon borders, no trace of the original map's illustrative texture or flat painted surfaces.

When the reference is already a photorealistic or high-fidelity render, source style erasure is not needed.

Grid artifact rejection

Reference images frequently contain painted gridlines. Explicitly instruct the generation engine:

Completely ignore the reference image's gridlines. Do not interpret grid lines as cracks, paths, stone edges, texture boundaries, or terrain features. The final output must have an uninterrupted, seamless floor surface.

Do NOT: redesign the map, invent new rooms, remove existing areas, move walls, widen/narrow corridors, add/remove paths, rotate/crop/rescale the map, or block gameplay paths with oversized props.

Area descriptions are for environmental dressing only — not permission to change layout.

Exception: image edges may be blended or extended to create a believable border environment.

Dimensions and Aspect Ratio

VTT map modes only (Prompt, Generation, Correction). Scene Art has its own dimension defaults — see references/scene-art-mode.md.

If reference image provided → count grid cells from visible gridlines (if present) to derive exact column/row count, then calculate output dimensions as cols × cell_px and rows × cell_px using the target platform cell size. If no grid visible, estimate from proportions and flag as estimated. See references/vtt-core-rules.md — Grid Dimensions Math.

If no reference image:

FormatGridDimensions (100px/cell)Recommended Use
Square20×202000×2000pxDefault. Small rooms, shrines, interior encounters
Square medium30×303000×3000pxMost VTT battlemaps
Portrait20×302000×3000pxTrail maps, vertical corridors
Wide30×203000×2000pxRoad encounters, riverbanks, open fields
Large40×404000×4000pxBoss arenas, major set-pieces

Default to 30×30 at 100px (3000×3000px) for a standard battlemap with no other context. All values stay under the 8000px long-edge limit for Owlbear Rodeo.

Style and Environment Selection

  1. User names specific style letter or environment number → use exactly
  2. User names style alias → match via reference files
  3. User names only aesthetic → pair with environment best matching map concept
  4. User names only environment → pair with Style R (Premium Painterly Tactical)
  5. User names neither → Style R + environment best matching concept
  6. No environment apparent → generic stone/earth dungeon

Combination Examples

RequestAestheticEnvironment
"painterly forest trail"Style R (Default)Env 10 (Forest)
"premium cave encounter"Style R (Default)Env 2 (Cave)
"illustrated ruins"Style R (Default)Env 1 (Ruins)
"gritty jungle cave"Style J (Gritty Dark Fantasy)Env 2 (Cave) + 6 (Jungle) blend
"grimdark swamp"Style G (Grimdark)Env 8 (Swamp)
"WoW-style frozen ruins"Style W (WoW-like)Env 5 (Arctic) + 1 (Ruins) blend
"muted ethereal plane"Style M (Muted)Env 11 (Arcane)
"clean urban sewer"Style H (Premium Clean)Env 4 (Urban/Sewer)
"Diablo hellfire dungeon"Style D (Diablo-like)Env 7 (Volcanic/Infernal)
"ink parchment cave"Style I (Ink & Parchment)Env 2 (Cave)
"FF14 ancient ruins"Style F (FF14-like)Env 1 (Ruins)
"darkest dungeon crypt"Style K (Darkest Dungeon-like)Env 1 (Ruins) or generic dungeon
"generic dungeon"Style R (Default)Generic stone dungeon

Detail Intensity

If user does not specify, use Medium.

LevelAliasesDescription
Lowlow, sparse, clean, minimal props, maximum readabilitySparse props, essential storytelling only, clean walkable spaces. Best for small rooms, narrow corridors, complex layouts.
Medium (default)medium, balanced, normal, readable detailBalanced environmental storytelling, readable prop placement, clear walkable spaces. Best for most VTT battlemaps.
Highhigh, rich, decorative, premium detail, atmospheric detail, photorealistic, cinematicFull photogrammetry-quality asset pass. Rebuild surfaces from scratch with high-density, layered textures. Apply ambient occlusion — micro-shadows under every individual pebble, root, blade of grass, and debris asset. Use directional lighting to define elevation breaks and slopes organically. Volumetric light shafts where applicable. High material fidelity: distinct rock face geology, procedural mud or stone surface variation, multi-toned groundcover. Paths, doorways, stairs, bridges, and combat spaces must remain readable. Best for boss arenas, scenic set-pieces, showcase maps, and any map where visual richness is the primary goal.

Narrative Dressing Fidelity

Controls how much weight markdown, adventure notes, and room descriptions receive when adding visible area dressing. This affects props and environmental storytelling only. It never allows layout changes, blocked tactical paths, readable labels, player-facing spoilers, or visible creatures unless DM variant is active.

If the user does not specify and no notes are provided, use Reference Faithful. If the user provides markdown, adventure notes, or room notes without choosing a fidelity level, use Balanced Narrative Dressing.

LevelAliasesDescription
Reference Faithful (default)reference faithful, faithful, close to reference, preserve original, defaultPreserve visible reference props and existing map feel. Add only light generic environmental dressing from the selected environment. Best when the goal is a polished version of the original map.
Balanced Narrative Dressing (recommended with notes)balanced narrative, balanced dressing, use notes, use markdown, player-safe notesPreserve the spatial blueprint while using markdown or room notes to add player-safe visible details per area: occupation, wear, materials, residue, furniture, bedding, storage, debris, and atmosphere. Do not reveal hidden content.
Strong Narrative Dressingstrong narrative, strong dressing, story-rich, room identity, must include key propsStrongly differentiate each room using player-safe notes. Required props may be phrased as "must visibly include" when they do not spoil secrets or block movement. Keep tactical paths clear.
DM Spoiler Dressingdm spoiler, spoiler dressing, dm dressing, reveal secretsOnly valid when DM variant is active or the user explicitly requests a DM-facing spoiler map. May include visible traps, hidden occupants, secret treasure, ambush positions, and other DM-only information, while still avoiding text labels and UI.

Player-Safe Narrative Extraction

When markdown, adventure notes, or room descriptions are provided, extract only details safe for a player-facing map: visible room use, wear, occupation traces, materials, remains, past events, atmosphere, and non-secret props. Do not reveal hidden traps, ambushes, secret doors, hidden treasure, invisible creatures, puzzle solutions, or information players should discover through exploration.

Treat area labels from the notes as internal placement guides. Never render area labels, room names, text, or annotations on the map.

Mandatory Visual Anchors

Mandatory Visual Anchors are concrete, player-safe objects that must appear visibly in the final map.

They are extracted from adventure notes, room keys, or user-provided area dressing when a room contains an object that defines the room's identity or gameplay readability.

Mandatory Visual Anchors are especially important for:

  • Small rooms of 1–12 cells
  • Hidden or secret chambers that are included in the visible reference layout
  • Rooms whose identity depends on a single prop
  • Treasure/stash rooms where a closed container is visible but contents must remain hidden
  • Trap or hazard rooms where the visible, non-secret physical feature matters
  • Rooms that previously failed to show required props

Mandatory Visual Anchors are not general atmosphere. They must be concrete nouns or short concrete prop phrases. For props prone to perspective drift (chests, barrels, crates, tables, sarcophagi, beds, columns), append explicit top-down language: "viewed strictly from directly overhead," "rectangular top/lid only," "no front/side face visible."

Examples:

  • closed wooden chest: rectangular top/lid viewed strictly from directly overhead, no front/side face
  • broken crate scraps
  • dusty footprints
  • sarcophagus: rectangular top/lid only, viewed from directly above
  • old table: flat top surface, overhead view only, legs implied by shadow beneath
  • four upright log stools: top-down circular silhouette with contact shadow
  • heavy rolling log
  • shallow pool
  • closed stone coffin: rectangular top/lid only, overhead view
  • bedroll pile
  • weapon rack: top-down arrangement, no side panels

Do not use Mandatory Visual Anchors for:

  • Hidden monsters
  • Creature silhouettes
  • Secret-door outlines
  • Hidden treasure contents
  • Magic item reveals
  • Readable notes
  • Puzzle solutions
  • DM-only clues
  • Exact ambush positions

If a visible container is allowed, such as a chest in a discovered or visible room, render it closed, mundane, unlit, and without visible contents unless DM Spoiler Dressing is active.

Mandatory Visual Anchor Extraction

When extracting area dressing, also identify 0–3 Mandatory Visual Anchors per keyed area.

Selection priority:

  1. A concrete object explicitly named as required
  2. A single object that defines the room's identity
  3. A visible obstacle, landmark, container, or furnishing important to navigation or recognition
  4. A small-room prop that would be easy for the image model to omit
  5. A player-safe clue that communicates room use without revealing secrets

For each area:

  • Use 0 anchors if the room has no necessary concrete prop.
  • Use 1 anchor for most rooms.
  • Use 2–3 anchors only when the room is small or the props are critical.
  • Keep anchors short and object-focused.
  • For perspective-prone props (chests, barrels, crates, tables, sarcophagi, beds, columns), append explicit top-down constraint: "rectangular top/lid viewed strictly from directly overhead, no front/side face, no angled perspective, flush with the floor."
  • Avoid atmospheric abstractions like "stale air," "ominous mood," or "neglected feeling."
  • Do not include spoilers in player-facing mode.

Mandatory Visual Anchors should be rendered before general area dressing.