@inneranimalmedia/agentsam-sdk 2.6.4 → 2.6.7

package/skills/grok-generate2dmap/references/prop-pack-contract.md

@@ -0,0 +1,174 @@
+# Prop Pack Contract
+
+Prop packs batch multiple small static map props into one generated sheet, then extract each cell into a transparent prop PNG. Square prop packs are for compact props only, not for floors, platforms, bridges, walls, or other wide/collision-critical scene objects.
+
+Use prop packs to reduce repeated image-generation calls and prompt overhead. They trade per-prop control for speed, so use them only when the props can share one style, scale, perspective, and quality bar.
+
+## When To Use
+
+Good candidates:
+
+- rocks, shrubs, flowers, mushrooms, logs
+- crates, barrels, sacks, pots
+- small signs, lamps, lanterns, fences, posts
+- floor ornaments, small statues, ruins, debris
+- repeated environmental dressing for one biome
+
+Avoid prop packs for:
+
+- buildings, gates, trees with wide canopies, bridges
+- floors, walkable platforms, terrain chunks, ledges, wall runs, rails, ladders, road segments, fence rows, long spike traps, pipes, conveyors, ramps, slopes, or any long horizontal object
+- hero objects, key story artifacts, readable statues
+- animated props or props with multiple states
+- props requiring exact silhouette, scale, or identity
+- props that are too wide/tall for equal square cells
+- props that must line up exactly with collision, walkable edges, build pads, doorways, gate openings, checkpoints, hazards, exits, or engine editor handles
+
+## Asset Strategy Gate
+
+Classify every object before choosing a generation shape:
+
+- `compact_prop`: small/medium, roughly square or vertical, decorative or simple blocker, no exact edge alignment requirement.
+- `wide_or_long_object`: expected aspect ratio wider than about `1.6:1`, such as floors, platforms, bridges, ledges, wall runs, fence rows, long traps, rails, pipes, roads, conveyors, or long signs.
+- `tall_or_large_object`: expected aspect ratio taller than about `1.6:1` or visually dominant, such as buildings, gates, large trees, towers, doors, banners, statues, or shrine pieces.
+- `collision_bearing_object`: must align with collision, walkable edges, build pads, hazards, doors, gates, checkpoints, exits, or engine handles.
+- `tileset_or_strip_piece`: should repeat or assemble from caps, middles, corners, slopes, tops, sides, or tile pieces.
+
+Only `compact_prop` objects may use square `2x2`, `3x3`, or `4x4` prop packs. Everything else must use one-by-one generation, a strip/tileset workflow, custom wide cells, or engine-native tile/object layers.
+
+Do not mix strategy classes in one sheet. A sheet of small rocks, crates, lamps, and grass is acceptable. A sheet that mixes rocks with platforms, floor pieces, gates, ladders, or spike hazards is not acceptable.
+
+## Sheet Size Selection
+
+- `2x2`: 4 props, safest batch size.
+- `3x3`: 9 props, best default for compact small/medium environmental sets.
+- `4x4`: 16 props, only for very simple small props with strong margins.
+- `1x3 platform strip`: non-actor left cap, middle repeat, right cap for walkable floors/platforms.
+- `1x4 platform strip`: non-actor left cap, middle repeat, right cap, plus one slope/corner/end variant. This is not an animation-frame format.
+- `custom_wide_pack`: several related wide props using explicit wide cells such as `768x256`, `1024x384`, or another non-square cell size.
+
+Use `3x3` by default only when the user asks for a set of compact map props and does not specify count.
+Use one-by-one, platform strips, custom wide packs, or tile/object layers instead of a square pack for hero props, wide gates, buildings, wide trees, floors, platforms, bridges, walls, long hazards, ladders, or anything that must line up exactly with collision.
+
+If a square pack fails because a wide/tall object touches the cell edge, do not pass it by relaxing QC and do not keep retrying the same square pack. Reclassify that object and regenerate it with one-by-one, a platform strip, a custom wide pack, or a tile/object-layer workflow.
+
+## Prompt Pattern
+
+For `3x3` and `4x4` packs, create a layout-only guide first with `$generate2dsprite`:
+
+```bash
+python3 .grok/skills/generate2dsprite/scripts/make_layout_guide.py \
+  --rows <ROWS> \
+  --cols <COLS> \
+  --cell-width 384 \
+  --cell-height 384 \
+  --output assets/props/raw/<name>-layout-guide.png
+```
+
+Pass the guide PNG's sandbox path to `imagine_image_to_image`. Tell the model to use it only for invisible slot count, spacing, centering, and safe padding. The output must not copy guide boxes, safe-area rectangles, center marks, labels, borders, or guide background.
+
+```text
+Create exactly one <ROWS>x<COLS> prop sheet for a top-down 2D RPG map.
+Each cell contains one separate static environmental prop from this list, in row-major order:
+1. <prop>
+2. <prop>
+...
+All props share the same biome, palette, camera angle, selected map art style, and scale.
+Use clean hand-painted HD 2D game asset style by default: crisp silhouettes, smooth surfaces, low texture noise, controlled accent lighting. Do not make pixel art unless the user asked for it.
+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; crates and barrels should not become diamond-shaped or tilted unless the user explicitly asks for isometric art.
+Full object visible, centered in its own cell, crisp but not chunky outlines.
+Each prop must fit fully inside the central 50% to 60% of its cell with generous flat magenta gutters on all four sides.
+No prop, branch, roof, sign, glow, cable, smoke, sparkle, shadow, or fragment may touch or cross a cell edge.
+This square prop sheet must contain only compact props. Do not include floors, platforms, bridges, wall runs, ladders, long hazards, gates, doors, buildings, wide trees, roads, ramps, slopes, or any object that needs exact collision or walkable-edge alignment.
+Background must be 100% solid flat #FF00FF magenta in every cell, no gradients, no texture, no shadows, no floor plane.
+No text, labels, UI, watermark, numbers, arrows, borders, grid lines, or readable letters.
+```
+
+If a cell should stay empty, explicitly say `empty magenta cell`.
+
+## Platform Strip Prompt Pattern
+
+For repeatable floors, platforms, bridges, or terrain chunks, do not use a square `3x3` prop pack. Use a strip or tileset-like atlas with wide cells and a layout guide:
+
+```text
+Create exactly one 1x3 platform strip asset sheet for a 2D game map.
+Cells, left to right:
+1. left end cap of the platform
+2. seamless middle repeat segment
+3. right end cap of the platform
+
+Each cell is a wide non-square cell, intended for platform/floor collision alignment.
+Every segment must have a perfectly horizontal walkable top edge at the same y-position across all cells.
+The middle segment must tile seamlessly left-to-right.
+No segment may touch or cross its cell edge except intentional seamless side edges on the middle repeat cell.
+Use solid flat #FF00FF magenta background, no floor plane, no shadows, no labels, no UI, no guide lines.
+```
+
+Use `1x4` only for non-actor platform strips when a slope, corner, broken variant, or underside piece is needed. If a platform is unique, large, or very important, generate it one-by-one on a wide canvas instead of using a strip. Never use this format for characters, enemies, creatures, NPCs, summons, or animated body assets.
+
+## Extraction
+
+The extract script includes built-in solid-magenta chroma cleanup. Prefer a
+hard-key first; if fringe remains after visual QC, regenerate the sheet with a
+flatter `#FF00FF` background or tighten thresholds via the script flags.
+
+```bash
+python3 .grok/skills/generate2dmap/scripts/extract_prop_pack.py \
+  --input assets/props/raw/forest-props-sheet.png \
+  --rows 3 \
+  --cols 3 \
+  --labels mossy-rock,shrub,fallen-log,small-lantern,wooden-sign,flower-patch,stump,crate,grass-tuft \
+  --output-dir assets/props \
+  --manifest assets/props/forest-prop-pack.json \
+  --component-mode largest \
+  --component-padding 8 \
+  --min-component-area 200 \
+  --reject-edge-touch
+```
+
+Output shape:
+
+```text
+assets/props/<label>/prop.png
+assets/props/forest-prop-pack.json
+```
+
+The manifest contains source cell coordinates, crop boxes, alpha bounds, extracted image size, component counts, and `edge_touch` flags.
+
+If the first pack fails because large props touch cell edges, regenerate with stricter occupancy wording such as `each prop must fit inside the central 50% of its cell`. Do not pass a failed pack by relaxing QC unless the clipped asset is intentionally discarded.
+
+## Placement
+
+After extraction, create placement JSON:
+
+```json
+{
+  "props": [
+    {
+      "id": "mossy-rock-1",
+      "image": "assets/props/mossy-rock/prop.png",
+      "x": 420,
+      "y": 512,
+      "w": 96,
+      "h": 72,
+      "sortY": 512,
+      "layer": "props"
+    }
+  ]
+}
+```
+
+Then compose a QA preview with `scripts/compose_layered_preview.py`.
+
+## QC Rules
+
+Reject or regenerate the pack when:
+
+- any accepted prop has `edge_touch: true`
+- labels do not match the requested cells
+- a prop has text, UI, shadows, or floor baked in
+- prop identity drifts into character/NPC-like art
+- a prop is too large for the intended placement scale
+- a square pack contains a wide/long, tall/large, collision-bearing, platform, floor, bridge, wall, ladder, gate, door, or tileset/strip object
+
+For noisy particles or edge debris, reprocess with `--component-mode largest`. For intentional multi-part props, use `--component-mode all` and increase the prompt margin.

package/skills/grok-generate2dmap/references/side-scroll-stages.md

@@ -0,0 +1,29 @@
+# Playable Stage Reference Rules
+
+For playable side-view scrolling/action maps, an in-world stage reference mockup is mandatory before generating final scene objects or scene metadata. This applies across art styles and game styles, including pixel art, clean HD, side-scrollers, platformers, runners, shooters, brawlers, scrolling combat stages, and Megaman-like or Castlevania-like stages:
+
+0. Choose and record one `stage_canvas`, for example `1536x864` for a default 16:9 HD side-scroller when the project has no explicit camera size. Use the engine's existing viewport aspect ratio when it exists. All primary parallax layers, the stage reference, and the stage preview must share this exact size unless a layer is explicitly marked as a repeatable strip.
+1. Generate named parallax scenery layers as separate runtime images: `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`.
+- These layers are scenery only, not playable foreground. They may contain sky, clouds, mountains, distant buildings, distant castle walls, silhouettes, atmosphere, and non-colliding far depth.
+- Do not collapse these layers into only `assets/map/<name>-background.png` for a playable `side_scroll_mode` stage. A single scenery background is allowed only when the user explicitly requests a flat/non-parallax background; in that case still continue with stage reference, separate objects, collision, camera bounds, and QA preview.
+   - Each primary layer prompt must specify the same target canvas size/aspect ratio, same camera framing, same horizon height, and same top-left aligned composition. If image generation returns different sizes, regenerate or normalize them to `stage_canvas` before using them together.
+   - Repeatable strips and foreground/object sprites may have different source dimensions, but they must declare display size, anchor point, repeat axis, and scale in metadata. They are not substitutes for the primary parallax plates.
+   - It must not contain walkable floors, platform tops, terrain chunks, spike traps, pickups, crates, doors, gates, checkpoints, ladders, near fences, near stone walls, enemies, player characters, UI, labels, or any object that should later be edited, collided with, reused, or layered independently.
+   - Keep the playable foreground lane visually open or neutral so separate platform/object layers can stack clearly over it.
+2. Hand the background to `imagine_image_to_image` as a real reference: pass its sandbox `file_path`. Also `read_file` it so you can see it; do not rely on a path string or prompt text as the reference.
+3. In the stage-reference prompt, explicitly say: use the provided background image as the visual reference, preserve exact camera/framing/dimensions/horizon/depth/entrances/exit direction, and generate an in-world stage reference mockup.
+4. Generate `assets/map/<name>-stage-reference.png` from the visible background.
+5. In the stage reference, visually place the intended scene layout as natural game-world objects or subtle blockout geometry: platforms or walkable lanes, terrain chunks, foreground occluders, hazards, pickups, doors, checkpoints, gates, and exits.
+   - Use at most 9 distinct visible runtime object candidates in the stage reference unless the user explicitly asks for a larger object pass. Repeated placements of the same platform, terrain chunk, hazard, pickup, checkpoint, door, gate, or occluder count as one candidate and should be repeated later in metadata.
+   - Prioritize objects that the final game must render or collide with separately. Avoid filling the mockup with many small decorative foreground props that will not become reusable assets.
+6. Do not draw spawn markers, actor markers, arena trigger zones, camera bounds, arrows, labels, circles, outlines, numbered callouts, text, legends, or UI overlays in the reference image. Record player spawn, actor spawn markers, arena triggers, camera bounds, and exit links later as scene-hook metadata.
+7. Use the stage reference to decide object identities, sizes, coordinates, render order, collision shapes, and camera bounds.
+8. Continue through the post-reference object production gate: generate or define final platforms, terrain chunks, hazards, pickups, doors, checkpoints, foreground occluders, and other visible scene objects as separate assets, tile layers, or object layers. Compose the final runtime preview from the original background plus these separate runtime objects.
+
+The stage reference is an in-world reference mockup. Do not ship it as the runtime map, do not infer collision from its pixels, and do not cut platform objects out of the baked reference image. If a platform must be reusable or collidable, generate it as a separate platform object, terrain chunk, tile, or engine-native object.
+
+If the generated background already has obvious foreground gameplay pieces baked into it, do not use it as `background` in runtime data. Regenerate the scenery-only background or demote that image to a concept/reference artifact.
+
+Scene hooks are metadata only. Do not generate enemy, boss, NPC, player, projectile, or animation sprites inside `generate2dmap`; call `$generate2dsprite` separately when the game needs those assets.
+
+If a playable side-view scrolling/action run has already generated a background but has not generated `assets/map/<name>-stage-reference.png`, pause the platform/props pipeline and generate the stage reference next. Background plus props is not enough evidence that the level layout is coherent.

package/skills/grok-generate2dmap/scripts/compose_layered_preview.py

@@ -0,0 +1,157 @@
+#!/usr/bin/env python3
+"""Compose a flattened layered-map preview from a base image and prop placements."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import Any
+
+from PIL import Image
+
+
+def read_json(path: Path) -> Any:
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def resolve_path(value: str, roots: list[Path]) -> Path:
+    path = Path(value)
+    if path.is_absolute():
+        return path
+    for root in roots:
+        candidate = root / path
+        if candidate.exists():
+            return candidate
+    return roots[0] / path
+
+
+def load_props(data: Any) -> list[dict[str, Any]]:
+    """Load placement entries from a list or object with layer lists.
+
+    When the payload is an object, merge *all* of props / foreground / objects
+    (in that order) so layered QA previews do not drop platforms or occluders
+    just because another key appeared first.
+    """
+    if isinstance(data, list):
+        return data
+    if isinstance(data, dict):
+        merged: list[dict[str, Any]] = []
+        for key in ("props", "foreground", "objects"):
+            value = data.get(key)
+            if not isinstance(value, list):
+                continue
+            if key == "foreground":
+                merged.extend({**item, "layer": "foreground"} for item in value)
+            else:
+                merged.extend(value)
+        if merged:
+            return merged
+    raise ValueError(
+        "Placement JSON must be a list or an object with a 'props', "
+        "'foreground', and/or 'objects' list."
+    )
+
+
+def placement_xy(prop: dict[str, Any], width: int, height: int) -> tuple[int, int]:
+    anchor = str(prop.get("anchor", "center-bottom"))
+    x = float(prop.get("x", 0))
+    y = float(prop.get("y", 0))
+
+    if anchor == "top-left":
+        left = x
+        top = y
+    elif anchor == "center":
+        left = x - width / 2
+        top = y - height / 2
+    elif anchor == "bottom-left":
+        left = x
+        top = y - height
+    else:
+        left = x - width / 2
+        top = y - height
+    return round(left), round(top)
+
+
+def paste_prop(canvas: Image.Image, prop: dict[str, Any], roots: list[Path]) -> dict[str, Any]:
+    image_key = prop.get("image") or prop.get("path")
+    if not image_key:
+        raise ValueError(f"Prop is missing image/path: {prop}")
+    image_path = resolve_path(str(image_key), roots)
+    if not image_path.exists():
+        raise FileNotFoundError(f"Prop image not found: {image_path}")
+
+    img = Image.open(image_path).convert("RGBA")
+    width = int(prop.get("w", prop.get("width", img.width)))
+    height = int(prop.get("h", prop.get("height", img.height)))
+    if width <= 0 or height <= 0:
+        raise ValueError(f"Invalid prop size for {image_path}: {width}x{height}")
+    if (width, height) != img.size:
+        img = img.resize((width, height), Image.Resampling.LANCZOS)
+
+    opacity = float(prop.get("opacity", 1.0))
+    if opacity < 1:
+        alpha = img.getchannel("A").point(lambda value: int(value * max(0.0, min(1.0, opacity))))
+        img.putalpha(alpha)
+
+    left, top = placement_xy(prop, width, height)
+    canvas.alpha_composite(img, (left, top))
+    return {
+        "id": prop.get("id", image_path.stem),
+        "image": str(image_path),
+        "left": left,
+        "top": top,
+        "w": width,
+        "h": height,
+        "sortY": prop.get("sortY", prop.get("y", top + height)),
+        "layer": prop.get("layer", "props"),
+    }
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--base", required=True, type=Path)
+    parser.add_argument("--placements", required=True, type=Path)
+    parser.add_argument("--output", required=True, type=Path)
+    parser.add_argument("--report", type=Path)
+    parser.add_argument("--project-root", type=Path, default=Path.cwd())
+    return parser
+
+
+def main() -> None:
+    args = build_parser().parse_args()
+    base = Image.open(args.base).convert("RGBA")
+    data = read_json(args.placements)
+    props = load_props(data)
+    roots = [args.placements.parent, args.base.parent, args.project_root]
+
+    props_layer = [prop for prop in props if str(prop.get("layer", "props")) != "foreground"]
+    foreground_layer = [prop for prop in props if str(prop.get("layer", "props")) == "foreground"]
+    props_layer.sort(key=lambda item: float(item.get("sortY", item.get("y", 0))))
+    foreground_layer.sort(key=lambda item: float(item.get("sortY", item.get("y", 0))))
+
+    pasted = []
+    for prop in props_layer + foreground_layer:
+        pasted.append(paste_prop(base, prop, roots))
+
+    args.output.parent.mkdir(parents=True, exist_ok=True)
+    base.save(args.output)
+    if args.report:
+        args.report.parent.mkdir(parents=True, exist_ok=True)
+        args.report.write_text(
+            json.dumps(
+                {
+                    "base": str(args.base),
+                    "placements": str(args.placements),
+                    "output": str(args.output),
+                    "pasted": pasted,
+                },
+                indent=2,
+            ),
+            encoding="utf-8",
+        )
+    print(str(args.output.resolve()))
+
+
+if __name__ == "__main__":
+    main()