@inneranimalmedia/agentsam-sdk 2.6.4 → 2.6.7

package/skills/grok-generate2dmap/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: generate2dmap
+description: >
+  Generate production-oriented 2D game maps with `imagine_text_to_image`: RPG/top-down maps,
+  side-scroller parallax stages, tilemaps, layered raster maps, prop packs,
+  collision zones, and walkable areas. Use when building browser games that
+  need real map art (not pure code-drawn tiles), layered props, or map
+  collision metadata. Triggers on "map", "level", "stage", "tilemap",
+  "overworld", "dungeon", "side scroller background", "prop pack", "2D map".
+metadata:
+  short-description: "2D game maps: layered art, props, collision metadata"
+user-invocable: false
+---
+
+# Generate2dmap
+
+## App-builder / Grok environment
+
+| Item | Value |
+| --- | --- |
+| Skill dir / scripts | `.grok/skills/generate2dmap/`, run as `python3 .grok/skills/generate2dmap/scripts/<script>.py …` |
+| Image tools | `imagine_text_to_image` / `imagine_image_to_image` (path-based; see **`imagine`**); inspect output with `read_file` on the PNG path (not Codex view_image) |
+| Generated image path | `imagine_text_to_image` → sandbox `file_path` → copy into `assets/map/`; Pillow is preinstalled |
+| Default `engine_target` | `raw_canvas` or `Phaser` for this TanStack browser sandbox — only use Godot/Unity/Tiled when the user explicitly wants those exports |
+| Related skills | **`generate2dsprite`** (character/FX sprites; prop packs still use this skill's extract script), **`building-games`**, **`imagine`** |
+
+## Decide the pipeline first
+
+Build the smallest playable map bundle that satisfies the game: choose a
+product-level `map_mode`, then the lower-level axes (`visual_model`,
+`runtime_object_model`, `collision_model`, `engine_target`).
+
+- `tile_mode` — editable tile/grid maps: Pokemon-like routes, top-down RPG towns, platformer tilemaps, or any project already on Tiled/LDtk/Godot/Unity/Phaser tilemaps.
+- `scene_mode` — foundation base plus separate props: tower defense, survivors-like arenas, cozy top-down showcase maps.
+- `side_scroll_mode` — parallax side-scroller stages: Mega Man-like, action platformers, Metroidvania rooms, runners, brawlers.
+- `grid_mode` — rule-heavy grids: tactical RPGs, factory/automation, board/card battlers, build grids.
+- `room_chunk_mode` — modular rooms/chunks: roguelike dungeons, Metroidvania networks, procedural assembly.
+- `baked_scene_mode` — explicitly flat, non-playable scenes only: title/menu screens, battle backdrops, visual-novel scenes, concept art.
+
+Use user-specified parameters when present; otherwise infer the lightest playable
+pipeline from the existing game, camera, collision needs, map scale, and editing
+needs. When mode and axes disagree, the mode's playable/editable contract wins.
+Genre routing, per-mode axis defaults, presets, and the escalation heuristic are in
+`references/map-strategies.md` — read it whenever the choice is not obvious.
+
+**A playable map is never one baked image.** For any request implying a playable
+map, level, stage, room, prototype, or engine scene, the deliverable must expose
+gameplay geometry and objects as separate layers, props, tile/object data,
+collision, zones, or engine-native scene nodes. A baked image may be a background,
+reference, or preview artifact — never the runtime map — unless the user
+explicitly asked for a flat background only.
+
+**Scenes and maps only.** Do not generate character, enemy, boss, NPC, player,
+projectile, or animation sprites here; those belong to `$generate2dsprite`. Maps
+carry scene hooks (spawn markers, patrol/encounter zones, arena entrances, gates,
+exits, camera triggers) as **metadata**, not as drawn art.
+
+## Art comes from image generation, and you write the prompts
+
+- `imagine_text_to_image` is the default art source for base maps, parallax plates,
+  references, prop sheets, and tileset art. Default `art_style` is `clean_hd`
+  (hand-painted HD, sharp readable shapes, low texture noise, no chunky pixels);
+  use `pixel_inspired` or `retro_pixel` only when asked.
+- **Write every creative prompt yourself.** Scripts may assemble, slice,
+  chroma-key, crop, validate, compose previews, and emit JSON/engine files — never
+  write creative prompts or draw final art. Procedural/placeholder art only when
+  the user explicitly asks for placeholders, fixtures, debug maps, or scaffolding.
+  With a tile engine target, generate the tileset art first, then script only the
+  layers, collision, zones, and scene wiring.
+- Save each prompt beside its asset as `<asset>.prompt.txt` (or an explicit
+  manifest field) whenever the run creates new visual assets.
+- **A reference handoff is a file path, not a sentence.** To build on an earlier
+  image, pass its sandbox `file_path` to `imagine_image_to_image` (and `read_file`
+  it so you can see it), then name the concrete features to preserve: camera
+  framing, horizon, road/water shapes, terrain boundaries, entrances/exits,
+  landmarks. A filename, "based on the map", or the image merely being visible in
+  conversation is **not** a handoff — stop and pass the path.
+
+## Keep runtime objects out of the base layer
+
+The first generated base/background/foundation image may hold only stable, non-interactive
+foundation art — ground material, paths, roads, water, cliffs, floor patterns, lane
+markings and build pads; for side views sky, far/mid scenery, silhouettes, atmosphere; for
+tilemaps tileset art as editable layers. It must **not** contain tall props, buildings,
+trees, rocks, crates, signs, doors, gates, pickups, chests, checkpoints, hazards, traps,
+turrets, ladders, foreground occluders, destructibles, actors, enemies, NPCs, UI, labels,
+or anything needing collision, interaction, reuse, y-sorting, animation, or its own render
+order — regenerate a foundation-only base, or demote such an image to a reference
+artifact.
+
+## Reference mockups are checkpoints, not deliverables
+
+Dressed references (top-down) and stage references (side-view) plan placement in-world:
+natural game-world objects or subtle blockout geometry, at most **9 distinct visible
+object candidates** (repeats count once, then recur in placement metadata), **no
+annotation graphics** (circles, arrows, outlines, labels, text, callouts, legends,
+measurement lines), and no non-visual metadata — spawns, triggers, patrol hints, camera
+bounds are written later as scene hooks.
+
+**Having generated one, do not stop there.** Continue through
+`references/object-production-gate.md`: re-`read_file` both images, build the object
+list, generate the final separate objects, write placement / collision / scene-hook
+metadata, compose the QA preview. Reference-only output is an incomplete run unless
+the user explicitly asked for a concept image.
+
+## Depth for the pipeline you picked — open these before producing assets
+
+- Layered raster maps → `references/layered-map-contract.md` (layer types, base and
+  prop prompt patterns, prop metadata, render order, collision, QA checklist).
+- `side_scroll_mode` → `references/side-scroll-stages.md`: the `stage_canvas`
+  decision, the named scenery-only parallax layers, and the mandatory in-world
+  stage reference before any platform/object work.
+- Any prop or scene-object generation → classify each object first, then follow
+  `references/prop-pack-contract.md`: only compact props may share a square prop
+  pack; platforms, floors, bridges, gates, buildings and anything collision-aligned
+  go one-by-one, as a platform strip, a custom wide pack, or tile/object layers.
+- Parameters, the step-by-step workflow, and the `extract_prop_pack.py` /
+  `compose_layered_preview.py` commands → `references/pipeline.md`.
+- Deliverable lists per pipeline and the validation checklist →
+  `references/deliverables.md`; run both before calling a map done.

package/skills/grok-generate2dmap/SOURCE.md

@@ -0,0 +1,6 @@
+# Source
+
+Vendored from [agent-sprite-forge](https://github.com/0x0funky/agent-sprite-forge) (`53dce6055984c610d833e77887939cbd0fb1c92b`).
+MIT License — see `LICENSE`.
+
+Adapted for Grok Build / app-builder sandbox (image tool paths, `read_file` for image inspection, workspace-relative script paths).

package/skills/grok-generate2dmap/agentsam.skill.json

@@ -0,0 +1,25 @@
+{
+  "schema": "agentsam.skill.v1",
+  "id": "grok-generate2dmap",
+  "name": "Grok \u00b7 generate2dmap",
+  "description": "2D game maps: layered art, props, collision metadata",
+  "icon": "skill",
+  "slash": {
+    "suggested": "/grok-generate2dmap"
+  },
+  "instructions": {
+    "source": "local_file",
+    "ref": "SKILL.md"
+  },
+  "execution": {
+    "mode": "turn",
+    "tools": [],
+    "operations": [],
+    "capabilities": []
+  },
+  "provenance": {
+    "source": "apps/local-studio/.grok/skills",
+    "vendor": "grok",
+    "status": "imported"
+  }
+}

package/skills/grok-generate2dmap/references/deliverables.md

@@ -0,0 +1,101 @@
+# Expected deliverables and validation
+
+Check the deliverable list for the pipeline you chose before calling a map
+done, then run the validation list against what you actually wrote.
+
+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
+
+Use this deliverable only for non-playable backgrounds or explicitly requested flat images. If actors must move through the scene, collide with level geometry, jump on platforms, collect items, trigger doors, or edit the level later, upgrade to a layered, parallax-stage, tilemap, or engine-native deliverable.
+
+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 tilemap or layered tilemap:
+
+- image-generated or user-supplied `assets/tilesets/<name>.png`
+- optional tile slicing/atlas metadata
+- engine-native tile layer data such as Tiled JSON, LDtk data, Godot TileMap scene data, Unity tile placement data, or project-native JSON
+- object layers for spawns, exits, interactables, blockers, and zones
+- a flattened preview assembled from the visual tileset and layer data
+- no script-drawn final tileset art unless the user explicitly asked for procedural placeholders
+
+For a playable side-view scrolling/action stage:
+
+- image-generated parallax scenery layers such as `assets/map/<name>-sky.png`, `assets/map/<name>-far-bg.png`, `assets/map/<name>-mid-bg.png`, `assets/map/<name>-near-bg.png`, and optional `assets/map/<name>-foreground-overlay.png`
+- one recorded `stage_canvas` shared by the primary parallax layers, `stage-reference`, and `stage-preview`
+- `assets/map/<name>-background.prompt.txt` and prompt files/manifests for other generated visual assets
+- `assets/map/<name>-stage-reference.png` as an in-world reference mockup for platform/object placement
+- separate image-generated platform, terrain-chunk, foreground-occluder, hazard, door, pickup, checkpoint, gate, and exit sprites when these are visible scene objects
+- `data/<name>-objects.json` or engine-native object layers for platforms, terrain chunks, hazards, pickups, doors, checkpoints, gates, exits, and foreground occluders
+- `data/<name>-scene-hooks.json` or engine-native metadata for player spawns, actor spawn marker metadata, encounter/arena triggers, camera bounds, and exit links
+- `data/<name>-collision.json` with explicit platform/solid geometry independent from the background pixels
+- `assets/map/<name>-stage-preview.png` composed from the background plus objects for QA only
+- code or scene changes that load the background, render object layers, and use the collision/object data as runtime gameplay data
+
+Do not accept a single generated side-view action/platformer stage image plus collision rectangles as the final playable map. The stage must expose platforms or walkable lanes, hazards, doors, pickups, checkpoints, gates, exits, scene hooks, and camera bounds as separate runtime objects, tile/object layers, or metadata. Runtime `background` fields must point to the scenery-only background or parallax layer, never to `stage-reference` or `stage-preview`; previews are QA artifacts only.
+
+For `grid_mode`:
+
+- image-generated or user-supplied tileset/grid art
+- grid dimensions, cell size, and map data in project-native JSON, Tiled JSON, LDtk, Godot TileMap, Unity Tilemap, or equivalent
+- cell metadata for walkable/buildable, movement cost, terrain effects, resources, collision, and placement rules
+- object layers for units, buildings, machines, cards/board slots, exits, spawns, and triggers
+- a QA preview that can show optional debug grid/collision overlays
+
+For `room_chunk_mode`:
+
+- reusable chunk art or tile/object layers
+- chunk metadata with `chunk_id`, size, entrances/exits, connection sockets, spawn markers, blockers, hazards, and camera bounds
+- collision and seam validation metadata
+- a chunk preview and, when multiple chunks exist, an assembled layout preview
+
+For `scene_mode`:
+
+- foundation-only `assets/map/<name>-base.png`
+- in-world `assets/map/<name>-dressed-reference.png`
+- separate props/interactables/blockers from one-by-one assets or compact prop packs
+- placement, collision, zones, exits, camera bounds, and scene-hook metadata
+- a QA preview composed from the base plus final runtime objects
+
+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
+- prompt files or prompt manifest fields exist for generated visible assets
+- 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
+- playable/editable layered maps use a foundation-only base/background and do not bake runtime-controlled props, interactables, hazards, doors, gates, pickups, actors, foreground occluders, or reusable scene objects into the base
+- playable stages have explicit runtime objects or metadata for every gameplay-relevant platform or walkable lane, blocker, hazard, door, pickup, checkpoint, gate, exit, player spawn, actor spawn marker, encounter/arena trigger, and camera bound
+- playable side-view backgrounds are scenery-only and do not contain baked-in foreground gameplay platforms, hazards, pickups, doors, gates, checkpoints, or other reusable runtime objects
+- `side_scroll_mode` primary parallax layers, stage references, and stage previews match the recorded `stage_canvas`; any repeatable strips or differently sized foreground sprites declare display size, anchor, scale, and repeat policy
+- `side_scroll_mode` parallax layers have explicit render order, scroll factors, dimensions, loop/repeat policy, and are not used as collision sources
+- `grid_mode` outputs include grid dimensions, cell size, cell metadata, object layers, and validation of critical walkable/buildable cells
+- `room_chunk_mode` outputs include chunk dimensions, exits/connection sockets, seam validation, collision, and at least one assembled or per-chunk preview
+- stage-reference maps preserve the background dimensions and their object plan matches the final object/collision metadata
+- stage-reference and dressed-reference mockups contain no more than 9 distinct visible runtime prop/object candidates unless the user explicitly requested a larger pass
+- reference mockups are followed by final props/objects, placement metadata, collision/scene-hook metadata, and a QA preview unless the user explicitly requested reference-only output
+- flattened preview looks coherent at the game's camera size

package/skills/grok-generate2dmap/references/layered-map-contract.md

@@ -0,0 +1,209 @@
+# Layered Raster Map Contract
+
+Use this contract for hand-painted or generated 2D RPG scenes, monster-taming exploration maps, shrine/town/dungeon maps, and any top-down scene where actors must interact with props.
+
+## Layer Types
+
+1. `base`: one raster image containing only terrain and ground-level details.
+2. `props`: transparent sprites anchored in map coordinates.
+3. `actors`: player, NPCs, monsters, pickups, and moving objects.
+4. `foreground`: optional transparent sprites that must cover actors.
+5. `collision`: structured metadata, not pixels.
+6. `zones`: structured metadata for encounters, rest, triggers, exits, and dialogue.
+7. `preview`: flattened QA artifact only.
+
+## Base Map Prompt Pattern
+
+Default to clean HD maps for gameplay readability unless the user explicitly asks for pixel art:
+
+```text
+Create a clean hand-painted top-down 2D RPG game map.
+This is a BASE GROUND MAP ONLY for a layered raster exploration scene.
+Style: clean HD game asset style, sharp readable terrain shapes, crisp silhouettes, smooth painted surfaces, low texture noise, controlled accent lighting.
+Do not make pixel art. Avoid chunky pixels, retro dithering, noisy microtexture, tiny debris, clutter, blurry painterly mush, and over-detailed grime.
+Include terrain, paths, grass/water/floor materials, ground markings, floor patterns, and flat anchor pads.
+Do not include tall collidable objects: no buildings, gates, fences, lanterns, trees, signs, barrels, NPCs, monsters, UI, or text.
+Leave clear empty spaces where props will be placed later.
+Make walkable paths and zone boundaries easy to trace.
+```
+
+If the user wants a pixel-adjacent look, use `clean modern pixel-art-inspired` and still forbid heavy dithering and noisy microtexture. Use `16-bit pixel art`, `retro JRPG pixel art`, or similar terms only when the user explicitly asks for a retro pixel look.
+
+## Prop Generation
+
+Use `$generate2dsprite` when the map needs reusable transparent props. Choose one of two approaches:
+
+- One-by-one props: safest for large, important, irregular, animated, or identity-critical props.
+- Prop packs: faster for sets of small/medium static environmental props.
+
+Read [prop-pack-contract.md](prop-pack-contract.md) before batching props.
+
+## Dressed Reference Pass
+
+For generated layered raster maps, use a dressed reference pass before final prop extraction:
+
+1. Generate the base as ground-only terrain.
+2. Hand the base to built-in `imagine_image_to_image` as a real reference: pass its sandbox `file_path` to `imagine_image_to_image`. Also call `read_file` so you can see it. Do not expect a filesystem path in the prompt, or the image merely being visible in conversation, to work as the visual reference.
+3. Ask for a dressed-reference version of the same map by adding props only.
+4. Preserve exact camera, framing, dimensions, terrain, paths, water, anchor pads, collision-relevant boundaries, and map edges.
+5. Use the dressed reference to choose prop identities and placement coordinates, but compose the final runtime preview from the original base plus extracted transparent props.
+
+The dressed reference is a planning artifact. Do not ship it as the only runtime map when props need collision, y-sort, occlusion, or reuse.
+
+Prompt shape:
+
+```text
+Use the provided reference image as the exact base map reference.
+Create a dressed-reference version of the same map by adding props only.
+Preserve exactly: camera, framing, image size, terrain, paths, water, anchor pads, rocks, map boundaries, and all walkable routes.
+Do not crop, zoom, rotate, repaint, or redesign the terrain.
+Add these props naturally on top of the existing map: <list>.
+Props should feel intentionally placed along paths, landmarks, encounter-zone edges, rest points, and entrances.
+No UI, no text, no labels, no watermark.
+```
+
+## One-By-One Prop Prompt Pattern
+
+```text
+Create a single <prop> prop for a top-down 2D RPG map.
+Use the same selected map art style: clean HD hand-painted by default, pixel-inspired only when requested, retro pixel only when explicitly requested.
+Mostly front-facing top-down RPG object view: upright objects are vertical and centered, with only a small visible top face. Avoid strong isometric diagonal rotation.
+Full object visible, centered, crisp but not chunky outlines.
+Background must be 100% solid flat #FF00FF magenta, no gradients, no texture, no shadows, no floor plane.
+No text, labels, UI, or watermark.
+Entire prop must fit fully inside the image with generous magenta margin on all sides; no part may touch or cross the image edge.
+```
+
+Recommended processing:
+
+```bash
+python /path/to/generate2dsprite.py process \
+  --input <raw.png> \
+  --target asset \
+  --mode single \
+  --rows 1 \
+  --cols 1 \
+  --cell-size 256 \
+  --output-dir assets/props/<prop> \
+  --fit-scale 0.9 \
+  --align feet \
+  --component-mode largest \
+  --component-padding 8 \
+  --min-component-area 200 \
+  --threshold 100 \
+  --edge-threshold 150 \
+  --edge-clean-depth 2
+```
+
+Use a larger `--cell-size` for buildings, trees, gates, statues, or large signs.
+
+## Prop Metadata
+
+Use explicit map-space dimensions:
+
+```json
+{
+  "props": [
+    {
+      "id": "torii",
+      "image": "assets/props/torii/prop.png",
+      "x": 836,
+      "y": 850,
+      "w": 380,
+      "h": 306,
+      "sortY": 850,
+      "layer": "props"
+    }
+  ]
+}
+```
+
+Anchor conventions:
+
+- `x`: center of the prop's base/feet.
+- `y`: bottom of the prop in map coordinates.
+- `w`, `h`: rendered size in map units.
+- `sortY`: y-depth used for render ordering. Use base `y` for normal props.
+- `layer`: `props` for y-sorted objects, `foreground` for always-over actors overlays.
+
+## Render Order
+
+Recommended order:
+
+```text
+base map
+ground effects / zone glimmers
+renderables sorted by sortY:
+  props
+  actors
+foreground overlays
+debug collision
+HUD/UI
+```
+
+If an NPC must always appear above the player, draw that NPC after the y-sorted pass or set a high `sortY`.
+
+## Collision Metadata
+
+Keep collision readable and hand-editable:
+
+```json
+{
+  "mapSize": { "width": 1672, "height": 941 },
+  "spawn": { "x": 836, "y": 782 },
+  "walkBounds": [
+    { "id": "main-courtyard", "type": "ellipse", "x": 838, "y": 548, "rx": 604, "ry": 304 }
+  ],
+  "blockers": [
+    { "id": "torii-left-pillar", "type": "rect", "x": 704, "y": 668, "w": 52, "h": 176 }
+  ],
+  "zones": {
+    "grass": { "type": "rect", "x": 180, "y": 306, "w": 382, "h": 302 },
+    "rest": { "type": "circle", "x": 760, "y": 548, "radius": 122 }
+  }
+}
+```
+
+Guidelines:
+
+- Use blockers for prop bases, not full sprite silhouettes.
+- Keep entrances open by testing path centers.
+- Use ellipses for lanterns, rocks, trees, and basins.
+- Use rectangles for fences, walls, buildings, gates, bridges, and posts.
+- Use polygons only when rects/ellipses produce poor walkability.
+
+## Preview Composition
+
+Use `scripts/compose_layered_preview.py` to flatten a base map and placement JSON:
+
+```bash
+python3 .grok/skills/generate2dmap/scripts/compose_layered_preview.py \
+  --base assets/map/shrine-base.png \
+  --placements data/shrine-props.json \
+  --output assets/map/shrine-layered-preview.png
+```
+
+The script assumes prop placement uses center-bottom anchoring unless a prop explicitly sets another anchor.
+
+## QA Checklist
+
+- Spawn point is walkable.
+- Main path centers are walkable.
+- Gate centers are walkable if the player should pass through.
+- Gate pillars block.
+- Fences block but entrances remain open.
+- Interactables block at their base but can be approached.
+- Encounter/rest zones are reachable.
+- Actors sort correctly when walking in front of and behind tall props.
+- The flattened preview matches the in-game layered render closely enough for visual review.
+
+## Anti-Patterns
+
+Avoid:
+
+- Cutting props out of a fully baked generated map.
+- Using a complete flattened map as the only source when collision/occlusion matters.
+- Baking text, signs, UI, NPCs, or monsters into the base.
+- Letting prop sprites touch image edges.
+- Treating transparent PNG bounding boxes as collision automatically.
+- Updating art without updating collision and critical point tests.