Skip to content

0x0funky/agent-sprite-forge / skills/generate2dmap

generate2dmap

Verified

Plan and build 2D game maps and scenes - top-down and side-scrolling levels, tilemaps, prop packs, parallax backgrounds and HD-2D battle or story plates - with collision, navigation and reachability checks, environment motion, a playable HTML preview and export to Tiled, Godot 4 or LDtk. Map art (terrain, tiles, props, plates, parallax layers) is image generation by default, through generate2dmedia route_media.py (the API when a key is configured, else the local Codex or Grok CLI); map data (layout, collision, exits, spawns) is written as data. Use for any map, level, room, scene, background, terrain or prop-kit request. Not for characters, creatures, items or FX (generate2dsprite), character animation (video2dsprite), code-drawn tiles or maps (codeart2d, only on request) or calling an image or video API by itself (generate2dmedia).

FileKindSize
SKILL.mdskill md12.3 KB
agents/openai.yamlconfig513 B
references/background-scenes.mdmarkdown14.2 KB
references/engine-maps.mdmarkdown14.4 KB
references/hd2d-plates.mdmarkdown11.9 KB
references/hd2d-presentation.mdmarkdown9.8 KB
references/layered-map-contract.mdmarkdown21.3 KB
references/map-presets.mdmarkdown7.9 KB
references/map-strategies.mdmarkdown12.2 KB
references/parallax-backgrounds.mdmarkdown14.0 KB
references/prop-pack-contract.mdmarkdown15.0 KB
references/runtime/map-runtime.mjsscript81.1 KB
references/scene-preview.mdmarkdown14.6 KB
references/schemas/common.schema.jsonconfig12.9 KB
references/schemas/host.schema.jsonconfig18.8 KB
references/schemas/map.schema.jsonconfig134.0 KB
references/side-scroll-scenes.mdmarkdown14.3 KB
scripts/build_motion_mask.pyscript46.3 KB
scripts/build_scene_preview.pyscript93.5 KB
scripts/compose_layered_preview.pyscript92.2 KB
scripts/conform_background.pyscript25.4 KB
scripts/edit_locality_check.pyscript27.1 KB
scripts/export_godot.pyscript85.6 KB
scripts/export_ldtk.pyscript51.4 KB
scripts/export_tiled.pyscript45.5 KB
scripts/extract_platform_strip.pyscript29.4 KB
scripts/extract_prop_pack.pyscript63.2 KB
scripts/extract_scene_lights.pyscript43.3 KB
scripts/extract_terrain_tiles.pyscript54.1 KB
scripts/forge_av.pyscript46.6 KB
scripts/forge_core.pyscript86.4 KB
scripts/forge_hibit.pyscript18.8 KB
scripts/forge_index.pyscript24.8 KB
scripts/forge_matte.pyscript71.6 KB
scripts/forge_nav.pyscript95.5 KB
scripts/forge_schema.pyscript26.1 KB
scripts/hibit_plate.pyscript13.5 KB
scripts/map_bundle.pyscript82.6 KB
scripts/map_nav.pyscript31.9 KB
scripts/scene_layout_guide.pyscript22.1 KB
scripts/scene_motion.pyscript54.5 KB
scripts/validate_chunks.pyscript48.8 KB
scripts/validate_layout.pyscript47.1 KB
scripts/validate_parallax.pyscript29.6 KB
scripts/validate_stage.pyscript62.3 KB

references/map-presets.md

View on GitHub
# Map presets and engine targets

Starting values for common game shapes, written as map-bundle data (see [layered-map-contract.md](layered-map-contract.md) and [schemas/map.schema.json](schemas/map.schema.json)). They are data only: no tool reads a preset name, and every value is a starting point to adjust to the project's actual camera, actor size and engine. Measure the real actor before fixing `actorRadius`.

Rules of thumb used below:

- `actorRadius` is about 0.2 of the actor's displayed height in world pixels (a 64 px tall actor gets about 12); on a tile map about a third of a tile.
- `ySquash` is 1.0 for top-down maps and about 0.58 for HD-2D plates seen at a low camera angle.
- The navigation cell follows from the radius: `max(1, round(actorRadius / 2))` px. Corridors must be wider than `2 * actorRadius + cell` px.
- Exits at map borders use `activation: intent` with a `radius` of one to two actor radii; doors inside the map can use `crossing`.

## Genre presets

| Preset | Map mode | World and tiles | Collision | Portals and points | Tools after art |
|---|---|---|---|---|---|
| Tile RPG town or field | `tile_mode` | 16 or 32 px tiles; wang-corner terrain plus blob-47 paths | tile collision plus prop footprints; no walk regions | intent exits at the borders; spawns per entrance; anchors for shops and wells | map_bundle, map_nav, export_tiled |
| Painted exploration scene | `scene_mode` | one painted plate as an image layer; optional tile overlay | walk-region polygons traced on the plate; trunk and base footprints | intent exits along paths; interactions with `reach`; anchors with `approach` | map_bundle, map_nav, compose preview |
| HD-2D plate | `scene_mode` | painted plate, actors at plate scale | walk regions on the floor band; `ySquash` 0.58 | slots for party members; stage data in `stage` | map_bundle, map_nav, the HD-2D stage tools |
| Dungeon rooms | `room_chunk_mode` | fixed-size rooms (for example 15 x 11 tiles) | tile collision; door gaps match the sockets | crossing doors between rooms; one bundle per room | map_nav per room, the chunk validator across rooms |
| Tactics board | `grid_mode` | one material pixel per tile (`material_map` scale = tile size) | material classes per tile (`liquid`, `hazard`, `solid`); small radius so every free tile is a valid node | tall dressing uses `rear_shift_and_fade` | map_bundle, map_nav, export_tiled |
| Brawler belt | `side_scroll_mode` | a long plate; the belt is one walk-region polygon | belt polygon only; `ySquash` about 0.6 | intent exits at the belt ends | map_bundle, map_nav |
| Platformer | `side_scroll_mode` | platform kit tiles | `one_way` platforms in the material map | exits and checkpoints | map_bundle for data; jump and gap checks belong to the side-scroll layout validator (`validate_layout.py`), not to map_nav |
| Story or point-and-click scene | `baked_scene_mode` | one complete picture | a walk region for the floor | interactions with `reach`, anchors whose `approach` is where the actor walks before acting | map_bundle, map_nav |

`map_nav.py` checks top-down movement. Platformer reachability depends on jump arcs, which it does not model; for those maps it still checks the data, the `one_way` direction (blocked only when moving down onto it) and the exits. `one_way` is a side-scroll class; bundles carry no view mode, so the rule applies to every map and top-down presets never use it.

### Snippets

Tile RPG field (16 px tiles, actor about 16 px tall on screen):

```json
{"tile_size": [16, 16], "world": {"width": 640, "height": 480, "unit": "px"},
 "collision": {"actorRadius": 5, "ySquash": 1.0},
 "portals": [{"id": "exit-east", "rect": [632, 192, 8, 48], "to": "route-1:arrive-west", "activation": "intent",
              "travelDirection": [1, 0], "radius": 8, "entranceByFrom": {"route-1": "arrive-east"}}]}
```

HD-2D plate (1920 x 1080 plate, actor about 140 px tall):

```json
{"world": {"width": 1920, "height": 1080, "unit": "px"},
 "layers": [{"name": "plate", "kind": "image", "image": "plate.png"}, {"name": "props", "kind": "objects"}],
 "collision": {"actorRadius": 28, "ySquash": 0.58,
               "walkRegions": [{"polygon": [[120, 760], [1800, 760], [1880, 1040], [40, 1040]]}]}}
```

Tactics board (12 x 10 tiles of 32 px; materials one pixel per tile):

```json
{"tile_size": 32, "world": {"width": 384, "height": 320, "unit": "px"},
 "collision": {"actorRadius": 6},
 "material_map": {"image": "board-materials.png", "materials": {
   "floor": {"class": "decor", "color": "#000000"}, "pit": {"class": "hazard", "color": "#ff0000"},
   "shallow": {"class": "liquid", "color": "#00ffff", "walkable": true}, "pillar": {"class": "solid", "color": "#808080"}}}}
```

## Engine targets

| Target | Hand over | Produced by | What is verified |
|---|---|---|---|
| Tiled 1.10 or later | `map.tmj`, one `.tsx` per tileset, `props.tsx`, `images/` | `export_tiled.py export` | the written files re-render to the bundle's reference render with 0 px difference (built-in reader; pytiled-parser when installed); Tiled GUI not verified, including terrain brushes on the exported wangsets |
| Phaser 3 | `map.embedded.tmj` (tilesets inlined) and `images/` | `export_tiled.py export --embedded-variant` | the same re-render check; Phaser itself is not run by the tests |
| Godot 4.3 or later | a `.tres` TileSet and a `.tscn` scene | `export_godot.py` ([engine-maps.md](engine-maps.md)) | re-read by the exporter's own Godot text parser; editor import not verified |
| LDtk 1.5.3 | an `.ldtk` project | `export_ldtk.py` ([engine-maps.md](engine-maps.md)) | required fields against a snapshot of the LDtk schema; editor not verified |
| Custom engine (Canvas, Three.js, Pixi, others) | `map-bundle.json` and `nav-grid.json` (its `runtimeInputs` carry the tile collision and the material grid) | `map_bundle.py`, `map_nav.py check` | collision and reachability follow the forge_nav rules ([layered-map-contract.md](layered-map-contract.md)); [runtime/map-runtime.mjs](runtime/map-runtime.mjs) is the JavaScript collision query that mirrors them, loaded with `createMapRuntime(bundle, navGrid.runtimeInputs)` |
| Unity | a Tiled export through a third-party importer, or a reader of `map-bundle.json` | not provided here | not verified |

`nav-grid.json` (from `map_nav.py check`) lists one character per grid node: `#` for a blocked node, otherwise a hex digit of its open moves (east 1, south 2, west 4, north 8; south is +y). Node `(col, row)` sits at `((col + 0.5) * cell, (row + 0.5) * cell)`. A runtime can path-find on it directly; `blockedRects` lists the blocked nodes as disjoint rectangles in world pixels.

A game that walks the bundle with [runtime/map-runtime.mjs](runtime/map-runtime.mjs) needs two inputs the module cannot read itself, because it reads no files: the collision of every placed tile (the tileset manifests' `tiles[].collision`) and the material map's pixels. `nav-grid.json` carries both, read by forge_nav, as `runtimeInputs`: `tileSolids` (world solids, `source` names the layer) and `materialGrid` (bit planes of the blocking and `one_way` pixels; `null` without a material map). Pass that object as the options, `createMapRuntime(bundle, navGrid.runtimeInputs)`. Without it, `createMapRuntime` throws a `TypeError` for a bundle with a tiles layer or a `material_map` rather than let the actor walk through tile walls and blocking materials; `{ignoreMaterialMap: true}` walks without the material map on purpose. Run `map_nav.py check` again whenever the bundle, a tileset or the material map changes.

```bash
python "<skill-dir>/scripts/map_nav.py" check --bundle map/map-bundle.json --output-dir map/qa/nav
python "<skill-dir>/scripts/export_tiled.py" export --bundle map/map-bundle.json --output-dir map/tiled --embedded-variant
python "<skill-dir>/scripts/export_tiled.py" verify --map map/tiled/map.tmj --bundle map/map-bundle.json --reader pytiled
```

The `--reader pytiled` check needs `python -m pip install pytiled-parser`; without it the tool prints that command and exits.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall