@inneranimalmedia/agentsam-sdk 2.6.7 → 2.6.9

package/skills/grok-generate2dmap/references/map-strategies.md

@@ -1,341 +0,0 @@
-# Map Pipeline Selection
-
-Choose maps by first selecting a product-level `map_mode`, then mapping that mode to pipeline axes. Avoid treating `hybrid` as a top-level strategy; most real 2D maps are hybrid combinations of visual art, objects, and collision metadata.
-
-## Core Map Modes
-
-Use these modes as the first decision layer:
-
-- `tile_mode`: editable tile/grid maps. Use for Pokemon-like routes, top-down RPG towns, monster-taming exploration, platformer tilemaps, tactical maps, factory maps, and projects that already use Tiled, LDtk, Godot TileMap, Unity Tilemap, or Phaser tilemaps.
-- `scene_mode`: foundation/base map plus separate props. Use for tower defense, survivors-like arenas, cozy/top-down showcase maps, visual adventure scenes, and base-map-plus-props requests.
-- `side_scroll_mode`: parallax side-scroller scenes. Use for Mega Man-like, action platformer, Metroidvania side rooms, runners, side-view shooters, and brawlers.
-- `grid_mode`: rule-heavy grid scenes. Use for tactical RPGs, factory/automation games, board/card battlers, build grids, terrain-cost maps, and resource maps.
-- `room_chunk_mode`: modular room/chunk generation. Use for roguelike rooms, dungeon chunks, procedural level assembly, and Metroidvania room networks.
-- `baked_scene_mode`: fixed visual backgrounds. Use only for title screens, visual novel backgrounds, point-and-click scenes, boss arena concept art, non-playable showcase images, or explicit flat-image requests.
-
-Modes are not final file formats. After choosing a mode, still define `visual_model`, `runtime_object_model`, `collision_model`, and `engine_target`.
-
-## Genre Routing Table
-
-| User asks for | Default mode | Notes |
-| --- | --- | --- |
-| Pokemon-like, monster-taming RPG, top-down RPG route/town | `tile_mode` | Add props, encounter zones, exits, NPC/actor spawn markers, and collision. |
-| Tower defense, Kingdom Rush-like | `scene_mode` | Add path metadata, build slots, spawn/exit hooks, blockers, and optional engine scene scaffold. |
-| Survivors-like arena | `scene_mode` or `tile_mode` | Use sparse blockers, spawn zones/rings, camera bounds, and props. |
-| Mega Man-like, side-view action, platformer, runner | `side_scroll_mode` | Use parallax layers plus platform/object/collision metadata. |
-| Metroidvania | `side_scroll_mode` or `room_chunk_mode` | Use room/chunk exits and camera bounds; use tilemap when the engine expects grid collision. |
-| Beat-em-up / brawler | `side_scroll_mode` | Use parallax/background depth plus a walkable belt polygon, enemy wave zones, and props. |
-| Tactical RPG, grid strategy | `grid_mode` | Store terrain, move cost, defense/effects, unit slots, and collision. |
-| Factory / automation | `grid_mode` | Store buildable cells, resource nodes, machine slots, belts/conveyors, and item lanes. |
-| Card/board battler or UI-heavy game | `grid_mode` | Store board slots, UI zones, interaction regions, and background art. |
-| Roguelike room, procedural dungeon, modular rooms | `room_chunk_mode` | Store chunk sockets, exits, collision, spawn markers, and seam validation. |
-| Visual novel, title screen, fixed battle background | `baked_scene_mode` | Use only when no runtime editing/collision is needed. |
-
-## Playable Map Default
-
-When the user asks for a playable game map, level, stage, room, prototype, or engine scene, the runtime map must not be only a flattened generated image. A single baked image can be used as a background, in-world reference mockup, or QA preview, but playable output needs explicit runtime structure:
-
-- top-down maps: ground/base layer plus separate props, object placement, collision, zones, exits, and spawn data
-- side-view scrolling/action stages: background/parallax layers plus an in-world stage reference mockup, platform objects or walkable lanes, terrain chunks, foreground occluders, hazards, doors, pickups, checkpoints, scene hooks, camera bounds, and collision
-- tile/editor workflows: generated or supplied tileset art plus tile layers, object layers, collision, zones, and engine-native scene/map data
-
-If the request mentions "game", "playable", "prototype", "level", "stage", "side-view action", "side-scroller", "platformer", "Megaman-like", "RPG exploration", "tower defense", or engine integration, start from the nearest playable preset below instead of `baked_raster`.
-
-## Mode Deliverable Contracts
-
-### `tile_mode`
-
-Deliver tileset art, map data, tile layers, object layers, collision, exits, and a preview. Good output formats include Tiled JSON, LDtk, Godot TileMap, Unity Tilemap, Phaser tilemaps, or project-native JSON.
-
-Use `generate2dsprite` only when reusable transparent props, NPCs, animated objects, or non-tile scene objects are actually needed. A pure terrain map can stay tileset + map data + collision metadata.
-
-### `scene_mode`
-
-Deliver a foundation-only base map, an in-world dressed reference, final separate props/interactables/blockers, placement metadata, collision/zones/exits/camera bounds, and a composed QA preview.
-
-This is the default for beautiful top-down demos, tower defense scenes, survivors-like arenas, and base-map-plus-props workflows.
-
-### `side_scroll_mode`
-
-Deliver scenery-only parallax layers plus separate playable foreground objects. Typical visual layers:
-
-- `sky`
-- `far_bg`
-- `mid_bg`
-- `near_bg`
-- optional `foreground_overlay`
-
-Then deliver platform tiles/objects, terrain chunks, hazards, doors, checkpoints, pickups, exits, camera bounds, scroll factors, collision, scene hooks, and a QA preview. Parallax layers create depth; they are not collision sources.
-
-Choose one `stage_canvas` before generation. The primary parallax plates, stage reference, and QA preview must share the same pixel dimensions, aspect ratio, camera framing, horizon, and top-left anchor. Default to the project camera aspect ratio; when unknown, use a 16:9 side-scroller canvas such as `1536x864`.
-
-For brawlers, use the same mode but replace jump-platform geometry with a walkable belt polygon, foreground/background props, enemy wave zones, and camera locks.
-
-### `grid_mode`
-
-Deliver grid dimensions, cell size, tiles/cells, terrain metadata, walkable/buildable flags, movement cost, resource or terrain effects, collision, object layers, and a preview with optional debug overlay.
-
-Prioritize validation over beauty. The map must be readable by game logic.
-
-### `room_chunk_mode`
-
-Deliver reusable room/chunk art or tile/object layers, chunk dimensions, exits, connection sockets, collision, spawn markers, camera bounds, and seam validation. If multiple chunks exist, also deliver an assembled layout preview.
-
-### `baked_scene_mode`
-
-Deliver a fixed image plus optional coarse collision/zones only. Do not use this mode for editable or playable maps unless the user explicitly requests a flat background.
-
-## Visual Asset Source
-
-Default to built-in image generation for visual assets. Base maps, in-world reference mockups, dressed references, stage references, prop sheets, prop sprites, tileset art, parallax layers, and battle backgrounds should come from `imagine_text_to_image` unless the user supplies existing art or explicitly asks for procedural placeholders.
-
-Scripts may slice, assemble, chroma-key, validate, compose previews, create metadata, and emit engine files. They must not replace image generation as the creative art source for final map visuals. Engine outputs such as Godot `.tscn`, Tiled JSON, LDtk data, or Unity placement data should wire up image-generated or user-supplied assets.
-
-## In-World Reference Mockups
-
-Use an in-world reference mockup whenever object placement must be visually coherent but the final runtime needs separate objects.
-
-- Top-down layered maps use `assets/map/<name>-dressed-reference.png`: base map plus proposed props rendered as natural game-world objects.
-- Side-view scrolling/action stages use `assets/map/<name>-stage-reference.png`: background/parallax base plus proposed platforms or walkable lanes, hazards, pickups, doors, checkpoints, gates, and exits rendered as natural game-world objects or subtle in-world blockout geometry.
-- Reference mockups must preserve exact camera, framing, dimensions, terrain/background, entrances, exits, and collision-relevant boundaries from the base image.
-- Reference mockups should include at most 9 distinct visible runtime prop/object candidates unless the user explicitly asks for a larger pass. Repeated placements of the same object count as one candidate and should be repeated later in placement metadata.
-- Reference mockups are planning artifacts only. Do not ship them as runtime maps, infer collision from their pixels, or cut final platform/prop assets out of them.
-- Final output must still use separate props/platform objects, scene-object metadata, collision, zones, scene hooks, tile/object layers, or engine-native nodes.
-- Character, enemy, boss, projectile, player, NPC, and animation sprites are outside the map deliverable. Store actor spawn markers and encounter/arena hooks as metadata only, then use `$generate2dsprite` if those actor assets are needed.
-- Do not create annotated diagrams. Reference mockups must not contain circles, arrows, outlines, labels, numbers, UI callouts, text, captions, legends, highlighted boxes, highlighted zones, measurement lines, or explanatory overlays.
-- Do not stop after the reference mockup. Reference-only output is incomplete unless the user explicitly asked for a reference-only concept image.
-
-## Visual Reference Handoff
-
-Reference mockups must be generated from the actual base/background image, passed to the image model as a real reference:
-
-1. Save the base/background image first and keep its sandbox `file_path`.
-2. Pass that `file_path` on the reference-mockup `imagine_image_to_image` call. Also call `read_file` on the saved image so you can see it yourself.
-3. The image prompt must explicitly say to use the provided reference image as the visual reference.
-4. The prompt must name concrete features from the viewed image to preserve: camera framing, dimensions, horizon, terrain boundaries, road/water shapes, entrances, exits, major silhouettes, and landmark positions.
-5. The prompt must ask for an in-world reference mockup, not an annotated planning diagram.
-6. The prompt should render only visible scene objects: props, platforms, terrain chunks, hazards, gates, pickups, checkpoints, doors, exits, foreground occluders, or subtle blockout geometry.
-7. Non-visual data such as player spawns, actor spawn markers, camera bounds, patrol hints, and encounter/arena triggers must be written later as scene-hook metadata, not drawn into the image.
-
-Do not rely on filenames, paths, vague phrasing such as "based on this map", or the image merely being visible in conversation. If the base/background is not wired into the call as a sandbox `file_path`, stop and pass it before generating the dressed reference or stage reference.
-
-## Layer Separation Contract
-
-For any playable or editable layered map, the first generated base/background/foundation image must not bake in objects that the runtime should control separately. This applies across top-down RPG maps, monster-taming maps, tactical arenas, tower-defense lanes, side-view platformers, parallax stages, tile/editor workflows, clean HD, pixel-inspired, and retro pixel art.
-
-Allowed in the base/background/foundation layer:
-
-- top-down or 3/4 maps: ground material, paths, roads, water, cliffs, low terrain markings, floor patterns, and terrain boundaries
-- tactical or tower-defense maps: ground, lanes, roads, build pads, lane markings, terrain zones, and non-interactive floor detail
-- side-view stages: sky, far/mid scenery, distant buildings, distant terrain silhouettes, atmosphere, and non-colliding depth
-- tilemaps: tileset art and editable tile layers, not a flattened full-scene background
-
-Not allowed in the runtime base/background/foundation layer unless the user explicitly asks for a single baked image:
-
-- tall props, buildings, trees, rocks, crates, signs, doors, gates, pickups, chests, checkpoints, hazards, traps, turrets, tower objects, ladders, foreground occluders, destructibles, actors, enemies, NPCs, bosses, player characters, UI, labels, or any object that needs collision, interaction, replacement, reuse, y-sorting, animation, engine editing, or independent render order
-
-If a generated base/background contains runtime-controlled objects, regenerate a cleaner foundation-only base or demote that image to a concept/reference artifact. Proposed objects belong in the in-world reference mockup, then in final separate props, platform objects, object layers, tile layers, collision, zones, and scene-hook metadata.
-
-## Side-Scroll Parallax Contract
-
-`side_scroll_mode` uses parallax background as a core stage-building method. It should produce a layered depth stack, not one crowded full-stage painting.
-
-Typical layer responsibilities:
-
-- `sky`: sky, moon/sun, far atmosphere; scroll factor near `0.0` to `0.1`.
-- `far_bg`: mountains, skyline, far castle/factory silhouettes; slow scroll factor.
-- `mid_bg`: readable landmarks and large distant structures; medium scroll factor.
-- `near_bg`: near non-colliding scenery behind gameplay objects; faster scroll factor but still not collision.
-- `foreground_overlay`: optional fog, chains, pipes, silhouettes, smoke, or framing elements that render above actors but do not define gameplay collision.
-
-Generate parallax layers as scenery-only art. Platforms, walkable floors, ladders, hazards, gates, doors, pickups, checkpoints, and collision-critical props belong in platform/object/tile layers, not in parallax backgrounds.
-
-All primary parallax plates must use the same `stage_canvas`. If image generation returns inconsistent dimensions, regenerate or normalize the generated layer before runtime use. Do not rely on the engine to guess scaling between mismatched layer sizes. Repeatable strips may have different source widths only when metadata records display size, anchor, scale, repeat axis, and loop policy.
-
-The final side-scroller should feel deeper than a single flat image: distant layers move slowly, near layers move faster, and gameplay objects stay on their own runtime layer.
-
-## Side-View Background Separation
-
-For playable side-view scrolling/action stages, the general layer separation contract becomes stricter: the background is scenery-only. It should be a far/mid depth plate that separate runtime objects can stack over cleanly.
-
-Allowed in the background:
-
-- sky, clouds, mountains, distant city/castle silhouettes, far walls, smoke, weather, atmospheric depth, and non-colliding distant landmarks
-- optional separate parallax midground/foreground layers when they are not gameplay geometry
-
-Not allowed in the runtime background:
-
-- walkable floors, platform tops, terrain chunks, ladders, spike traps, pickups, crates, doors, gates, checkpoints, near fences, near walls, foreground barricades, enemies, player characters, UI, labels, or any object that should be edited, collided with, reused, or rendered independently
-
-If a generated side-view background contains obvious foreground gameplay geometry, reject it as a runtime background and regenerate a cleaner scenery-only background. Do not set flattened `stage-reference` or `stage-preview` images as the runtime background.
-
-## Post-Reference Object Production
-
-After a dressed reference or stage reference exists, continue into final runtime production:
-
-1. Make both the original base/background and the dressed/stage reference mockup visible in conversation context. For local files, call `read_file` on both images immediately before object-list extraction or object/prop generation.
-2. Create a concrete object list from the visible reference mockup while cross-checking the original base/background: object id, type, approximate position, approximate size, render layer, collision role, and asset strategy.
-3. For each visible runtime object, generate a separate transparent asset, extract it from a generated pack, or represent it as a tile/object layer when the engine/editor pipeline is tile-based.
-4. For object/prop generation that must match the map style, pass the base/background and/or reference mockup sandbox paths, and state in the prompt that the provided reference images are the visual context. The generated asset must match the original map style and correspond to an object visible in the reference mockup.
-5. Generate or define the final props, platforms, terrain chunks, hazards, pickups, doors, gates, checkpoints, exits, foreground occluders, and other visible scene objects. Do not rely on the reference image as the runtime art for these objects.
-6. Write placement metadata, object layers, collision data, scene hooks, camera bounds, exits, and zones.
-7. Compose a QA preview from the original base/background plus the final runtime objects.
-
-For playable maps, layered maps with props, side-view stages, engine scenes, and requests for separate/editable props, stopping after the reference mockup is a failed/incomplete run.
-
-For prop packs or object packs generated after a reference mockup, derive the object list and prompt from the visible reference mockup and original base/background. Do not generate generic props from memory or filenames.
-
-## Visual Model
-
-### `baked_raster`
-
-Use when:
-
-- the scene is static, decorative, fixed-screen, or visual-first
-- the game needs a battle background, title scene, menu backdrop, cutscene, or quick prototype
-- collision is absent or can be represented by a few invisible shapes
-- the user explicitly asks for a single flat image or background
-
-Deliver one image generated or edited through image generation, plus optional collision/zones metadata.
-
-Do not use this as the final runtime map for platformers, RPG exploration, tower defense, or any scene where props, platforms, hazards, exits, or interactables must be edited, collided with, reused, or rendered independently.
-
-### `layered_raster`
-
-Use when:
-
-- a hand-painted or generated base map is best, but tall objects need collision, occlusion, interaction, reuse, or later editing
-- the scene is an RPG town, shrine, dungeon room, field, interior, or monster-taming exploration map
-- y-sorted actors should walk in front of and behind props
-
-Deliver an image-generated ground-only base image, separate image-generated props, placement metadata, collision/zones metadata, and a flattened preview.
-
-The base image must be foundation-only: terrain, roads, water, floor markings, and boundaries are allowed; tall props, buildings, trees, signs, doors, chests, pickups, actors, hazards, and occluders must be separate assets or object/tile layers.
-
-### `tilemap`
-
-Use when:
-
-- the engine/editor already uses Tiled, LDtk, Phaser tilemaps, Godot TileMap, Unity Tilemap, or similar tooling
-- the user asks for tiles, tilesets, tile collision, autotiling, or editable grid-perfect maps
-- procedural generation, large maps, or editor workflows matter
-
-Deliver image-generated or user-supplied tileset images, engine-native map data, tile layers, object layers, and tile/object collision. Do not script-draw the tileset as final art unless the user explicitly asked for procedural placeholders.
-
-Do not flatten tile layers, object layers, collision-relevant props, pickups, doors, hazards, or interactables into one runtime background image.
-
-### `layered_tilemap`
-
-Use when:
-
-- the game needs multiple tile layers such as ground, decor, walls, overhead, and foreground
-- actors need to pass under selected tile layers
-- collision and triggers are tile/object-layer driven
-
-Deliver image-generated or user-supplied tileset art, layered tile data, and a render-order contract.
-
-### `parallax_layers`
-
-Use when:
-
-- the map is a side-scroller, platformer, runner, shooter, side-view brawler, scrolling action stage, or scrolling backdrop
-- background depth matters more than top-down collision
-
-Deliver image-generated background, midground, foreground, and scroll-speed metadata.
-
-For a playable side-view scrolling/action stage, parallax layers are only the scenery. Generate an in-world stage reference mockup from the visible background using the visual reference handoff, then continue through post-reference object production. The playable stage still needs separate runtime objects for platforms or walkable lanes, terrain chunks, hazards, pickups, doors, checkpoints, gates, exits, scene hooks, camera bounds, and explicit collision.
-
-The runtime background for this preset must be scenery-only. Put collidable foreground geometry and reusable gameplay objects into `platform_objects`, tile/object layers, or engine-native nodes instead of baking them into the background image.
-
-For `side_scroll_mode`, use named parallax layers (`sky`, `far_bg`, `mid_bg`, `near_bg`, optional `foreground_overlay`) plus explicit scroll factors, shared `stage_canvas`, and loop/repeat policy. Do not treat a single scenery background as a complete side-scroller background stack unless the user explicitly asks for a flat/non-parallax background.
-
-## Runtime Object Model
-
-- `none`: the map is just a background or tile layers.
-- `separate_props`: props are independent sprites but do not require y-sort.
-- `platform_objects`: platforms, walkable lanes, terrain chunks, walls, hazards, foreground blockers, and other collidable stage geometry are independent runtime objects with placement and collision data.
-- `y_sorted_props`: props and actors sort by base `y`; use for top-down RPG scenes.
-- `interactive_scene_objects`: doors, pickups, switches, checkpoints, gates, destructibles, signs, exits, and other non-character scene objects with interaction or state.
-- `foreground_occluders`: selected overlays always draw over actors.
-- `scene_hooks`: metadata-only markers such as player spawn, actor spawn markers, encounter zones, patrol hints, arena triggers, camera bounds, exit links, and checkpoint ids. These do not require generated actor art.
-
-Use the simplest model that can express collision and occlusion correctly.
-
-## Collision Model
-
-- `none`: visual-only maps and simple backgrounds.
-- `coarse_shapes`: a few rectangles/ellipses for fixed arenas or decorative maps.
-- `precise_shapes`: explicit blockers and walk bounds for layered RPG maps.
-- `tile_collision`: collision stored per tile or tile layer.
-- `polygon_walkmesh`: irregular walkable regions or constrained path maps.
-- `trigger_zones`: encounter/rest/exit/dialogue areas; often combined with another collision model.
-
-Do not infer collision from prop PNG bounds automatically. Use explicit blockers for prop bases and explicit walkable zones for navigation.
-
-## Engine Target
-
-- `raw_canvas`: use PNG assets, JSON metadata, and project-specific render code.
-- `Phaser`: prefer atlas/tilemap JSON when the project already uses Phaser loaders; visual assets still come from image generation or existing art.
-- `Tiled_JSON`: produce Tiled-compatible tilesets, layers, objects, and custom properties around image-generated or existing tileset art.
-- `LDtk`: produce or adapt to LDtk entity/layer concepts if the project uses LDtk, while preserving image-generated or existing art as the visual source.
-- `Godot_TileMap`: produce tile layers and scene metadata matching Godot's structure after generating or selecting the visual tileset art.
-- `Unity_Tilemap`: produce tileset/sprite assets and placement data for Unity workflows after generating or selecting the visual art.
-- project-native: preserve existing schema when a game already has one.
-
-## Presets
-
-### Fixed Battle Background
-
-- `visual_model`: `baked_raster`
-- `runtime_object_model`: `none`
-- `collision_model`: `none` or `coarse_shapes`
-- Typical deliverables: one PNG, optional zones.
-
-### RPG Exploration Scene
-
-- `visual_model`: `layered_raster`
-- `runtime_object_model`: `y_sorted_props`
-- `collision_model`: `precise_shapes + trigger_zones`
-- Typical deliverables: base map, prop images, placement JSON, collision JSON, preview.
-
-### Monster Grassland
-
-- `visual_model`: `layered_raster`
-- `runtime_object_model`: `y_sorted_props + interactive_scene_objects + scene_hooks`
-- `collision_model`: `precise_shapes + trigger_zones`
-- Good prop-pack candidates: rocks, shrubs, flowers, signs, small logs.
-
-### Tile-Based Dungeon
-
-- `visual_model`: `layered_tilemap`
-- `runtime_object_model`: `interactive_scene_objects + scene_hooks`
-- `collision_model`: `tile_collision + trigger_zones`
-- Use only when the engine/editor supports tilemaps.
-
-### Side-View Scrolling Stage
-
-- `visual_model`: `parallax_layers`
-- `runtime_object_model`: `platform_objects + interactive_scene_objects + scene_hooks + foreground_occluders`
-- `collision_model`: `precise_shapes` or engine-native platform/object collision
-- Typical deliverables: shared `stage_canvas`, separate parallax layers (`sky`, `far_bg`, `mid_bg`, `near_bg`, optional `foreground_overlay`) matching that canvas, scroll factors, in-world stage reference mockup, separate platform/terrain sprites, foreground pieces, hazards, pickups, doors, checkpoints, gates, exits, scene-hook metadata, camera bounds, collision metadata, and a stage preview.
-
-### Side-View Action / Platformer Stage
-
-- `visual_model`: `parallax_layers` or `layered_tilemap` if the engine/editor already uses tiles
-- `runtime_object_model`: `platform_objects + interactive_scene_objects + scene_hooks + foreground_occluders`
-- `collision_model`: `precise_shapes` or engine-native platform/object collision
-- Applies to Megaman-like, Castlevania-like, Contra-like, side-view action, runner, shooter, and brawler stages across pixel art, clean HD, and project-native styles.
-- Required deliverables: shared `stage_canvas`, background/parallax art that matches that canvas, in-world stage reference mockup, separate platform or terrain-chunk sprites, hazard sprites, scene object placement data, scene-hook metadata, pickups/doors/checkpoints/gates when present, collision data, camera bounds, and a QA preview.
-- The stage reference should plan no more than 9 distinct visible object candidates unless the user requests a larger pass. Use repeats in metadata rather than asking the image model to invent many unrelated props at once.
-- Anti-pattern: one generated full-stage PNG plus collision rectangles. That is a background with hitboxes, not a playable stage.
-
-## Escalation Heuristic
-
-Start with the smallest playable bundle that works:
-
-1. non-playable background: `baked_scene_mode`
-2. beautiful top-down or tower-defense demo: `scene_mode`
-3. editable top-down/platform/grid map: `tile_mode`
-4. playable side-view scrolling/action stage: `side_scroll_mode`
-5. tactical/factory/board rules-first scene: `grid_mode`
-6. procedural/modular room assembly: `room_chunk_mode`

package/skills/grok-generate2dmap/references/object-production-gate.md

@@ -1,24 +0,0 @@
-# Post-Reference Object Production Gate
-
-An in-world reference mockup is never the final deliverable by itself. After generating `dressed-reference` or `stage-reference`, continue with:
-
-1. Make both images visible in conversation context before any object/prop generation:
-   - the original `base` or `background`
-   - the generated `dressed-reference` or `stage-reference` mockup
-2. If either image is a local file, call `read_file` on it immediately before writing object lists or object/prop image prompts. Do not rely on file paths alone.
-3. Create a concrete object list from the visible reference mockup while cross-checking the original base/background: object id, type, approximate position, approximate size, render layer, collision role, and asset strategy.
-   - If the reference contains more than 9 distinct visible runtime object candidates, reduce the generated asset list to the 9 most gameplay-relevant candidates first, then represent extra repeats or low-value decorations through placement metadata or a later asset pass.
-   - Classify every object before generation. Compact decorative props may be batched; wide/long, tall/large, collision-bearing, and tileset/strip objects must use one-by-one, strip, custom wide pack, tile/object-layer, or engine-native strategies.
-4. For each visible runtime object, choose exactly one asset strategy:
-   - generate a separate transparent asset with `$generate2dsprite` or direct `imagine_text_to_image`
-   - extract it from a generated prop/object pack
-   - represent it as a tile/object layer if the engine/editor pipeline is tile-based
-5. For every object/prop generation that must match the map style, pass the base/background and/or reference mockup via `imagine_image_to_image` (`file_path`) or `imagine_reference_to_image` (path list for 2+) — and say in the prompt that the provided reference images are the visual context. The generated asset must match the original map style and correspond to an object visible in the reference mockup.
-6. Generate or define the final platforms, terrain chunks, props, hazards, pickups, doors, gates, checkpoints, exits, foreground occluders, and other visible scene objects. Do not skip this step just because the reference mockup already contains them visually.
-7. Write placement metadata such as `data/<name>-props.json`, `data/<name>-objects.json`, engine-native object layers, or tile/object data.
-8. Write collision, zones, scene hooks, camera bounds, and exits as structured metadata.
-9. Compose a QA preview from the original base/background plus final runtime objects.
-
-Reference-only output is incomplete for any playable map, layered map with props, side-view stage, engine scene, or request that asks for separate props/editable objects. Only stop at a reference mockup if the user explicitly asks for a reference-only concept image.
-
-For prop packs or object packs generated after a reference mockup, the prompt must be derived from the visible reference mockup and original base/background, not from memory or filenames. It should list the exact objects being generated and preserve the art style, lighting, perspective, and scale cues from the original base/background.

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

@@ -1,149 +0,0 @@
-# Map Pipeline: parameters, workflow, and scripts
-
-Read this once the `map_mode` is chosen and you are about to produce assets.
-
-## Parameter Contract
-
-User-facing parameters may be stated in natural language:
-
-- `map_mode`: tile_mode | scene_mode | side_scroll_mode | grid_mode | room_chunk_mode | baked_scene_mode
-- `map_kind`: overworld | town | dungeon | shrine | arena | battle_bg | side_scroller | side_view_action | platformer | metroidvania | brawler | tower_defense | survivors_like | tactical | factory | card_board | room_chunk
-- `visual_model`: baked raster | layered raster | tilemap | layered tilemap | parallax
-- `size`: pixel dimensions, tile dimensions, or camera-relative size
-- `stage_canvas`: exact pixel dimensions and aspect ratio for side-scroll/parallax layers, references, and previews
-- `perspective`: top-down | 3/4 top-down | side-view | isometric-like
-- `art_style`: clean_hd | pixel_inspired | retro_pixel | hand_painted | project-native
-- `visual_asset_source`: imagine_text_to_image | existing_assets | procedural_placeholder
-- `collision_precision`: none | coarse | precise | tile | walkmesh
-- `prop_generation`: none | one_by_one | prop_pack_2x2 | prop_pack_3x3 | prop_pack_4x4 | platform_strip_1x3 | platform_strip_1x4 | custom_wide_pack
-- `output_format`: PNG only | layered preview | manifest JSON | engine-native map data
-
-When unspecified:
-
-- Use `imagine_text_to_image` as the visual asset source.
-- Infer `map_mode` from genre and editing needs before selecting lower-level axes.
-- Use `tile_mode` for Pokemon-like, top-down RPG, monster-taming, editor/grid-perfect, or tilemap requests.
-- Use `scene_mode` for tower defense, survivors-like, cozy/top-down showcase maps, and base-map-plus-props requests.
-- Use `side_scroll_mode` for side-scrollers, platformers, runners, side-view action, brawlers, Metroidvania side rooms, Mega Man-like, Castlevania-like, Contra-like, and parallax background requests.
-- For `side_scroll_mode`, choose a canonical `stage_canvas` before image generation. Use the project camera/viewport aspect when available; otherwise default to a 16:9 side-scroller canvas such as `1536x864`. All primary parallax plates, stage references, and previews must preserve this same size/aspect.
-- Use `grid_mode` for tactical RPGs, factory/automation maps, board/card battlers, build grids, and terrain-cost maps.
-- Use `room_chunk_mode` for modular rooms, roguelike rooms, procedural room assembly, or Metroidvania room-chunk planning.
-- Use `baked_scene_mode` only for non-playable visual scenes or explicitly flat images.
-- Use `baked_raster + coarse_shapes` only for battle backgrounds, title/menu scenes, cutscenes, decorative backdrops, non-playable previews, or when the user explicitly asks for a single flat image.
-- Use `layered_raster + y_sorted_props + precise_shapes` for top-down RPG exploration with tall props, occlusion, interactables, or reusable props; the base must be foundation-only and the props/interactables must remain separate.
-- Use `tilemap` or `layered_tilemap` only when the engine/editor already uses tiles or the user asks for editable tiles; do not flatten gameplay objects into one background image.
-- Use `parallax_layers + platform_objects + interactive_scene_objects + scene_hooks + precise_shapes` for playable side-view scrolling stages, platformers, runners, shooters, and horizontal action scenes; the parallax/background image is scenery-only and is not the runtime map by itself.
-- Use square prop packs only when 4 or more compact small/medium static props share one style and fit comfortably inside equal square cells.
-- Use one-by-one, platform strips, tile/object layers, or custom wide packs for hero props, buildings, gates, irregular large props, wide/tall props, platforms, terrain chunks, bridges, walls, ladders, long hazards, animated props, or props needing strong identity or collision alignment.
-- Use `clean_hd` for generated exploration maps unless the project or user asks for pixel art. This means clean hand-painted top-down 2D RPG game map, HD game asset style, sharp readable terrain shapes, low texture noise, and no chunky pixels.
-- Use `pixel_inspired` only when the user wants a pixel-adjacent look without retro chunkiness.
-- Use `retro_pixel` only when the user explicitly asks for 16-bit, retro JRPG, or classic pixel-art maps.
-
-## Workflow
-
-1. Inspect the target game.
-   - Find camera size, map dimensions, coordinate system, render order, asset loading, collision support, zone data, and existing map formats.
-   - Preserve the engine's existing style and data contracts.
-
-2. Choose the pipeline axes.
-   - Choose `map_mode` first. Use the genre routing table in `map-strategies.md` when the user describes a game type instead of a technical map format.
-   - Select `visual_model`, `runtime_object_model`, `collision_model`, and `engine_target`.
-   - If the request is for a playable map, stage, level, room, prototype, or game scene, choose a pipeline with explicit runtime objects. Do not downgrade to `baked_raster` unless the user asked for a background-only image.
-   - If the request implies a playable side-view scrolling/action stage, such as a side-scroller, platformer, runner, shooter, brawler, scrolling combat stage, Megaman-like stage, Castlevania-like stage, or Contra-like stage, lock the map pipeline to `parallax_layers + platform_objects + interactive_scene_objects + scene_hooks + precise_shapes` unless the engine already requires a tilemap.
-   - Select `art_style`. Prefer readable gameplay shapes over decorative texture density.
-   - Select `visual_asset_source`. Default to `imagine_text_to_image`; use `existing_assets` only when the project already has suitable art; use `procedural_placeholder` only when explicitly requested.
-   - Treat `hybrid` as a result of combining axes, not as a primary category.
-
-3. Produce assets.
-   - Write the creative prompts manually and use built-in `imagine_text_to_image` for visible map art unless the user explicitly chose existing assets or procedural placeholders.
-   - For baked raster maps, generate one background with built-in `imagine_text_to_image`, or edit/use an existing image when supplied, then add optional collision/zones metadata.
-   - For playable or editable layered maps, generate a foundation-only base/background first. The base must not contain runtime-controlled props, interactables, hazards, doors, gates, pickups, actors, or foreground occluders. If it does, regenerate or demote it to a reference artifact.
-   - For layered raster maps, generate a ground-only/foundation-only base map first. Then perform the visual reference handoff and generate an in-world dressed reference mockup from the visible base before making final props and placements.
-   - For tilemaps, generate or reuse tileset art first, then follow the engine/editor format for layers, objects, collision, and scene files. Do not script-draw the tileset as the final art source, and do not flatten object layers into a single runtime image.
-   - For `grid_mode`, generate or reuse grid/tileset visual art first, then write cell metadata such as walkable/buildable flags, move cost, terrain effects, resource nodes, and object layers.
-   - For `room_chunk_mode`, define chunk dimensions, exits, connection sockets, collision contract, and spawn/trigger metadata before final art assembly. Chunks must be reusable and validated at their seams.
-   - For playable side-view scrolling/action stages, define the canonical `stage_canvas` before generating art. Generate named scenery-only parallax layers first: `sky`, `far_bg`, `mid_bg`, `near_bg`, and optional `foreground_overlay`. Every primary parallax layer must use the same pixel dimensions, aspect ratio, camera framing, horizon line, and top-left anchor as the `stage_canvas`; do not accept mismatched image sizes that require guesswork to stack. Do not treat one full-width background image as a complete `side_scroll_mode` background stack unless the user explicitly asks for a flat/non-parallax background. These parallax passes must not contain playable foreground platforms, walkable floors, terrain chunks, hazards, pickups, doors, gates, checkpoints, crates, fences, spikes, or other runtime objects. Then perform the visual reference handoff and generate an in-world stage reference mockup that visually places up to 9 distinct intended platform/object candidates before generating final separate scene objects and metadata.
-   - If a side-view background already contains collidable-looking foreground geometry, walkable floors, or reusable gameplay props, reject it as a runtime background and regenerate a cleaner scenery-only background before continuing.
-   - Treat the reference mockup as a checkpoint, not a deliverable. Do not stop after generating it. After the relevant `dressed-reference` or `stage-reference` exists, inspect it and continue into the post-reference object production gate (`object-production-gate.md`).
-   - Do not present a rerunnable script that creates the whole art pack as the main solution unless the user asked for procedural placeholder art.
-
-4. Build metadata.
-   - Store prop placement, player spawns, actor spawn marker metadata, interactable scene objects, blockers, walk bounds, encounter zones, exits, camera bounds, and triggers as structured data.
-   - For `grid_mode`, store grid dimensions, cell size, tile ids, terrain types, walkable/buildable flags, movement cost, collision, resource nodes, and object/entity slots.
-   - For `room_chunk_mode`, store chunk id, size, entrances/exits, connection sockets, collision, spawn markers, camera bounds, and validation hints for seam alignment.
-   - For `side_scroll_mode`, store `stage_canvas`, parallax layer source size, display size, anchor, render order, scroll factors, loop/repeat policy, camera bounds, platform collision, hazards, exits, checkpoints, and actor spawn marker metadata.
-   - Keep collision independent from pixels unless the target engine explicitly uses tile collision.
-
-5. Validate and preview.
-   - Compose a flattened preview for layered maps.
-   - Validate image sizes, alpha channels, prop pack extraction metadata, JSON parseability, and critical walkability points when collision matters.
-   - For `side_scroll_mode`, reject or normalize mismatched primary parallax layer sizes before runtime integration. The stage reference and QA preview must match `stage_canvas` exactly. Deterministic resizing/cropping/padding is allowed only as a normalization step on generated art, not as a way to invent missing art.
-
-## Prop Generation Rules
-
-Use `$generate2dsprite` for reusable transparent props and visible scene objects, but the agent must write the prop prompt itself using the selected map `art_style`. Do not use a script to generate the creative prompt. For `clean_hd` maps, explicitly request clean hand-painted HD 2D game assets and explicitly forbid pixel art. For `pixel_inspired`, request clean modern pixel-art-inspired props without retro chunkiness. For `retro_pixel`, request 16-bit or retro JRPG pixel art.
-
-Before any prop/object image generation, classify each visible runtime object from the reference mockup:
-
-- `compact_prop`: small/medium, roughly square or vertical, decorative or simple blocker, no exact alignment requirement
-- `wide_or_long_object`: expected aspect ratio wider than about `1.6:1`, such as platforms, floor pieces, bridges, wall runs, fence rows, long traps, long signs, pipes, rails, ledges, or roads
-- `tall_or_large_object`: expected aspect ratio taller than about `1.6:1` or visually dominant, such as large trees, gates, towers, buildings, banners, doors, statues, or boss-room props
-- `collision_bearing_object`: must line up with collision, walkable edges, build pads, doors, checkpoints, gates, hazards, or engine editor handles
-- `tileset_or_strip_piece`: should repeat seamlessly or assemble from left/middle/right caps, corners, slopes, tops, sides, or tile pieces
-
-Generation strategy is determined by that classification:
-
-- Only `compact_prop` objects may use square `prop_pack_2x2`, `prop_pack_3x3`, or `prop_pack_4x4`.
-- Do not put `wide_or_long_object`, `tall_or_large_object`, `collision_bearing_object`, or `tileset_or_strip_piece` into square prop packs.
-- Use `one_by_one` for important, large, tall, irregular, identity-sensitive, or collision-aligned objects.
-- Use `platform_strip_1x3` or `platform_strip_1x4` for repeatable floors/platforms: left cap, middle repeat, right cap, plus optional corner/slope/end variant.
-- Use `custom_wide_pack` only for several similar wide objects that share one category and can use wide cells such as `768x256`, `1024x384`, or another explicit non-square cell size.
-- Never mix compact decorative props with platforms, terrain chunks, gates, doors, hazards, or other collision-critical objects in the same generated sheet.
-- If a square pack fails because a wide/tall object touches an edge, do not retry the same square pack with looser QC. Reclassify that object and regenerate it one-by-one, as a platform strip, as a custom wide pack, or as tile/object-layer art.
-
-Choose the generation shape deliberately:
-
-- `one_by_one`: safest for large, important, animated, or irregular props.
-- `prop_pack_2x2`: 4 related compact props, safest square batch size.
-- `prop_pack_3x3`: 9 compact small/medium props, good quality/time tradeoff.
-- `prop_pack_4x4`: 16 very simple compact small props; fastest but most likely to drift or touch edges.
-- `platform_strip_1x3`: repeatable non-actor platform/floor strip with left cap, middle repeat, and right cap.
-- `platform_strip_1x4`: repeatable non-actor platform/floor strip with left cap, middle repeat, right cap, and one extra slope/corner/end variant. This is not an animation-frame format and must not be used for characters, enemies, creatures, NPCs, summons, or animated body assets.
-- `custom_wide_pack`: several related wide objects using explicit wide cells, not square cells.
-
-Prop packs save image-generation calls and prompt overhead, but reduce per-prop control. Use square prop packs for rocks, shrubs, barrels, small signs, lamps, crates, floor ornaments, plants, and repeated compact environmental props. Do not use square prop packs for buildings, gates, trees with wide canopies, bridges, platforms, floors, walls, ladders, long fences, long hazards, character-like statues, hero objects, or anything that must be pixel-perfect or collision-aligned.
-
-For layered maps with generated props, prefer this in-world reference mockup pipeline:
-
-1. Generate `assets/map/<name>-base.png` as ground-only terrain.
-2. Hand the base 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 dressed-reference prompt, explicitly say: use the provided base image as the visual reference, preserve its camera/framing/dimensions/terrain/road/water/boundaries, and generate an in-world dressed reference mockup.
-4. The dressed reference must show proposed props as natural game-world objects placed on the base. It must not contain circles, arrows, outlines, labels, text, callouts, legends, highlighted boxes, or other annotation graphics.
-5. The dressed reference should contain at most 9 distinct visible prop/object candidates unless the user explicitly asks for more. Prefer the objects that will become final generated props, collision blockers, interactables, or occluders.
-6. Generate `assets/map/<name>-dressed-reference.png` from the visible base. Treat this as a reference mockup, not the final runtime map.
-7. Generate one-by-one props or a prop pack based on the dressed reference.
-8. Place extracted props over the original base and compose a flattened preview.
-9. Validate that base, dressed reference, and preview dimensions match.
-
-## Scripts
-
-Use the extract script after generating a solid-magenta prop sheet (built-in magenta cleanup is enough for most sheets):
-
-```bash
-python3 .grok/skills/generate2dmap/scripts/extract_prop_pack.py \
-  --input assets/props/raw/<name>-sheet.png \
-  --rows 3 --cols 3 \
-  --labels <comma-separated-labels> \
-  --output-dir assets/props \
-  --manifest assets/props/<name>-prop-pack.json \
-  --component-mode largest
-```
-
-Compose a QA preview:
-
-```bash
-python3 .grok/skills/generate2dmap/scripts/compose_layered_preview.py \
-  --base assets/map/<name>-base.png \
-  --placements data/<name>-props.json \
-  --output assets/map/<name>-layered-preview.png
-```