generate2dmap

name	generate2dmap
description	Claude Code skill for generating and revising production-oriented 2D game maps. Use for RPG maps, monster-taming maps, tactical arenas, battle backgrounds, side-scroller/parallax scenes, tilemaps, layered raster maps, prop packs, collision zones, walkable areas, and map previews. Raw image generation must go through the installed codex-gateway-imagegen skill.

Generate2dmap

Build the smallest map bundle that satisfies the game. Decide the map as a pipeline, not as a single strategy label:

1. visual_model: baked_raster | layered_raster | tilemap | layered_tilemap | parallax_layers
2. runtime_object_model: none | separate_props | y_sorted_props | interactive_entities | foreground_occluders
3. collision_model: none | coarse_shapes | precise_shapes | tile_collision | polygon_walkmesh | trigger_zones
4. engine_target: raw_canvas | Phaser | Tiled_JSON | LDtk | Godot_TileMap | Unity_Tilemap | project-native

Use user-specified parameters when present. When the user does not specify them, infer the lightest pipeline from the existing game, camera, collision needs, map scale, and editing needs.

This Claude Code adapter has one hard rule: any raw map, prop sheet, dressed reference, or parallax image must be generated through the installed codex-gateway-imagegen skill. Do not call any built-in image generation tool directly from this skill.

Read references/map-strategies.md when the pipeline choice is not obvious. Read references/layered-map-contract.md before implementing a layered raster map. Read references/prop-pack-contract.md before batching generated props into a sheet.

Parameter Contract

User-facing parameters may be stated in natural language:

• map_kind: overworld | town | dungeon | shrine | arena | battle_bg | side_scroller | tactical
• visual_model: baked raster | layered raster | tilemap | layered tilemap | parallax
• size: pixel dimensions, tile dimensions, or camera-relative size
• perspective: top-down | 3/4 top-down | side-view | isometric-like
• collision_precision: none | coarse | precise | tile | walkmesh
• prop_generation: none | one_by_one | prop_pack_2x2 | prop_pack_3x3 | prop_pack_4x4
• output_format: PNG only | layered preview | manifest JSON | engine-native map data

When unspecified:

• Use baked_raster + coarse_shapes for battle backgrounds, title/menu scenes, cutscenes, and fixed arenas.
• Use layered_raster + y_sorted_props + precise_shapes for top-down RPG exploration with tall props, occlusion, interactables, or reusable props.
• Use tilemap or layered_tilemap only when the engine/editor already uses tiles or the user asks for editable tiles.
• Use parallax_layers for side-scrollers and scrolling backgrounds.
• Use prop packs when 4 or more small/medium static props share one style and can fit into equal cells.
• Use one-by-one prop generation for hero props, buildings, gates, irregular large props, animated props, or props needing strong identity.

Workflow

1. Inspect the target game.

   • Find camera size, map dimensions, coordinate system, render order, asset loading, collision support, zone data, and existing map formats.
   • Preserve the engine's existing style and data contracts.

2. Choose the pipeline axes.

   • Select visual_model, runtime_object_model, collision_model, and engine_target.
   • Treat hybrid as a result of combining axes, not as a primary category.

3. Produce assets through codex-gateway-imagegen when pixels are needed.

   • For baked raster maps, generate or edit one background and optional collision/zones metadata.
   • For layered raster maps, generate a ground-only base map first. Then use that saved local image as a reference input to codex-gateway-imagegen when making a dressed reference or style-matched props.
   • For tilemaps, follow the engine/editor format; do not force image-only maps into tilemaps.
   • For parallax scenes, produce background/midground/foreground layers and scroll metadata.

4. Build metadata.

   • Store prop placement, actor spawn points, interactables, blockers, walk bounds, encounter zones, exits, and triggers as structured data.
   • Keep collision independent from pixels unless the target engine explicitly uses tile collision.

5. Validate and preview.

   • Compose a flattened preview for layered maps.
   • Validate image sizes, alpha channels, prop pack extraction metadata, JSON parseability, and critical walkability points when collision matters.

Prop Generation Rules

Use /generate2dsprite for reusable transparent props when the local skill is available, but choose the generation shape deliberately:

• one_by_one: safest for large, important, animated, or irregular props.
• prop_pack_2x2: 4 related props, safest batch size.
• prop_pack_3x3: 9 small/medium props, good quality/time tradeoff.
• prop_pack_4x4: 16 very simple small props; fastest but most likely to drift or touch edges.

Prop packs save gateway calls and prompt overhead, but reduce per-prop control. Use them for rocks, shrubs, barrels, small signs, lamps, crates, floor ornaments, plants, and repeated environmental props. Do not use prop packs for buildings, gates, trees with wide canopies, character-like statues, hero objects, or anything that must be pixel-perfect.

For layered maps with generated props, prefer this reference pipeline:

1. Generate assets/map/<name>-base.png as ground-only terrain through codex-gateway-imagegen.
2. Use the saved base image path as a reference input for codex-gateway-imagegen when generating assets/map/<name>-dressed-reference.png.
3. Preserve camera, terrain, size, road/water shapes, anchor pads, and boundaries. Treat the dressed image as a planning/reference image, not the final runtime map.
4. Generate one-by-one props or a prop pack based on the dressed reference.
5. Place extracted props over the original base and compose a flattened preview.
6. Validate that base, dressed reference, and preview dimensions match.

Use the bundled prop extractor after generating a solid-magenta prop sheet:

python "${CLAUDE_SKILL_DIR}/scripts/extract_prop_pack.py" \
  --input "assets/props/<pack>/raw-prop-pack.png" \
  --rows 2 \
  --cols 2 \
  --output-dir "assets/props/<pack>" \
  --labels "rock,crate,barrel,sign" \
  --reject-edge-touch

Use the bundled preview composer to verify placement over the base map:

python "${CLAUDE_SKILL_DIR}/scripts/compose_layered_preview.py" \
  --base "assets/map/<name>-base.png" \
  --placements "data/<name>-props.json" \
  --output "assets/map/<name>-layered-preview.png" \
  --report "assets/map/<name>-layered-preview.report.json" \
  --project-root "."

Expected Deliverables

For a baked raster map:

• assets/map/<name>.png
• optional <name>.prompt.txt
• optional data/<name>-collision.json or data/<name>-zones.json
• code changes that load/use the image

For a layered raster map:

• assets/map/<name>-base.png
• assets/map/<name>-base.prompt.txt
• optional assets/map/<name>-dressed-reference.png for prop planning
• assets/props/<prop>/prop.png folders, from one-by-one props or extracted prop packs
• data/<name>-props.json placement metadata
• data/<name>-collision.json and/or data/<name>-zones.json when gameplay needs them
• assets/map/<name>-layered-preview.png
• code changes that load the base, props, y-sorted renderables, collision, and zones

For a prop pack:

• raw generated sheet with solid #FF00FF background
• extracted assets/props/<prop>/prop.png files
• prop-pack.json extraction manifest
• no edge_touch entries for accepted props

Validation

Always validate what the chosen pipeline requires:

• map files exist and have expected dimensions
• transparent props contain alpha
• prop pack manifests parse and accepted props do not touch cell edges
• placement JSON parses and referenced prop files exist
• collision/zones JSON parses when present
• critical spawn, path, entrance, blocker, and zone points behave as expected
• flattened preview looks coherent at the game's camera size