pixel-art-studio

Pixel Art Studio

Programmatic pixel art creation with palette discipline, dithering, animation, and automated quality control. Designed for production-quality output, not "look-pixelated filter on a photo."

When to use this skill

If user provides only a vague description ("a cat sprite"), pick the standard sprite workflow with 32×32 + Endesga 32 palette as the safe default, then offer to iterate.

---

Prerequisites

pip install Pillow numpy
# Optional but recommended for advanced quality checks:
pip install scikit-image scipy

Pillow is mandatory; numpy is mandatory; the rest are optional (the scripts will degrade gracefully).

---

Core principle: design discipline > pixel quantity

A 16×16 sprite with deliberate cluster choices reads better than a 64×64 with random pixel noise. Always start from the smallest grid that conveys the subject, expand only when needed for detail.

The four pillars of quality (encoded in scripts/quality_check.py):

1. Per-pixel hygiene — no orphan single pixels, no parallel doublies, no banded ramps
2. Cluster coherence — pixel groups read as recognizable shapes, not noise
3. Palette discipline — limited (≤32 typically), with hue rotation across luminance ramp
4. Silhouette readability — render-as-solid-shape and verify subject is recognizable

When in doubt, run quality_check.py after generation and fix issues until score ≥ 80/100.

---

Workflow 1: Single-frame sprite

Step 1 — Pick canvas size

When user is vague: 32×32.

Step 2 — Pick palette

Three modes:

• Bundled palette (recommended): Use scripts/palette.py --list to enumerate. Default for vague subjects: Endesga 32.
• Style-anchored palette: subject-specific recommendations in references/02-palette-theory.md
• Custom palette: 4-16 hex colors curated by hand. Validate with palette ramp checker.

Common style → palette mapping:

Step 3 — Design layer-by-layer

Always think in this order, not free-form:

1. Silhouette (darkest color, just outline) — does shape read at intended size?
2. Base fill — primary 1-2 colors covering largest areas
3. Cell shading — pick 3-4 discrete shades, place them per a single light direction (default: top-left)
4. Hue shift — shadows shift cooler+desaturated (toward blue-violet); highlights warmer+saturated (toward yellow-orange). Hue rotation across ramp ≥ 30°
5. Selective AA — only on staircase patterns longer than 1×1, using intermediate-color halftone strip
6. Details — eyes, patterns, small features. Each pixel must belong to a cluster ≥ 2-3 pixels (no orphans)

NEVER do pillow shading: dark border + light center regardless of light source. Auto-detected as anti-pattern in quality_check.py.

Step 4 — Generate JSON

Use the Sparse Coordinate JSON format. Minimal example:

{
  "width": 16,
  "height": 16,
  "background": "transparent",
  "pixel_size": 16,
  "palette_ref": "endesga-32",
  "pixels": [
    {"x": 7, "y": 4, "color": "#a8ca58"},
    ...
  ]
}

For animation, use the multi-frame extended schema (frames array — see Workflow 2).

Step 5 — Render PNG

python ${CLAUDE_PLUGIN_ROOT}/skills/creative/pixel-art-studio/scripts/render.py \
  sprite.json -o sprite.png

Step 6 — Quality check

python ${CLAUDE_PLUGIN_ROOT}/skills/creative/pixel-art-studio/scripts/quality_check.py sprite.png

Output is JSON. Score ≥ 80 = ship. Score 60-80 = fix issues listed. Score < 60 = redesign.

Step 7 — Display + iterate

Read the PNG with the Read tool to show user. Offer fixes for any quality issues flagged.

---

Workflow 2: Animation

Frame counts (production-validated)

Pick from this table — do NOT improvise frame counts.

Cultural variations:

• Western indie: 8-12 fps standard
• Chinese mobile RPG: 4-frame walk @ 200ms (5 fps) is documented standard
• Korean dot mobile: 6 frames @ 8-12 fps; chibi 4-frame walk
• Russian indie: typically follows Western, sometimes "Punch Club rule" (draw 1×, render 2-3×)

Animation principles (Disney → pixel art)

Only 3 of 12 translate without modification:

1. Timing — wind-up frames longer, action shortest, recovery eases
2. Anticipation — crouch before jump, wind-up before attack
3. Squash & stretch — even 1 pixel of compression on landing is effective

For walk cycles: 4-frame minimum is [contact, recoil, passing, high-point] and back. Don't add frames just to "smooth" — add anticipation/follow-through instead.

For attacks: [anticipation (slow), strike (1 frame, fast), recovery (eases back)]. Slowing down anticipation + speeding up action ≫ adding frames.

Smear frames (Korean Skul-style)

For fast attacks/throws, insert 1-2 stretched intermediate frames (smear). Heavy in Skul, less in Sanabi. See references/04-animation.md.

JSON schema for animations

{
  "width": 32,
  "height": 32,
  "background": "transparent",
  "palette_ref": "endesga-32",
  "frames": [
    {"id": 0, "duration_ms": 120, "pixels": [...]},
    {"id": 1, "duration_ms": 120, "pixels": [...]},
    {"id": 2, "duration_ms": 120, "pixels": [...]},
    {"id": 3, "duration_ms": 120, "pixels": [...]}
  ],
  "tags": [
    {"name": "walk", "from": 0, "to": 3, "direction": "forward"}
  ]
}

direction ∈ forward | reverse | pingpong (Aseprite convention).

Render animation

# Animated GIF
python scripts/animate.py walk.json --format gif -o walk.gif

# APNG (better, supports semi-transparency)
python scripts/animate.py walk.json --format apng -o walk.apng

# Sprite sheet (for game engines)
python scripts/animate.py walk.json --format spritesheet -o walk_sheet.png --layout horizontal

Animation quality check

python scripts/quality_check.py --animation walk.json

Checks: palette stability across frames (no off-palette colors), pixel rate consistency (sub-pixel-AA matches), total mass conservation (8-pixel torso stays 8 pixels across frames), per-frame quality scores.

---

Workflow 3: Image-to-pixel-art preprocessing

When user provides a real photo / hi-res illustration and asks for pixel art version.

Pipeline (in scripts/preprocess.py):

1. Downsample to target grid via Image.NEAREST (NOT bicubic — that introduces fractional pixels = AI-slop signal)
2. Extract palette via k-means or median cut (configurable colors: 8/16/32/64)
3. Quantize to extracted or chosen palette
4. Optional dithering to soften gradients (Floyd-Steinberg/Atkinson for photos; Bayer for halftone style)
5. Manual cleanup pass — agent reviews output and lists orphans, doublies for edits

Usage:

python scripts/preprocess.py photo.jpg --target-size 64x64 --palette aap-64 --dither floyd-steinberg -o pixel.png

Important: AI-generated art (Stable Diffusion, Midjourney) is NOT pixel art even if it looks pixelated. It usually has fractional pixel widths and noise instead of dithering. Always run preprocess pipeline + quality check on AI output before treating it as pixel art.

---

Workflow 4: Sprite sheet

For game engines (Unity, Godot, Unreal) wanting a single PNG with all frames.

# Layout: rows = animation type, cols = frames (canonical convention)
python scripts/animate.py character.json --format spritesheet \
  --layout grid --rows 4 --cols 8 -o character_sheet.png

Conventions:

• 1-2 px transparent padding between cells (configurable)
• Power-of-2 final dimensions when possible (engine-friendly)
• Optional .json metadata file alongside (Aseprite-compatible format)

---

Workflow 5: Quality review

When user asks "review this pixel art" or "is this good":

python scripts/quality_check.py existing_sprite.png --verbose

Returns JSON with:

• per-pixel hygiene: orphan count, doublies count, banding bands
• palette analysis: unique color count, ramp hue rotation, banding score
• silhouette readability: solid-fill recognizability (heuristic)
• anti-AI-slop signals: blurry edges count, fractional widths, gradient-over-flat detection
• overall score: 0-100

For Generator-Evaluator review (independent agent), invoke the pixel-art-reviewer agent (see agents/pixel-art-reviewer.md). It runs quality_check.py + reads the image with fresh context and writes a verdict.

---

Palette management

List bundled palettes

python scripts/palette.py --list

Returns 30+ palettes grouped by category:

• Hardware-authentic: nes, gameboy-dmg, pico-8, ega
• Lospec community: db16, db32, aap-64, endesga-32, endesga-64, sweetie-16, resurrect-64, apollo, steam-lords, slso8
• Cultural: obangsaek (KR), gugong-red-wall (CN), qinghua (CN), wuxing (CN), stoneshard-inspired (RU dark fantasy)

Extract palette from image

python scripts/palette.py --extract photo.jpg --colors 16 --method median-cut

Methods: kmeans (slow, high quality), median-cut (default, balanced), octree (fast).

Generate hue-shifted ramp

python scripts/palette.py --ramp "#5b3a3a" --steps 5 --hue-shift 40

Generates a 5-step ramp from dark→bright with proper hue rotation (Endesga rule). Use this when you need a fresh material color (skin tone, metal, leather) without a full palette.

---

Cultural style guides (when relevant)

The skill respects multiple cultural canons. Match the user's stated style:

---

Mandatory rules (will be quality-checked)

1. No orphan pixels unless intentional texture (sparkle, stippling). Default cap: 5% of total pixels.
2. No doublies — parallel double-thickness lines from accidental brush. Hard rule.
3. No pillow shading — dark-border-light-center regardless of light source. Hard rule.
4. Palette ≤ stated cap — if palette is endesga-32, output must use ≤32 unique colors.
5. Hue rotation ≥ 30° across any luminance ramp ≥ 4 colors. Soft warning, not hard error.
6. Selective AA — never on 45° lines, never on perfectly straight lines.
7. Outline (when present) darker than darkest object pixel (Punch Club / Stoneshard rule).

---

Gotchas

• Pillow Image.quantize defaults to median cut. For better quality on photos use method=Image.Quantize.LIBIMAGEQUANT if pyImageQuant is installed; otherwise MEDIANCUT is fine.
• GIF format limits: ≤256 colors, no semi-transparency. For semi-transparent animations use APNG (better) or WebP (modern but inconsistent compatibility).
• Sub-pixel "anti-aliasing" trick: animate the AA values between frames to suggest motion smaller than a pixel. Looks pro but doubles the AA pixel budget.
• CN walking timing: Chinese mobile games sometimes use 5fps (200ms/frame) walks — looks slow to Western eye but is documented standard. Don't "fix" it.
• 45° lines never get AA — common newbie mistake. AA on staircase patterns longer than 1×1 only.
• Indexed PNG vs RGBA PNG: indexed is smaller, faster, game-engine-friendly; RGBA preserves alpha. Default to RGBA in render.py; offer --indexed flag when palette is fixed.
• Aseprite source files (.aseprite) preserve tags, layers, palette in original form. If user has Aseprite installed, offer to export .aseprite alongside PNG.
• Background-color confusion: "background": "transparent" ≠ "#FFFFFF". Default to transparent for game sprites; use solid color only for non-cutout art.
• AI pixel art is not pixel art: SD/Midjourney outputs need preprocess.py pipeline. Don't trust their pixel grid alignment.

Troubleshooting

Reference index

Companion agent

For independent quality review (Generator-Evaluator pattern): invoke pixel-art-reviewer agent. It runs the quality scripts + reads the rendered image with fresh context, returning PASS/HOLD/REJECT verdict — see agents/pixel-art-reviewer.md for invocation pattern.