# generate2dmap

Adopt this skill: https://proskills.md/skills/other/0x0funky-agent-sprite-forge-skills-generate2dmap

Page: https://proskills.md/skills/other/0x0funky-agent-sprite-forge-skills-generate2dmap
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/generate2dmap/SKILL.md
size: 8000
upstream: https://github.com/0x0funky/agent-sprite-forge/blob/main/skills/generate2dmap/SKILL.md

```text
---
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.

1. `map_mode`: `tile_mode` | `scene_mode` | `side_scroll_mode` | `grid_mode` | `room_chunk_mode` | `baked_scene_mode`
2. `visual_model`: `baked_raster` | `layered_raster` | `tilemap` | `layered_tilemap` | `parallax_layers`
3. `runtime_object_model`: `none` | `separate_props` | `platform_objects` | `y_sorted_props` | `interactive_scene_objects` | `foreground_occluders` | `scene_hooks`
4. `collision_model`: `none` | `coarse_shapes` | `precise_shapes` | `tile_collision` | `polygon_walkmesh` | `trigger_zones`
5. `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](references/map-strategies.md) when the pipeline choice is not obvious. Read [references/layered-map-contract.md](references/layered-map-contract.md) before implementing a layered raster map. Read [references/prop-pack-contract.md](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:

1. Save the base/background image first.
2. 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.
3. In the next `image_gen` prompt, explicitly say to use the visible image immediately above as the visual reference.
4. Describe concrete features from the viewed image that must be preserve
```

## File: README.md
upstream: https://github.com/0x0funky/agent-sprite-forge/blob/main/README.md

```text
# Agent Sprite Forge

Languages: [English](./README.md) | [繁體中文](./README.zh-TW.md) | [简体中文](./README.zh-CN.md) | [日本語](./README.ja.md) | [한국어](./README.ko.md)

<p align="center">
  <img src="./src/banner.png" alt="Agent Sprite Forge banner" width="900" />
</p>

<p align="center">
  <a href="https://trendshift.io/repositories/42911?utm_source=repository-badge&amp;utm_medium=badge&amp;utm_campaign=badge-repository-42911" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/repositories/42911" alt="0x0funky%2Fagent-sprite-forge | Trendshift" width="250" height="55"/></a>
</p>

<p align="center">
  <img src="./src/v040/asf-v040-teaser.gif" alt="Agent Sprite Forge 0.4 teaser" width="720" />
  <br />
  <em>0.4 launch teaser: every frame is real ASF output.</em>
</p>

## One still → a whole game-ready sprite set

<p align="center">
  <strong>Approve one generated still. Get every action of the character, keyed, looped, timed and exported for your engine.</strong>
</p>

<p align="center">
  Agent skills for <strong>Claude Code</strong> (plugin), <strong>Codex</strong> and <strong>Grok</strong>. The agent generates a master still with the best image route you have, makes one image-to-video clip per action from it, and deterministic Python tools gate, key, register, loop, retime, finish and package every action for Godot, Aseprite or a web game.
</p>

<table>
  <tr>
    <td align="center" width="30%">
      <img src="./src/v040/aria-master.png" alt="Aria, the approved master still: a young swordswoman with short dark hair, a teal cloak and a long red scarf, side view facing right" width="250" />
      <br />
      <strong>1. One approved master still</strong>
      <br />
      <sub>Generated by the local Codex CLI (<code>image_gen</code>), take 1 of 3.</sub>
    </td>
    <td align="center" width="70%">
      <img src="./src/v040/aria-set.gif" alt="Aria's six actions at real timing: idle, walk and run loops; attack, jump and hurt one-shots" width="600" />
      <br />
      <strong>2. Six actions, one image-to-video clip each</strong>
      <br />
      <sub>Grok image-to-video (local CLI), soft-matte keyed, registered, loops picked by measurement, one-shots retimed to game speed, HD finish with the colour lock. Real timing.</sub>
    </td>
  </tr>
</table>

<p align="center">
  <img src="./src/v040/aria-in-scene.gif" alt="Aria runs across a generated meadow, stops for a sword thrust and runs on" width="860" />
  <br />
  <em>3. In a scene: the packaged run, attack and idle over a generated background. The run speed is measured from the contact foot, so the feet do not slide. Every frame comes from the 2026-10-06 live run; nothing is mocked up.</em>
</p>

<p align="center">
  <a href="#new-pixel-looks-1x-sprites-that-follow-a-reference">Pixel looks</a> ·
  <a href="#new-hibit-real-pixel-art-from-flat-ai-art">Hibit style</a> ·
  <a href="#whats-new-in-04--the-big-upgrade">What's new</a> ·
  <a href="#quickstart">Quickstart</a> ·
  <a href="#routes-and-providers">Routes and providers</a> ·
  <a href="#pipeline-master--set--finish--export">Pipeline</a> ·
  <a href="#maps">Maps</a> ·
  <a href="#showcase-games-made-with-agent-sprite-forge">Showcase</a> ·
  <a href="#tools">Tools</a>
</p>

## New: pixel looks, 1x sprites that follow a reference

<p align="center">
  <img src="./src/pixel-looks/battle.gif" alt="A fight on a 384x216 plate: a swordsman walks in and is struck by a skeleton knight, strikes back, a mage casts and the knight falls, a frost dragon roars and lunges, and after the last blow it falls and the swordsman raises his sword" width="768" />
  <br />
  <em>A whole fight from pixel-look sprites, rendered at 1x and shown at 2x: four 1x characters (masters of 33x55 to 87x86) and 14 sets with 168 drawings read back from image-to-video clips. The plate behind them is a generated painting brought down to 384x216 and 40 colours. The white hit flashes and the knight's fade are the demo's; nothing else is added.</em>
</p>

An image model asked for pixel art paints a picture of pixels: blocks of uneven size (15 to 30 px in the picture below), 88,410 colours in one small figure, soft edges. Shrinking it does not help: resized plainly to the sprite's size it still has 1,033 colours. Hibit gets round this by never asking for pixel art. **Pixel looks** go the other way, for the classic small sprite that follows a look you like: the look is never described in words, one sprite you like is the reference for the whole cast, and the picture the model paints is read back onto a real grid. `pixel_look.py master` finds the picture's own grid, takes one flat colour from every block, keeps the figure's proportions, brings the colours down to a palette and closes the outline by rule. What comes out can be counted: 33x55 pixels, 48 colours, alpha 0 or 255, a 2.5 KB PNG.

<table>
  <tr>
    <td align="center" width="40%">
      <img src="./src/pixel-looks/kael-picture.png" alt="The picture an image model painted of a silver-haired swordsman in a dark coat, on a flat green ground: it looks like pixel art" width="340" />
      <br />
      <strong>What the image model painted</strong>
      <br />
      1254x1254 px. The figure alone has 88,410 colours and its blocks are 15 to 30 px: no grid fits it.
    </td>
    <td align="center" width="30%">
      <img src="./src/pixel-looks/kael-plain-resize.png" alt="The same picture resized plainly to 33x55 and shown at 7x: a smudged eye, uneven edges and green specks at the hair" width="259" />
      <br />
      <strong>Resized plainly to 33x55</strong>
      <br />
      Nearest sampling, shown at 7x: 1,033 colours, the ground's green left in 3 cells. Bilinear gives 1,275 colours and 413 soft pixels.
    </td>
    <td align="center" width="30%">
      <img src="./src/pixel-looks/kael-master.png" alt="The 1x sprite made from the same picture, shown at 7x: clean cells, a closed outline, a clear face" width="259" />
      <br />
      <strong><code>pixel_look.py master</code></strong>
      <br />
      The same picture read on its own grid, shown at 7x: 33x55, 48 colours, no soft pixel.
    </td>
  </tr>
</table>

<p align="center">
  <img src="./src/pixel-looks/closeup.png" alt="The same part of the face twice: in the picture the blocks have uneven sizes and soft, stained edges; in the sprite every cell is one flat colour" width="742" />
  <br />
  <em>The same part of the face: the picture at 2x (left) and the sprite at 40x (right).</em>
</p>

<p align="center">
  <img src="./src/pixel-looks/cast.gif" alt="The swordsman, the mage, the skeleton knight and the frost dragon on one ground line; each idles and plays one action in turn: a sword strike, a cast, a strike, a roar" width="808" />
  <br />
  <em><strong>The cast follows the first sprite.</strong> Every further character is drawn beside the first sprite in one picture (<code>ask-cast</code>, <code>cast</code>), so it keeps the pixel size and stands as tall: a mage, a skeleton knight and a frost dragon, 48 colours each.</em>
</p>

<p align="center">
  <img src="./src/pixel-looks/sets.gif" alt="The swordsman's idle, walk, attack, hurt and victory sets and the dragon's roar, lunge and fall, each with its number of drawings" width="812" />
  <br />
  <em><strong>Poses, views and motion from the master.</strong> A pose is the master reproduced with one change (the sword pose: 217 cells changed, 91% of the master kept); a view is drawn beside the master. Motion comes from an image-to-video clip of that sprite: <code>pixel_motion.py</code> reads every frame back on the sprite's lattice and palette (the attack: 21 drawings picked from 145 video frames). The number is the drawings of each set.</em>
</p>

| Measured on the run (2026-11-12) | |
|---|---:|
| The swordsman's generated picture (the figure) | 1254x1254, 88,410 colours, blocks 15-30 px |
| The same picture resized to 33x55: nearest / bilinear | 1,033 colours / 1,275 colours and 413 soft pixels 
```
