pixel-art-studio

像素艺术工作室

独立工作室：编写一个构建脚本，用 scripts/pixelstudio.py（仅依赖 Pillow）绘制每个像素，渲染预览，亲眼查看，再进行评估、修正并重复。查看→评估→修正的循环是整个质量引擎—— 绝不能跳过。你才是艺术家；这个库只是你的画笔。

要求：python3 -c "import PIL"——如果缺少 Pillow，请运行 pip3 install --user pillow。

工作循环

1. 确定方案——确定画布尺寸、调色板（并设定严格的颜色数量上限）、风格、描边规则和光照方向。参考 references/patterns.md 和 references/palettes.md， 并查看 references/learned/INDEX.md，寻找风格相符的研究案例。

2. 编写构建脚本——在工作目录中创建 pixel-art/<slug>/build.py。 该脚本是作品的唯一真实来源：每次运行都会重新生成所有内容。对形状进行参数化（位置、压扁程度、帧偏移），而不是把每个像素重复硬编码两次——动画帧可以通过函数调用生成。

   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. 运行——cd pixel-art/<slug> && python3 build.py

4. 查看——读取 preview.png（不确定时，还可以使用 s.save_silhouette() / s.zoom()）。 对照 references/validations.md 中的检查清单，逐项进行诚实评估。

5. 修正——编辑 build.py，然后重新运行。向用户展示前，至少完成 2–3 轮循环。

6. 交付——导出 1x 主 PNG 和显示尺寸版本（4–8x）；如果是动画，还要导出 GIF/精灵图集，然后 open 输出文件（遵循用户偏好）。

始终以真实像素尺寸创作；缩放只在导出时进行，且只能使用整数倍。

API — scripts/pixelstudio.py

颜色在所有位置均可使用："#hex" | (r,g,b[,a]) | 调色板索引（int）| None = 擦除。 大多数操作都接受 only= 来限制绘制范围：某种颜色（只在该颜色上绘制）、"opaque"、"empty"—— 这是遮罩系统；references/techniques.md 中的平移形状阴影绘制配方以此为基础。

区域	调用
画布	Sprite(w, h, palette=None, snap=True) · s.layer(name) · s.frame(i) · s.use(frame=, layer=)
绘制	px line rect(fill=) circle(cx,cy,r,fill=)（像素级精准）ellipse polygon contour fill(x,y) clear get(x,y) paste_png
像素艺术操作	outline(c, where="outside"/"inside") · mirror_x mirror_y · shift(dx,dy,wrap=) · replace(old,new) · dither(box,c1,c2,mix,pattern) · gradient_dither(box,colors) · noise(box,c,density,seed)
颜色	ramp(base, steps, hue_shift) · mix(c1,c2,t) · PALETTES · s.set_palette(p, remap=) · s.to_palette(p, dither=) · s.quantize(n)
清理（生成图/杂乱作品）	s.harden_alpha(threshold, steps) · s.despeckle(min_cluster) · s.dedupe_colors(tol) · s.dehalo() · s.clean(palette=, max_colors=, ...) · s.before_after(path)
动画	s.add_frame(copy=True) · s.set_duration(ms, frames) · s.tag(name, from, to, direction) · s.copy_cel(layer, from_frame, to_frames, link=) · s.del_frame
检查	s.preview(path, scale, grid=, labels=) · s.zoom(path, x0,y0,x1,y1) · s.save_silhouette(path) · s.stats() · s.save_swatch(path) · s.used_colors()
导出	s.save_png(path, frame, scale, bg) · s.save_gif(path, scale, tag, bg) · s.save_spritesheet(path, layout, scale, padding)（+引擎 JSON）· s.save_project / Sprite.load_project / Sprite.from_png(path, scale="auto", strip_bg=)

知识路由

任务	阅读
任何新作品（尺寸、Q 版/英雄风/高挑战术比例、先剪影后细节的顺序、图块）	references/patterns.md
色阶、阴影、抖动、抗锯齿、轮廓、纹理	references/techniques.md
动画（帧数、时序、骨骼操控、超大攻击帧格、稳定的枢轴点）	references/animation.md
类人生物角色（2 条手臂 + 2 条腿）——完整动作组（行走/挥砍/突刺/施法/射击/受伤）	references/lpc.md + scripts/lpc.py — 将帧组装到 LPC 通用图纸上（可直接用于引擎的布局）
调色板选择、预算、预设、学习到的调色板	references/palettes.md
导出格式、引擎（Unity/Godot/Phaser）	references/export.md
清理 AI 生成的/杂乱的作品、锁定调色板、混合流程	references/cleanup.md
已知故障模式——定稿前阅读	references/sharp_edges.md
每次迭代的评审清单	references/validations.md
从用户提供的作品中研究的风格	references/learned/INDEX.md

从用户提供的作品中学习

当用户发送像素画文件供学习时（เรียนรู้/ศึกษาไฟล์นี้）：

**持久化规则：**学习会改变技能项目本身。将 <skill> 解析为包含此 SKILL.md 的目录，并且只在该目录内写入持久知识。 调用方的工作目录、./pixel-art/、剪贴板路径和 <file>_study/ 都是来源或临时分析位置；它们不是知识库。完成的研究绝不能只留在这些位置。

1. python3 <skill>/scripts/study.py <file> [--save-palette <name>] → 生成 <file>_study/，其中包含 zoom.png、swatch.png、silhouette.png、report.json。
2. 阅读 zoom.png 和 swatch.png——报告会给出数据（实际尺寸、调色板、色阶、抖动百分比、轮廓暗度）；你需要用眼睛提取技法：色块形状、抗锯齿位置、抖动分布、色阶如何映射到形体，以及轮廓在亮面上的表现。
3. 根据 <skill>/references/learned/TEMPLATE.md，撰写研究卡片 <skill>/references/learned/NNN-<slug>.md ——记录像素级观察和命令式规则，而非主观感受。
4. 在同一项更改中，向 <skill>/references/learned/INDEX.md 添加一行。
5. 如果所得经验可泛化到一种以上的视觉风格（动画、导出、验证、清理等），还要更新相关的 <skill>/references/*.md 规则文件和知识路由。
6. --save-palette <name> 会让调色板永久可通过 Sprite(palette="<name>") 使用；请确认已保存的调色板数据也位于 <skill> 下，而不是输入文件旁边。
7. 完成前，确认每个新学习的持久文件都位于 <skill> 下。

之后以研究过的风格创作作品时：打开匹配的卡片并遵循其中的规则。

混合流程——从生成或杂乱的作品开始（“B”路径）

当用户希望从图像模型（codex-imagegen、SD+LoRA、FLUX、PixelLab 导出内容、屏幕截图或任何杂乱的 PNG）生成像素画时，此技能负责确定性清理、锁定和动画处理。完整操作指南见 references/cleanup.md。只需一条命令即可完成整个导入→清理流程：

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

它会还原真实网格（对粗糙放大的图像进行块采样）、去除烘焙进图像的棋盘格、强化 Alpha、去除杂点、合并重复颜色、锁定调色板，并生成 clean.png 和可重新生成的 build.py，后续编辑时应继续修改 build.py。清理后，切回常规循环（确定性地编辑/制作动画/替换调色板）——这正是此技能胜过生成器的地方。

约定

• 作品存放在 ./pixel-art/<slug>/（build.py 和所有输出放在一起）。
• 切勿手动编辑导出的 PNG——请编辑 build.py 并重新运行。
• 只通过 noise(seed=) 使用随机性——渲染结果必须是确定性的。
• 完成后对交付文件运行 open；报告中应包含 1x 主图的路径。