generate2dmap

name generate2dmap description Generate and revise production-oriented 2D game maps with built-in image generation as the default visual asset source, choosing a visual model, runtime object model, collision model, art direction, and engine/export target. Use when Codex needs to create or integrate RPG maps, monster-taming maps, tactical arenas, battle backgrounds, side-scroller/parallax scenes, tilemaps, layered raster maps, clean HD hand-painted maps, pixel-inspired maps, prop packs, collision zones, walkable areas, or map previews. Generate2dmap Overview Build the smallest playable map bundle that satisfies the game. Start by choosing a user-facing map_mode , then map it to the lower-level pipeline axes. Do not treat a map as only one image unless the user explicitly asks for a flat visual background. map_mode : tile_mode | scene_mode | side_scroll_mode | grid_mode | room_chunk_mode | baked_scene_mode visual_model : baked_raster | layered_raster | tilemap | layered_tilemap | parallax_layers runtime_object_model : none | separate_props | platform_objects | y_sorted_props | interactive_scene_objects | foreground_occluders | scene_hooks collision_model : none | coarse_shapes | precise_shapes | tile_collision | polygon_walkmesh | trigger_zones 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 playable pipeline from the existing game, camera, collision needs, map scale, and editing needs. For requests that imply a playable game map, level, stage, room, prototype, or engine scene, do not ship a single baked image as the runtime map unless the user explicitly asks for a flat background only. A baked image may be a background, reference, or preview artifact, but the playable deliverable must expose gameplay geometry and objects as separate layers, props, tile/object data, collision, zones, or engine-native scene nodes. This skill is for scenes and maps. Do not generate character, enemy, boss, projectile, NPC, player, or animation sprite assets as map deliverables. The map may include scene hooks such as player spawns, actor spawn marker metadata, patrol/encounter zones, arena entrances, gates, exits, and camera triggers, but actor artwork, projectiles, and animations belong in $generate2dsprite . 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. Map Modes Use map_mode as the first decision. It is a product-level preset that chooses the initial pipeline axes and expected deliverables: tile_mode : editable tile/grid maps for RPGs, monster-taming games, platformers, tactical maps, factory games, and engines/editors that already use tiles. Default axes: tilemap or layered_tilemap + interactive_scene_objects + scene_hooks + tile_collision + trigger_zones . scene_mode : base map plus separate props for tower defense, survivors-like arenas, cozy demos, top-down adventure scenes, and visual showcase maps. Default axes: layered_raster + separate_props or y_sorted_props + interactive_scene_objects + scene_hooks + precise_shapes + trigger_zones . side_scroll_mode : parallax side-scroller stages for action platformers, runners, Metroidvania rooms, side-view shooters, and beat-em-up stages. Default axes: parallax_layers + platform_objects + interactive_scene_objects + foreground_occluders + scene_hooks + precise_shapes . grid_mode : rule-heavy grid scenes for tactical RPGs, factory/automation games, board/card battlers, build grids, and terrain-cost maps. Default axes: layered_tilemap or tilemap + interactive_scene_objects + scene_hooks + tile_collision or grid metadata. room_chunk_mode : modular rooms/chunks for roguelikes, Metroidvania rooms, dungeon rooms, and procedural level assembly. Default axes: layered_tilemap or parallax_layers or layered_raster + object layers + exits/connection metadata + collision. baked_scene_mode : fixed battle backgrounds, title/menu screens, boss-room concept art, visual novel scenes, point-and-click backgrounds, or other explicitly flat/non-editable scenes. Default axes: baked_raster + none or coarse_shapes . When the mode and lower-level axes disagree, the mode's playable/editable contract wins. For example, side_scroll_mode always needs separate collision and platform/object data even if it also produces a beautiful full-width preview image. Genre Routing When the user gives a genre instead of a technical map mode, choose the mode conservatively: Pokemon-like / monster-taming RPG / top-down RPG town or route -> tile_mode with optional separate props, encounter zones, exits, NPC spawn markers, and collision. Tower defense / Kingdom Rush-like -> scene_mode with path metadata, build slots, props, collision/blockers, spawn/exit hooks, and optional engine scene scaffold. Survivors-like / arena survival -> scene_mode or tile_mode depending on map scale; keep obstacles sparse, define spawn rings/zones, camera bounds, and collision separately. Mega Man-like / side-view action platformer / runner / Metroidvania side room -> side_scroll_mode . Beat-em-up / brawler -> side_scroll_mode with a walkable belt polygon instead of jump-platform geometry; use parallax/background depth plus props, enemy wave zones, and camera bounds. Tactical RPG / strategy grid / factory automation / board-like game -> grid_mode . Roguelike dungeon / modular Metroidvania / procedural room assembly -> room_chunk_mode . Visual novel, title screen, point-and-click, boss arena concept, or non-playable showcase -> baked_scene_mode unless gameplay/editability is requested. Image Generation First This skill is image-generation-first for visual assets. Use built-in image_gen as the default creative art source for base maps, in-world reference mockups, dressed references, stage references, prop sheets, prop sprites, tileset art, parallax layers, battle backgrounds, and other visible map assets. The agent must write the creative image prompts itself. Do not use scripts to generate creative prompts or to procedurally draw final visual art. Scripts may assemble, slice, chroma-key, crop, validate, compose previews, emit JSON metadata, and wire image-generated assets into engine-native files such as Godot .tscn scenes. Save every manually written image-generation prompt next to the generated asset as <asset>.prompt.txt or in an explicit manifest field. Do not leave accepted generated assets with empty prompt metadata when the run creates new visual assets. Only use procedural drawing or scripted placeholder art when the user explicitly asks for placeholders, test fixtures, debug maps, or engine scaffolding without final art. If using an engine target such as Godot_TileMap , generate or reuse the visual tileset art first, then use scripts/code only to build tile layers, collision, zones, and scene wiring. Visual Reference Handoff When generating an in-world reference mockup from an existing generated base/background, the prior image must be treated as an active visual reference, not just a file path or loose style hint: Save the base/background image first. Immediately before the next image_gen call, make that exact image visible in conversation context. If it is a local file, call view_image on the saved file. In the next image_gen prompt, explicitly say to use the visible image immediately above as the visual reference. Describe concrete features from the viewed image that must be preserved, such as camera framing, horizon, road or water shapes, terrain boundaries, entrance/exit direction, major silhouettes, empty pads, and landmark positions. Generate an in-world reference mockup, not an annotated diagram. Do not draw circles, arrows, outlines, labels, numbers, UI callouts, text, captions, legends, highlighted boxes, highlighted zones, measurement lines, or explanatory overlays. Render proposed visible gameplay objects as natural game-world objects or subtle in-world blockout geometry. Do not draw non-visual metadata such as spawn points, triggers, camera bounds, or patrol hints; write those later as structured scene-hook metadata. Keep reference mockups sparse enough to drive final asset production. Unless the user explicitly asks for a dense concept sheet, include at most 9 distinct visible runtime prop/object candidates in the mockup. Repeated instances of the same platform, lamp, crate, hazard, pickup, or gate count as one candidate and can be repeated later in placement metadata. Do not rely on a path string, filename, or generic wording like "based on the map" as the reference handoff. If the base/background is not visible in context, stop and make it visible before generating the dressed reference or stage reference. Layer Separation Contract For any playable or editable layered map, the first generated base/background/foundation image must not bake in objects that the runtime should control separately. This applies across perspectives and styles: top-down RPG maps, monster-taming maps, tactical arenas, tower-defense lanes, side-view platformers, parallax stages, tile/editor workflows, clean HD, pixel-inspired, and retro pixel art. The base/background/foundation layer may contain only stable non-interactive foundation art: top-down or 3/4 maps: ground material, paths, roads, water, cliffs, low terrain markings, floor patterns, and terrain boundaries tactical or tower-defense maps: ground, lanes, roads, build pads, lane markings, terrain zones, and non-interactive floor detail side-view stages: sky, far/mid scenery, distant buildings, distant terrain silhouettes, atmosphere, and non-colliding depth tilemaps: tileset art and tile layers arranged as editable engine data, not a flattened full-scene background The base/background/foundation layer must not contain runtime-controlled objects unless the user explicitly asked for a single baked image: tall props, buildings, trees, rocks, crates, signs, doors, gates, pickups, chests, checkpoints, hazards, traps, turrets, tower objects, ladders, foreground occluders, destructibles, actors, enemies, NPCs, bosses, player characters, UI, labels, or any object that needs collision, interaction, replacement, reuse, y-sorting, animation, engine editing, or independent render order If a generated base/background already contains those runtime objects, do not use it as the runtime base. Regenerate a cleaner foundation-only base or demote that image to a concept/reference artifact. The next in-world reference mockup is where proposed objects may appear, and the final runtime must still use separate generated props, platform objects, object layers, tile layers, collision, zones, and scene-hook metadata as appropriate. Parameter Contract User-facing parameters may be stated in natural language: map_mode : tile_mode | scene_mode | side_scroll_mode | grid_mode | room_chunk_mode | baked_scene_mode map_kind : overworld | town | dungeon | shrine | arena | battle_bg | side_scroller | side_view_action | platformer | metroidvania | brawler | tower_defense | survivors_like | tactical | factory | card_board | room_chunk visual_model : baked raster | layered raster | tilemap | layered tilemap | parallax size : pixel dimensions, tile dimensions, or camera-relative size stage_canvas : exact pixel dimensions and aspect ratio for side-scroll/parallax layers, references, and previews stage_segment_count : number of camera-width chunks for a side-scroll stage perspective : top-down | 3/4 top-down | side-view | isometric-like art_style : clean_hd | pixel_inspired | retro_pixel | hand_painted | project-native visual_asset_source : image_gen | existing_assets | procedural_placeholder collision_precision : none | coarse | precise | tile | walkmesh tile_generation : none | terrain_tile_bundle | autotile_set | engine_native_tileset platform_strategy : platform_rects_with_shared_tiles | platform_strip | tilemap | custom_terrain_chunks prop_generation : none | one_by_one | prop_pack_2x2 | prop_pack_3x3 | prop_pack_4x4 | platform_strip_1x3 | platform_strip_1x4 | custom_wide_pack output_format : PNG only | layered preview | manifest JSON | engine-native map data When unspecified: Use image_gen as the visual asset source. Infer map_mode from genre and editing needs before selecting lower-level axes. Use tile_mode for Pokemon-like, top-down RPG, monster-taming, editor/grid-perfect, or tilemap requests. Use scene_mode for tower defense, survivors-like, cozy/top-down showcase maps, and base-map-plus-props requests. Use side_scroll_mode for side-scrollers, platformers, runners, side-view action, brawlers, Metroidvania side rooms, Mega Man-like, Castlevania-like, Contra-like, and parallax background requests. For side_scroll_mode , choose a canonical stage_canvas before image generation. Use the project camera/viewport aspect when available; otherwise default to a 16:9 side-scroller canvas such as 1536x864 . All primary parallax plates, stage references, and previews must preserve this same size/aspect. For playable side_scroll_mode , choose stage_segment_count before image generation. Default to 2 camera-width segments for a normal playable scrolling level. Use 1 only for explicit one-screen rooms, boss arenas, title-like scenes, or fixed battle rooms; use 3 or more only when the user asks for a longer stage or the existing game already has that scope. For playable side_scroll_mode , default platform_strategy to platform_rects_with_shared_tiles : write platform rectangles or engine-native platform objects as the gameplay source of truth, then skin them with a shared generated platform tile/strip library. Do not rely on a generated background or generic prop pack for platform shape. Use grid_mode for tactical RPGs, factory/automation maps, board/card battlers, build grids, and terrain-cost maps. Use room_chunk_mode for modular rooms, roguelike rooms, procedural room assembly, or Metroidvania room-chunk planning. Use baked_scene_mode only for non-playable visual scenes or explicitly flat images. Use baked_raster + coarse_shapes only for battle backgrounds, title/menu scenes, cutscenes, decorative backdrops, non-playable previews, or when the user explicitly asks for a single flat image. Use layered_raster + y_sorted_props + precise_shapes for top-down RPG exploration with tall props, occlusion, interactables, or reusable props; the base must be foundation-only and the props/interactables must remain separate. Use tilemap or layered_tilemap only when the engine/editor already uses tiles or the user asks for editable tiles; do not flatten gameplay objects into one background image. Use parallax_layers + platform_objects + interactive_scene_objects + scene_hooks + precise_shapes for playable side-view scrolling stages, platformers, runners, shooters, and horizontal action scenes; the parallax/background image is scenery-only and is not the runtime map by itself. Use square prop packs only when 4 or more compact small/medium static props share one style and fit comfortably inside equal square cells. Use one-by-one, platform strips, tile/object layers, or custom wide packs for hero props, buildings, gates, irregular large props, wide/tall props, platforms, terrain chunks, bridges, walls, ladders, long hazards, animated props, or props needing strong identity or collision alignment. For side-scroll platformers, treat platforms, floors, ledges, bridges, walls, slopes, ladders, long hazards, doors, gates, checkpoints, and exits as structural stage objects, not decorative props. Compact prop packs are for optional dressing and pickups only. Use clean_hd for generated exploration maps unless the project or user asks for pixel art. This means clean hand-painted top-down 2D RPG game map, HD game asset style, sharp readable terrain shapes, low texture noise, and no chunky pixels. Use pixel_inspired only when the user wants a pixel-adjacent look without retro chunkiness. Use retro_pixel only when the user explicitly asks for 16-bit, retro JRPG, or classic pixel-art maps. Workflow 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. Choose the pipeline axes. Choose map_mode first. Use the genre routing table when the user describes a game type instead of a technical map format. Select visual_model , runtime_object_model , collision_model , and engine_target . If the request is for a playable map, stage, level, room, prototype, or game scene, choose a pipeline with explicit runtime objects. Do not downgrade to baked_raster unless the user asked for a background-only image. If the request implies a playable side-view scrolling/action stage, such as a side-scroller, platformer, runner, shooter, brawler, scrolling combat stage, Megaman-like stage, Castlevania-like stage, or Contra-like stage, lock the map pipeline to parallax_layers + platform_objects + interactive_scene_objects + scene_hooks + precise_shapes unless the engine already requires a tilemap. Select art_style . Prefer readable gameplay shapes over decorative texture density. Select visual_asset_source . Default to image_gen ; use existing_assets only when the project already has suitable art; use procedural_placeholder only when explicitly requested. Treat hybrid as a result of combining axes, not as a primary category. Produce assets. Write the creative prompts manually and use built-in image_gen for visible map art unless the user explicitly chose existing assets or procedural placeholders. For baked raster maps, generate one background with built-in image_gen , or edit/use an existing image when supplied, then add optional collision/zones metadata. For playable or editable layered maps, generate a foundation-only base/background first. The base must not contain runtime-controlled props, interactables, hazards, doors, gates, pickups, actors, or foreground occluders. If it does, regenerate or demote it to a reference artifact. For layered raster maps, generate a ground-only/foundation-only base map first. Then perform the visual reference handoff and generate an in-world dressed reference mockup from the visible base before making final props and placements. For tilemaps, generate or reuse tileset art first, then follow the engine/editor format for layers, objects, collision, and scene files. Do not script-draw the tileset as the final art source, and do not flatten object layers into a single runtime image. For grid_mode , generate or reuse grid/tileset visual art first, then write cell metadata such as walkable/buildable flags, move cost, terrain effects, resource nodes, and object layers. For room_chunk_mode , define chunk dimensions, exits, connection sockets, collision contract, and spawn/trigger metadata before final art assembly. Chunks must be reusable and validated at their seams. For playable side-view scrolling/action stages, define the canonical stage_canvas , stage_segment_count , stage_length , and platform_strategy before generating art. Do not ask image generation for one ultra-wide full level. Generate per-segment or loopable scenery-only parallax plates first: sky , far_bg , mid_bg , near_bg , and optional foreground_overlay . Every primary parallax layer must use the same pixel dimensions, aspect ratio, camera framing, horizon line, and top-left anchor as the stage_canvas ; do not accept mismatched image sizes that require guesswork to stack. Do not treat one full-width background image as a complete side_scroll_mode background stack unless the user explicitly asks for a flat/non-parallax background. These parallax passes must not contain playable foreground platforms, walkable floors, terrain chunks, hazards, pickups, doors, gates, checkpoints, crates, fences, spikes, or other runtime objects. Then perform the visual reference handoff and generate an in-world stage reference mockup that visually places up to 9 distinct intended platform/object candidates before generating final separate scene objects and metadata. If a side-view background already contains collidable-looking foreground geometry, walkable floors, or reusable gameplay props, reject it as a runtime background and regenerate a cleaner scenery-only background before continuing. Treat the reference mockup as a checkpoint, not a deliverable. Do not stop after generating it. After the relevant dressed-reference or stage-reference exists, inspect it and continue into the post-reference object production gate. Do not present a rerunnable script that creates the whole art pack as the main solution unless the user asked for procedural placeholder art. Build metadata. Store prop placement, player spawns, actor spawn marker metadata, interactable scene objects, blockers, walk bounds, encounter zones, exits, camera bounds, and triggers as structured data. For walkable cells or actor lanes with visible dressing, classify prop occlusion as low , tall , or foreground ; record an actor-safe area and an occupant policy such as none , rear_shift , fade , rear_shift_and_fade , or hide . Do not rely on render priority alone to keep actors readable. For grid_mode , store grid dimensions, cell size, tile ids, terrain types, walkable/buildable flags, movement cost, collision, resource nodes, and object/entity slots. For room_chunk_mode , store chunk id, size, entrances/exits, connection sockets, collision, spawn markers, camera bounds, and validation hints for seam alignment. For side_scroll_mode , store stage_canvas , stage_segment_count , stage_length , segment ids, parallax layer source size, display size, anchor, render order, scroll factors, loop/repeat policy, shared platform/object library ids, camera bounds, platform collision, hazards, exits, checkpoints, and actor spawn marker metadata. Keep collision independent from pixels unless the target engine explicitly uses tile collision. 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. For any playable map with tall props on walkable space, produce or inspect an actor-in-place preview at the real gameplay camera. The actor's head, torso, weapon/action silhouette, selection state, and destination/path cues must remain readable. Slight foot overlap is acceptable; losing the actionable silhouette is not. For side_scroll_mode , reject or normalize mismatched primary parallax layer sizes before runtime integration. The stage reference and QA preview must match stage_canvas exactly. Deterministic resizing/cropping/padding is allowed only as a normalization step on generated art, not as a way to invent missing art. Terrain Tile Bundles For a fixed grid, tactical board, card-board arena, or project-native 2.5D tile mesh, prefer tile_generation=terrain_tile_bundle when each cell needs one of several opaque surface textures. Keep tile mesh/collision separate from the generated surface art. Generate an atlas with one terrain family per row and 2-4 variants per row. Use a geometry layout guide when exact cells matter. Require full-bleed top-down orthographic surfaces with no gutters, labels, borders, perspective, tile thickness, actors, tall props, or UI. Use edge_policy=isolated when visible gaps or individual tile meshes separate cells. Use seamless only when adjacent tiles must visually join. Preserve one surface scale, lighting direction, grain density, and palette relationship across every terrain family. Extract and validate the atlas with scripts/extract_terrain_tiles.py . The script writes portable relative paths, per-variant luminance/contrast metrics, variant-difference QC, material hints, and a Godot mesh-top runtime contract.