OmniSprite 🎮✨ — /sprite 命令
通过 pixel-mcp 服务器在 Aseprite 上实现精准的像素艺术工作流（工具目录：references/mcp-tools.md）。以用户的母语回复。
/sprite 命令
用法：/sprite [描述] [标志]。无参数时，询问用户要创建什么。
| 标志 | 效果 |
|---|---|
--tamanho S|M|L|XL|cena | 尺寸级别（默认 L，128×128） |
--estilo <预设> | references/styles.md 中的 12 种风格之一（默认 hd-pixel） |
--vista lateral|3-4|frontal|iso | 固定视角（默认侧面，面朝右侧） |
--anim idle,walk,attack,... | 需要动画的循环（配方见 references/animation.md） |
--paleta <lospec-slug|#hex,#hex|ref:路径> | 指定的调色板，来自 Lospec 或从图像派生 |
--doctor | 仅诊断：Aseprite 找到了吗？MCP 注册了吗？（步骤 0 的操作） |
--compilar | 强制从源代码编译 Aseprite 的工作流（步骤 0.4a） |
已提供的信息标志会跳过相应的提问；缺失的信息将在 grill-me 回合中询问。例如：/sprite 黑暗奇幻骑士 --tamanho L --anim idle,walk,attack。
0. 先决条件（即插即用；检查一次并修复缺失项）
- MCP 工具可见吗？（
create_canvas、draw_pixels、export_sprite…）。如果是，请转到步骤 1。 - 如果否，找到 Aseprite： 运行
scripts/find-aseprite.ps1（Windows）或scripts/find-aseprite.sh。退出码 0 打印路径；退出码 2 = 未找到。 - 找到 Aseprite → 运行
scripts/install-mcp.ps1/.sh（自动检测，下载固定版本的pixel-mcp，检查 SHA-256 并注册）。要求用户重启客户端，然后继续。 - 未找到 Aseprite → 询问用户（一次提问，带选项）；不要假设：
- “Aseprite 未安装。您希望我从 GitHub 下载其源代码、编译并配置吗？（需要 git、CMake、Ninja 和 C++ 编译器；大约需要 10–40 分钟；Aseprite 许可证允许编译用于个人用途，但不允许重新分发二进制文件。）”
- 选项：(a) 是的，为我编译（推荐）· (b) 我自己安装（Steam / aseprite.org / itch.io；付费，支持开发者）· (c) 跳过 Aseprite 并使用基于 Python/Pillow 的 B 计划（无
.aseprite文件，相同的风格规则）。 - 对于 (a)：运行
scripts/build-aseprite.ps1（Windows）或scripts/build-aseprite.sh。如果缺少先决条件，请说明缺少什么，并提供使用平台包管理器（winget / brew / apt）在询问后安装它。如果失败，请参考references/build-aseprite.md。完成后，执行步骤 3。
- 在结束简报（第 1 节）之前永远不要开始绘制。缺少回答 → 询问，或使用默认值并告知。
1. 简报（如果已安装请使用 grill-me）
将以下问题作为 grill-me 的一轮短问句提出（所有独立问题一起提出，每个问题都有建议答案，回答“是”接受）；如果该技能不存在，则正常提问。只询问缺失的信息。
| 问题 | 无回答时的默认值 |
|---|---|
| 一句话描述 + 氛围是什么？ | – |
| 将用于何处（游戏类型、UI、印刷品）？相机：侧面 / 四分之三俯视 / 等距 / 正面 | 侧面视角 |
风格（参见 references/styles.md） | hd-pixel |
| 尺寸级别（见下表） | L |
| 动画？哪些循环 | 无 |
| 调色板：指定 / 从 Lospec 选择 / 从参考图派生 | 使用 color 技能（/color）派生（如果存在），否则使用 Lospec |
2. 尺寸级别（超越“图标大小”；保持像素艺术风格）
| 级别 | 画布 | 典型用途 | 颜色数 |
|---|---|---|---|
| S | 32×32 | 物品、图标 | 8–16 |
| M | 64×64 | 小型角色、道具 | 16–24 |
| L | 128×128 | 主要角色、细节道具 | 24–40 |
| XL | 192×192 / 256×256 | 英雄肖像、Boss | 32–64 |
| 场景 | 320×180 或 480×270 | 场景、关键艺术 | 32–64 |
规则：像素是正方形，永远不要以非整数值缩放。细节来自更多像素，而非模糊。如果用户要求“更多细节”，在添加噪点之前先提升一个级别。
3. 调色板优先
- 选择/派生调色板（
references/palette-workflow.md；Lospec 的十六进制码：https://lospec.com/palette-list/<slug>.hex）。 - 使用
create_canvas创建索引颜色模式，然后使用set_palette。在每个色阶内将调色板从暗到亮排序（必要时使用sort_palette按色相然后亮度排序）。 - 构建色阶，而非孤立的颜色：每种材质 3–5 级（阴影、中间色、亮部、高光），并带有色相偏移（阴影 → 更冷/饱和，亮部 → 更暖）。使用
analyze_palette_harmonies检查。 - 在每次绘图调用中传递
use_palette: true，以便每个像素都适配到调色板。
3b. 朝向和姿势（在绘制前锁定；参见 references/orientation-and-pose.md）
声明 view（侧面 / 四分之三 / 正面 / 等距）、facing（侧面视图面朝右侧绘制）、光照方向、哪只手拿哪个道具以及披风/头发的垂落方向。规则：靠近摄像头的肢体位于躯干前，对侧肢体位于躯干后，头部朝向视线方向，披风固定在背部并在最底层，每只手一个道具，位于身体前方。对于任何有动画的对象，先构建骨骼：关节 + 两骨 IK，然后是形状（rig.py 参见 https://github.com/LimaEdu-7x/omni-sprite/tree/main/examples/knight）。在首次渲染后进行剪影/镜像/重叠测试。
4. 构建顺序（图层，始终按此顺序）
使用 add_layer 从底向上创建图层：bg、shadow-cast、base、shade、light、detail、outline、fx。
- 剪影 – 在
base图层用一种深色平铺填充整个形状。以 1 倍大小查看：如果无法识别为剪影，则重做。强调不对称性，头部/躯干/四肢清晰分离，负空间清晰可辨。 - 平铺颜色 – 使用
fill_area/draw_rectangle/draw_circle/draw_contour为每种材质填充中间色调。 - 形状阴影 – 选择一个光照方向（默认：左上）。在
shade/light图层使用apply_shading（锐利风格用 hard，HD 用 smooth）；在远离主光源的一侧添加选择性轮廓光。 - 纹理和细节 – 仅在风格允许的地方使用
draw_with_dither（参见风格）；手动使用draw_pixels绘制眼睛、接缝、扣环、光泽。像素分组；避免孤立像素（噪点）和“锯齿”（线条上的不规则阶梯）。 - 轮廓 – 使用
apply_outline，然后手动调整：HD 使用选择性轮廓（带有色相偏移的深色，非纯黑）；8/16 位使用完整深色轮廓；无轮廓则跳过。 - 抗锯齿 – 在曲线/对角线上使用
suggest_antialiasing（1-bit/NES 风格跳过）。 - 特效 – 在
fx/shadow-cast图层绘制高光、火花、地面阴影。
对于复杂的有机形状，使用网格方法：将精灵写成 ASCII 网格（一个字符 = 一个调色板索引），使用 scripts/grid_to_pixels.py 将其转换为批量 draw_pixels 调用（参见 references/grid-method.md）。大面积使用形状工具，细节使用网格。
5. 渲染和审查循环（必须执行）
在每个重要步骤之后：export_sprite PNG → 使用 scale_sprite 复制并放大 4 倍（近邻采样）或放大 PNG → 查看图像（读取 PNG）。根据 references/quality-checklist.md 中的检查表检查。修复最严重的缺陷并重新渲染。每个步骤最多 3 个循环；然后报告剩余的缺陷。
6. 动画（如果要求）
遵循 references/animation.md：先关键帧，然后中间帧，8–12 fps（set_frame_duration 80–125 ms），每个循环一个标签（create_tag：idle、walk、run、attack、hurt、death），duplicate_frame + 编辑，link_cel 用于静态部分，枢轴/脚部锁定在同一像素行。使用 export_sprite（预览 GIF）和 export_spritesheet（+JSON）导出。
7. 交付
保存 .aseprite 文件（save_as），导出 1 倍 PNG、4 倍预览 PNG，对于动画，导出 GIF + 精灵表 + JSON。告知：画布大小、调色板名称/颜色数、光照方向、风格和文件路径。
陷阱（在 pixel-mcp 0.5.0 中已验证）
create_canvas返回 JSON{"file_path": ...}；该路径是所有其他工具的sprite_path。没有名称参数；使用save_as命名。- 在
output_path中使用正斜杠（C:/Users/you/output.png）。反斜杠会破坏生成的 Lua 代码（\U被解析为转义）并导致“无效字符 'U'”错误。 scale_sprite就地修改精灵：先save_as一个副本，缩放该副本，然后导出。- 帧编号从 1 开始（带 frame 0 的
export_sprite表示所有帧）。 draw_pixels接收[{x,y,color}]，每次调用最多约 10,000 个像素；这是grid_to_pixels.py生成的内容。- 通过 stdio 与服务器通信：每行 JSON-RPC，使用
\n写入字节（CRLF 会导致“无效尾随数据”错误）。 - 一个完整示例（骨骼 → 着色部分 → 图层 → 导出）位于 https://github.com/LimaEdu-7x/omni-sprite/tree/main/examples/knight。
额外参考（按需加载）
references/build-aseprite.md– 从源代码编译 Aseprite 并解决故障。references/orientation-and-pose.md– 视图/视线方向、远近图层、骨骼绑定、朝向集。references/styles.md– 12 种风格及其精确规则。references/palette-workflow.md– 色阶、色相偏移、Lospec 调色板、颜色预算。references/animation.md– 循环、帧、时间、缓动。references/quality-checklist.md– 通过/未通过检查列表。references/resources.md– 12+ 个网站和 20+ 个社区技能/服务器，用于学习和集成。references/mcp-tools.md– 工具目录。- 可选伴生技能：
color//color（调色板选择和镜像），以及一个前端设计技能（如果精灵用于 Web UI）。
诚实的局限性
通过工具调用逐像素绘制很慢，并且模型在不导出的情况下无法“看到”画布。优先使用形状 + 网格方法 + 审查循环；当用户提供参考图像时，使用 analyze_reference / downsample_image。