{
  "markdown": "# gemini-pixel-sprite-gen\n\nA Claude Code skill for producing **chunky low-res pixel-art game sprites**\nwith consistent style across an entire roster — characters, monsters, and\nboss variants — using Google Gemini for generation and a deterministic\npost-process for snap+normalize.\n\nOutput is engine-agnostic: chunky-pixel `<char>_<action>.png` files with binary alpha — drop into any 2D engine (Godot, Unity, Pico-8, raylib, web canvas, etc.).\n\n---\n\n## Requirements\n\n- Python 3.10+\n- Google Gemini subscription (logged in to gemini.google.com in Chrome or Firefox)\n- Claude Code\n\n---\n\n## Installation\n\n```bash\n/plugin marketplace add nakzyu/gemini-pixel-sprite-gen\n/plugin install gemini-pixel-sprite-gen@gemini-pixel-sprite-gen\n```\n\nLocal dev:\n\n```bash\ngit clone https://github.com/nakzyu/gemini-pixel-sprite-gen.git\nclaude --plugin-dir ./gemini-pixel-sprite-gen\n```\n\nDependencies are auto-installed on first run.\n\n---\n\n## First-run setup\n\nThe skill walks you through:\n\n1. **Output dir** — where sprites are saved (default `./sprites`).\n2. **Canonical style anchor** — a single reference image that locks the art\n   style for the entire project (chunky pixel size, palette feel, body\n   proportions). Every new character/monster's first frame uses this as the\n   anchor. **Mandatory** — without it, generation drifts.\n3. **`sprite_spec.yaml`** — project-level config defining `target_h` and\n   `cell_h` for characters and monsters. Defaults: chars 32/48, monsters\n   64/72. Created if missing.\n\nYou can stop here if you only need single-shot generation. The chunky\npixel-art pipeline below kicks in when you ask for game characters / sprite\nrosters / multiple poses.\n\n---\n\n## The pipeline\n\nFor game-ready sprites with multiple poses per creature, the skill follows a\nlocked-in two-step pipeline: **generate → snap**.\n\n### Step 1 — Generate (Gemini)\n\n```\n/gemini-pixel-sprite-gen recruit, female warrior, simple sword and tunic, idle pose\n```\n\nThe skill picks the right anchor reference automatically:\n\n| Frame                              | Anchor (`--files`)                          |\n|------------------------------------|---------------------------------------------|\n| First frame of a NEW character     | Canonical style anchor                      |\n| Subsequent frames of same char     | That character's approved IDLE              |\n| First frame of a NEW monster       | Canonical style anchor                      |\n| Subsequent frames of same monster  | That monster's approved IDLE                |\n| Family-of-monster (e.g. giant_slime from slime) | Canonical + parent monster's IDLE |\n\n**Hard gate:** new subjects without an anchor → the skill stops and asks\nyou. No anchor-less generation.\n\nPrompts emphasize what *differs* from the reference (pose, outfit, color),\nnot the style itself — the reference image carries the style. This keeps\nthe chunky pixel grid consistent across the roster.\n\n### Step 2 — Snap (post-process)\n\n```bash\npython3 scripts/snap_single.py <gemini_output> <name> <action> \\\n  --out-dir <project>/sprites/sheets \\\n  --target-h 32 --cell-h 48        # characters\n  # OR --target-h 64 --cell-h 72   # monsters\n```\n\nThe snap pipeline:\n\n1. Tight bbox of the figure (alpha > 10).\n2. Optional `--top-crop N` to drop overlong hair/halo so the face survives at small native resolution.\n3. **Mode-downsample** — each dest pixel = majority opaque color of its source block.\n4. Largest connected component cleanup.\n5. **Outline pass** — alpha-edge dest pixels recolored with the darkest opaque color in their source block, recovering outlines that mode-color picks would dilute.\n6. Bottom-center align (feet at `cell_h - PAD`, x-centered).\n\nOutput: `<char>_<action>.png` only. No upscaled `_display.png`, no `_1x1` suffix.\n\n---\n\n## Style conventions (built into the skill)\n\n- **Characters** = clean Octopath chibi feel. Modest detail, friendly readable proportions, minimalist face (eyes only — no mouth, no nose).\n- **Monsters** = grotesque / vile. Irregular asymmetric forms, dripping ooze, visible innards, multiple uneven eyes, drooling fanged mouths, dark sickly palettes.\n- **Backgrounds** = ordinary scenes (grassland, forest, cave) with darkened palettes.\n- **Combat orientation** = side-view, left↔right. **Every attack pose extends horizontally** toward the opponent — never downward, never toward the camera.\n\nThese conventions are encoded in the skill's prompt templates so the user\ndoesn't have to repeat them.\n\n---\n\n## File layout\n\n```\n<project>/\n├── sprite_spec.yaml          # project config\n├── sprites/\n│   ├── references/\n│   │   └── <canonical>.png   # the style anchor\n│   ├── character/            # raw Gemini outputs (with chromakey)\n│   └── sheets/               # snapped game files\n│       ├── recruit_idle.png\n│       ├── recruit_attack.png\n│       ├── slime_idle.png\n│       └── ...\n└── skills/\n    └── gemini-pixel-sprite-gen/    # the skill (if installed locally)\n        ├── SKILL.md\n        ├── PIXEL_ART_PIPELINE.md\n        └── scripts/\n```\n\nFilename invariant: `<creature>_<action>.png`. No prefixes, no suffixes.\n\n---\n\n## Engine import notes\n\n- Set the engine's texture filter to **NEAREST** (no bilinear / no smoothing). Otherwise pixel art blurs.\n- Each `<creature>_<action>.png` is one frame. Wire them into your engine's animation system per creature.\n- Feet are at row `cell_h - PAD` from the texture top, x-centered. Set the sprite origin / offset so node position equals feet position (in Godot 4: `offset = (0, -PAD)`; in Unity: pivot bottom-center; in Pico-8: just blit at `(x, y - cell_h)`).\n- Cell sizes can differ across creatures (chars 48 tall, monsters 72 tall by default). Group same-tier creatures into one atlas if your engine wants uniform cell.\n\n---\n\n## When things go wrong\n\n- **Output drifted in style** → regenerate in a fresh session (`end-session` then start new). Session context can decay.\n- **Eyes/face details lost at small resolution** → snap with `--top-crop 40-100` to drop hair/halo; the face gets more dest pixels.\n- **Bent pose looks too detailed compared to idle** → snap the bent pose at lower target (e.g. `--target-h 28-30`) — bent figure has shorter source tight_h, h32 ends up finer.\n- **Outfit color changed in non-idle frame** → the prompt didn't preserve colors strongly enough. Add explicit color list (\"OUTFIT COLORS must match image 1 EXACTLY: [list]\").\n- **Attack aiming wrong direction** → the prompt forgot the horizontal-attack rule. Re-emphasize \"side-view battle, attack extending RIGHT (or LEFT) horizontally.\"\n\n---\n\n## Other commands\n\n```\n/gemini-pixel-sprite-gen list                    # show all generated sprites\n/gemini-pixel-sprite-gen list --category monster\n/gemini-pixel-sprite-gen delete <name>\n/gemini-pixel-sprite-gen organize                # remove orphaned manifest entries\n/gemini-pixel-sprite-gen sessions                # list active sessions\n/gemini-pixel-sprite-gen end-session <name>      # close a session\n```\n\nFor one-off non-game-asset generation (single illustration, item icon, UI\nelement), the chunky pipeline doesn't activate — the skill just generates\nand saves the image.\n\n---\n\n## How transparency works\n\nGemini cannot output PNG alpha channels — it draws checkerboard patterns\ninstead. This skill works around that:\n\n1. Appends chromakey green (`#00FF00`) background instruction to every prompt\n2. HSV-based color detection identifies and removes the green\n3. Edge pixels are despilled to remove green color bleed\n4. Result: clean PNG with binary (0 or 255) alpha — pixel-art friendly\n\n---\n\n## License\n\nMIT\n",
  "bytes": 7559,
  "sha": "a70ef52eb946575cfb9da3c023d799dfce16f9e4e1cd1f33d5be3f17123c247f",
  "repo_slug": "nakzyu/sprite-gen",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_nakzyu_sprite_gen_sprite_gen_cec24174/readme"
}