perfectpixel

PerfectPixel — AI animation sprite generation

Run the same generation pipeline as the installable desktop app (prompt → AI image generation → background removal → frame extraction → quality inspection → corrective regeneration → pixel quantization) via a headless CLI (ppgen) to create sprite bundles ready to use directly in games.

When to use this skill

Use when the user requests creation of a character/motion animation/spritesheet/8-direction set.
god-tibo-imagen (Codex ChatGPT backend) or gemini (Google AI Studio) models to generate high-quality, consistent sprites.
Use when defining a character with a single line of text description and generating animations by applying about 100 motion presets.
Use when efficiently building an 8-direction sprite set through 5-direction AI generation and 3-direction horizontal mirroring.

Instructions

Step 0 — Prerequisites (first step of every run)

ppgen Check/install the binary. In this SKILL.md's directory (= skill root), run the installation script. On success, output the absolute path of the binary as the last line.

# SKILL_DIR = 이 SKILL.md 파일이 있는 디렉토리의 절대경로로 치환할 것.
PPGEN="$(bash "$SKILL_DIR/scripts/install.sh" 2>/tmp/ppgen-install.log | tail -1)"
echo "$PPGEN"   # 이후 모든 ppgen 호출에 이 경로를 사용

Step 1 — API key and provider setup

ppgenlooks for the key in the following order: config.json(installable app settings) → in the working directory/next to the executable .env·.env.local → OS environment variables → CLI -key flag.

Gemini: GEMINI_API_KEY (or GOOGLE_API_KEY) setup. Default model: gemini-3-pro-image
GodTiboImagen: god-tibo-imagen provider uses a local ~/.codex/auth.json, so no separate API key is required, but to run the CLI you must pass a dummy key such as -key dummy. Default model: gpt-5.4

Step 2 — Request interpretation → flag mapping

Extract the following from the user's natural-language request and map it to ppgen flags.

Character description → -desc "..." (English prompt recommended)
Style → -style one of: pixel(default), chibi, cartoon, retro16
Motions to create → -states "idle,walk,attack" (comma-separated). Motion names are English preset keys.
Provider specification → -provider god-tibo-imagen or -provider gemini
Model specification → -model gpt-5.4 or -model gemini-3-pro-image
Output folder → -out ./output-dir (default ./perfectpixel-out)

Step 3 — Execution

Always run with -json to receive a machine-readable summary.

"$PPGEN" \
  -provider god-tibo-imagen \
  -desc "a small knight with silver armor and a blue plume" \
  -style pixel \
  -states "idle,walk,run,attack" \
  -out ./knight-sprites \
  -key dummy \
  -json

Examples

Example 1: Basic character and idle animation generation using god-tibo-imagen

"$PPGEN" \
  -provider god-tibo-imagen \
  -desc "a tiny blue slime" \
  -states "idle" \
  -out ./slime-sprites \
  -key dummy \
  -json

Example 2: 8-direction walking animation generation using gemini

"$PPGEN" \
  -provider gemini \
  -desc "a red wizard with a staff" \
  -dirset "walk" \
  -out ./wizard-walk-8dir \
  -key "$GEMINI_API_KEY" \
  -json

Best practices

Test run: To save cost and time, first do a test run with 1 state (-states idle) to check the style and quality, and after user approval, generate the full state.
Background color compliance: Enforce background color rules in the prompt so that the AI model perfectly fills a solid magenta (#FF00FF) background, and avoid magenta/pink/purple tones in character designs so that characters are not erased during matting.
Quality correction loop: -attempts Use the flag (default 3 times) to automatically inject correction hints and regenerate when frame count mismatches or character identity drift is detected.

About this skill