Pixel Art Studio

Pixel Art Studio

Self-contained studio: you author a build script that draws every pixel with scripts/pixelstudio.py (Pillow only), render a preview, look at it with your own eyes, critique, fix, repeat. That see→critique→fix loop is the entire quality engine — never skip it. You are the artist; the library is just your hand.

Requirement: python3 -c "import PIL" — if missing, pip3 install --user pillow.

The Loop

1. Brief — decide canvas size, palette (with a hard color budget), style, outline rule, light direction. Consult references/patterns.md + references/palettes.md, and check references/learned/INDEX.md for a studied style that matches.

2. Build script — create pixel-art/<slug>/build.py in the working directory. The script is the artwork's source of truth: it regenerates everything on each run. Parametrize shapes (positions, squash, frame offsets) instead of hardcoding every pixel twice — animation frames become function calls.

   pythonCopy code
   import sys; sys.path.insert(0, "/Users/game/Projects/.claude/skills/pixel-art-studio/scripts")
   from pixelstudio import Sprite, PALETTES, ramp, mix
   
   BODY = ramp("#38b764", 5)            # hue-shifted 5-step ramp from a base color
   s = Sprite(32, 32, palette=BODY + ["#1a1c2c", "#f4f4f4"])
   
   def draw_slime(squash=0):            # parametric → reuse for every frame
       s.ellipse(6, 12 + squash, 25, 27, BODY[0])          # darkest first
       s.ellipse(6, 11 + squash, 24, 26, BODY[2], only="opaque")  # restack lighter, shifted to light
       s.outline(BODY[0], where="inside")                  # selout
   draw_slime()
   
   s.preview("preview.png", scale=10)   # LOOK at this file
   s.stats()                            # and read these numbers
   

3. Run — cd pixel-art/<slug> && python3 build.py

4. LOOK — Read preview.png (plus s.save_silhouette() / s.zoom() when unsure). Critique against the checklist in references/validations.md, point by point, honestly.

5. Fix — edit build.py, rerun. Minimum 2–3 loop passes before showing the user.

6. Deliver — export master PNG at 1x and a display scale (4–8x), GIF/spritesheet if animated, then open the output files (user preference).

Work at true pixel size always; scale is an export-time concern and integer only.

API — scripts/pixelstudio.py

Colors everywhere: "#hex" | (r,g,b[,a]) | palette index (int) | None = erase. Most ops accept only= to clip: a color (paint only over that color), "opaque", "empty" — this is the masking system; the shifted-shape shading recipe in references/techniques.md builds on it.

Knowledge routing

Learning from user-provided art

When the user sends a pixel-art file to learn from (เรียนรู้/ศึกษาไฟล์นี้):

Persistence rule: learning changes the skill project itself. Resolve <skill> to the directory containing this SKILL.md and write durable knowledge only inside that directory. The caller's working directory, ./pixel-art/, clipboard paths, and <file>_study/ are source or temporary analysis locations; they are not the knowledge base. Never leave a completed study only in those locations.

1. python3 <skill>/scripts/study.py <file> [--save-palette <name>] → emits <file>_study/ with zoom.png, swatch.png, silhouette.png, report.json.
2. Read zoom.png and swatch.png — the report gives numbers (true size, palette, ramps, dither %, outline darkness); your eyes extract the techniques: cluster shapes, AA placement, where dither sits, how ramps map onto forms, outline behavior on the light side.
3. Write a study card <skill>/references/learned/NNN-<slug>.md from <skill>/references/learned/TEMPLATE.md — record pixel-level observations and imperative rules, not vibes.
4. Add one line to <skill>/references/learned/INDEX.md in the same change.
5. If the lesson generalizes beyond one visual style (animation, export, validation, cleanup, etc.), also update the relevant <skill>/references/*.md rule file and Knowledge routing.
6. --save-palette <name> makes the palette available forever as Sprite(palette="<name>"); verify that the saved palette data is also under <skill>, not beside the input file.
7. Before finishing, verify every newly learned durable file resolves under <skill>.

When later creating art in a studied style: open the matching card and follow its rules.

Hybrid pipeline — from generated/messy art (the "B" path)

When the user wants pixel art from an image model (codex-imagegen, SD+LoRA, FLUX, PixelLab export, a screenshot, or any messy PNG), this skill is the deterministic cleanup + lock + animate layer. Use references/cleanup.md for the full playbook. One command does the whole import→clean:

bashCopy code
python3 <skill>/scripts/pixelpipe.py <gen.png> --strip-checker --max-colors 24 --display 6
# lock to a shared game palette for cross-asset consistency:
python3 <skill>/scripts/pixelpipe.py <gen.png> --palette my_game
# learn the style while cleaning:
python3 <skill>/scripts/pixelpipe.py <gen.png> --strip-checker --study knight_style

It recovers the true grid (block-sampling for sloppy upscales), strips baked-in checkerboards, hardens alpha, despeckles, dedupes colors, locks the palette, and emits clean.png + a regenerable build.py you keep editing. After cleaning, switch back to the normal Loop (edit/animate/palette-swap deterministically) — that's where the skill beats the generator.

Conventions

• Artworks live in ./pixel-art/<slug>/ (build.py + all outputs together).
• Never hand-edit exported PNGs — edit build.py and rerun.
• Randomness only via noise(seed=) — renders must be deterministic.
• Deliverables get opened when done; report includes the 1x master path.