0x0funky/agent-sprite-forge / skills/generate2dmap
generate2dmap
VerifiedPlan 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).
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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 471k | Updated | Claude CodeCodex | Verified | Install |
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |