@inneranimalmedia/agentsam-sdk 2.6.4 → 2.6.7

package/skills/grok-generate2dsprite/references/prompt-rules.md

@@ -0,0 +1,315 @@
+# Prompt Rules
+
+Use this file when writing sprite prompts by hand.
+
+Do not delegate prompt writing to a script unless you specifically need parity with an older generated prompt.
+
+## Global Rules
+
+Always keep these constraints:
+
+- background is 100% solid flat magenta `#FF00FF`
+- no gradients in the background
+- no text
+- no labels
+- no UI
+- no speech bubbles
+- exact grid count only
+- no borders or frames between cells
+- same asset identity across frames
+- same bounding box and same pixel scale across frames
+- raw sprite art must come from built-in `imagine_text_to_image`, not Three.js, Canvas, SVG, HTML/CSS drawing, PIL shape drawing, procedural geometry, placeholder primitives, or code-rendered screenshots
+
+## Style Rules
+
+Choose the art style from the user request, project context, map context, or reference:
+
+- `pixel_art`: general sprite default for classic 2D game actors and animation sheets.
+- `clean_hd`: clean hand-painted HD 2D game asset style, crisp silhouettes, smooth surfaces, low texture noise, controlled lighting, no chunky pixels.
+- `pixel_inspired`: clean modern pixel-art-inspired style without 16-bit wording, heavy dithering, or noisy microtexture.
+- `retro_pixel`: 16-bit pixel art or retro JRPG pixel art, only when explicitly requested.
+- `map_style` or `project-native`: match the visible reference, existing game, or `$generate2dmap` selected art style.
+
+Do not write `16-bit`, `retro JRPG`, or `chunky pixel-art` unless the user asks for that look. For clean HD map props, explicitly say `Do not make pixel art`.
+
+## Reference Rules
+
+Use these rules when the user attaches a reference, points to a local image, asks for consistency with an earlier generated image, or asks for an evolution/variant of an existing sprite:
+
+- Pass the reference to built-in `imagine_image_to_image` as a sandbox `file_path`, and `read_file` it so you can see it too. Do not assume a path string in the prompt is a visual input.
+- In the prompt, say `use the provided reference image as the visual reference`.
+- State what must stay fixed: silhouette family, palette, face/eyes, costume or markings, accessories, material language, and art style.
+- State what may change: pose, animation phase, action energy, size progression, evolution traits, or FX intensity.
+- For animation sheets, preserve the same character identity in every cell and only change the animation pose or effect state.
+- For evolution lines, keep visible lineage markers while allowing larger silhouette, added details, or stronger colors per form.
+- Keep the normal magenta-background and containment rules even when using a reference.
+
+## Layout Guide Rules
+
+Use a layout guide when the sheet needs stronger geometric control than text alone can provide:
+
+- good fit: `3x3` and `4x4` prop packs, tileset-like atlases, fixed atlas rows, and non-directional 16-frame sequences such as casting, summoning, charging, death, or transformation
+- possible fit: `3x3` large idles or showcase loops when earlier generations drift in scale, spacing, or edge safety
+- risky fit: four-direction walk sheets, because guide pressure can make directional poses too centered and reduce locomotion clarity
+
+When using a layout guide, pass the guide PNG's sandbox path to `imagine_image_to_image`. Use it only to understand the rows, columns, equal invisible frame slots, centering, spacing, and safe padding. Do not reproduce the guide: no visible boxes, no safe-area rectangles, no center marks, no labels, no borders, no guide background.
+
+Keep the creative prompt agent-written. The layout guide only provides geometry; it must not replace the action plan, art style, identity lock, or containment rules.
+
+## Containment Rules
+
+For any sheet mode, say this explicitly when consistency matters:
+
+- the entire subject must fit fully inside each cell
+- no body part, effect, weapon, tail, wing tip, orb, spark, or smoke trail may cross a cell edge
+- leave magenta margin on all four sides
+- use the same silhouette scale in every frame
+
+If detached FX are undesirable, say:
+
+- no floating detached effects outside the main silhouette
+
+If detached FX are required, say:
+
+- detached effects must remain tightly grouped near the main subject and still fit inside the cell
+
+## View Rules
+
+- `topdown`: for overworld actors and player / NPC sheets
+- `side`: for projectiles, side-view units, impact FX
+- `3/4`: for creature battle sprites, bosses, showcase idles, side-view spellcasters
+
+## Character Style
+
+For `player` and `npc` when the request does not specify another style:
+
+- top-down 2D pixel art for a 16-bit RPG overworld
+- 3/4 view from slightly above
+- full body visible
+- chunky readable pixel-art with crisp dark outlines
+- enough margin for clean engine rendering
+
+## Map Prop Style
+
+For `prop` assets requested by `$generate2dmap`, match the selected map art style:
+
+- `clean_hd`: clean hand-painted HD 2D game asset style, crisp silhouettes, smooth painted surfaces, low texture noise, controlled accent lighting, no chunky pixels.
+- `pixel_inspired`: clean modern pixel-art-inspired prop, crisp readable shape, no 16-bit wording, no heavy dithering.
+- `retro_pixel`: 16-bit or retro JRPG pixel-art prop, only when the map is explicitly retro pixel.
+
+For clean HD props, use 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 unless requested.
+
+## Creature and FX Style
+
+For `creature`, `spell`, `projectile`, `impact`, `summon`, and `fx`:
+
+- strong silhouette
+- readable body colors or effect shape
+- battle-ready or gameplay-readable pose
+- avoid painterly composition drift between frames
+- if humanoid, keep it clearly non-player unless the user explicitly wants a player-like unit
+
+## Action Rules
+
+### `idle`
+
+Use:
+
+- neutral stance
+- subtle motion
+- weight shift or aura pulse
+- strongest idle accent before looping
+
+Prefer:
+
+- `2x2` for standard actors
+- `3x3` for large creatures and showcase idles
+
+### `cast`
+
+A `2x3` cast is often the best default:
+
+- readiness
+- energy gather
+- stronger gather
+- release start
+- release peak
+- settle or hold
+
+### `attack`
+
+For a compact attack-only sheet, describe:
+
+- wind-up
+- strike
+- follow-through
+- recovery
+
+For controllable heroes, main characters, and fixed-cell game sprites, write attack body prompts as body-only:
+
+- no detached slash arc
+- no wide weapon trail
+- no muzzle flash
+- no projectile
+- no impact burst
+- no detached dust cloud
+- weapon remains close enough that the body bbox stays near idle/run size
+- body height and feet/bottom anchor match the accepted idle/run sheet
+
+If the attack needs a large slash arc, sword trail, muzzle flash, or hit spark, generate it as a separate `fx`, `projectile`, or `impact` sheet and layer it in the runtime.
+
+### `hurt`
+
+For a hurt-only sheet, describe:
+
+- impact
+- recoil
+- stagger
+- recovery
+
+### `combat`
+
+For a compact combined sheet:
+
+- top-left: attack wind-up
+- top-right: attack strike
+- bottom-left: hurt impact
+- bottom-right: hurt recovery
+
+### `projectile`
+
+Usually prefer `1x4` or `2x2`.
+
+Describe:
+
+- same projectile identity in all frames
+- travel direction stays consistent
+- shape changes are small and loopable
+- glow or trail stays inside the frame
+
+### `impact` / `explode`
+
+Usually prefer `2x2`.
+
+Describe:
+
+- ignition or contact
+- expansion
+- peak burst
+- fade or collapse
+
+### `walk` / `run` / `hover`
+
+State the travel behavior clearly:
+
+- grounded stride
+- hover bob
+- crawl
+- slither
+- mechanical glide
+
+## Sheet-Specific Rules
+
+### Mixed-action atlas guardrail
+
+Do not use a single raw generated sheet to pack unrelated actions just because the target engine wants a `4x4`, `5x5`, or custom atlas.
+
+Avoid prompts like:
+
+- row 1 idle, row 2 run, row 3 shoot, row 4 jump
+- first row walk, second row attack, third row hurt, fourth row death
+- one big atlas containing every hero action
+
+For controllable heroes, main characters, and high-value player assets:
+
+1. Generate each action as its own multi-row grid sheet, usually `2x2` for 4-frame actions, `2x3` for 6-frame actions, and `2x4`, `3x3`, `3x4`, or `4x4` for longer actions.
+2. Keep attack/shoot/cast body animation separate from projectile, muzzle flash, slash arc, weapon trail, impact, and dust unless the runtime explicitly supports wider per-action cells plus explicit origins.
+3. Process and visually QC each action independently for feet line, body center, scale, silhouette, and edge safety.
+4. Reject a body action when the body appears more than about 10-15% smaller than idle/run because a wide FX bbox forced it to shrink.
+5. Assemble a `4x4`, `5x5`, or custom engine atlas only after the separate action sheets pass QC.
+
+Allowed raw multi-row sheets:
+
+- canonical four-direction locomotion sheets where every row is the same walk/run action in a different direction
+- one continuous non-directional long action sequence, read left-to-right across rows
+- prop packs or tileset-like atlases where each cell is intentionally a separate object
+- compact low-stakes enemy combat sheets, but not controllable hero production assets
+
+### `4x4` player sheet
+
+Use:
+
+- row 1: down
+- row 2: left
+- row 3: right
+- row 4: up
+- column 1: neutral
+- column 2: left foot forward
+- column 3: neutral again
+- column 4: right foot forward
+
+Do not use a layout guide by default for this sheet. Try an unguided prompt first unless the previous result crossed cell edges or failed the grid shape.
+
+### `3x3` large idle
+
+Say:
+
+- exactly 9 equal cells in a `3x3` grid
+- same bounding box in all 9 cells
+- subject fills only about 55% to 65% of each cell
+- no edge crossing anywhere
+
+Use a layout guide when a previous 3x3 result has uneven spacing, inconsistent scale, or edge-touching frames.
+
+### `4x4` non-directional action sequence
+
+Use for casting, summoning, charging, transformation, death, and other single-action loops:
+
+- exactly 16 equal cells in a `4x4` grid
+- read frames left-to-right across each row, then continue on the next row
+- describe each phase in order, from anticipation through peak action to settle or loop return
+- keep the subject identity stable while allowing pose, energy, and compact attached effects to change
+- use a layout guide when the action includes VFX, portals, circles, summons, or other elements that might cross cell boundaries
+
+Do not use this format as a shortcut for four unrelated hero actions. If the requested rows are different actions, treat it as a `hero_action_bundle` or `engine_atlas` delivery problem instead.
+
+### `5x5` and custom grids
+
+Use raw `5x5` or custom-grid generation only when the entire sheet is one coherent action family, a prop pack, a tileset-like atlas, or a single long sequence.
+
+For mixed action requirements, generate each action separately and assemble the final grid after QC. The assembled atlas is a delivery artifact, not the raw image-generation target.
+
+### `1x4` projectile
+
+Say:
+
+- exactly 4 equal cells in one row
+- same projectile size in every frame
+- only the internal energy or shape pulse changes
+
+## Bundle Prompting
+
+When generating a bundle, write each asset prompt independently.
+
+Good default decomposition:
+
+- caster unit
+- projectile
+- impact
+
+or:
+
+- idle
+- combat
+- walk
+
+Do not try to force unrelated assets into one giant sheet.
+
+## Quick Prompt Pattern
+
+1. state the asset type and sheet shape
+2. describe the subject identity
+3. if applicable, state the reference role and invariants
+4. describe frame-by-frame motion
+5. restate same-scale and containment rules
+6. restate magenta background and no-text rules