Community图像github.com

精灵表切片器

将游戏精灵表、瓦片集或图标集(PNG)切成每个资产一张图片,并编写一个目录,为每个资产命名并记录其瓦片大小和来源。

精灵表切片器 是什么?

精灵表切片器是一个专业的AI代理技能,用于将游戏艺术精灵表、瓦片集或图标集(PNG格式)精确分割成每个资产一张图片。它专为处理单个图像中包含多个不规则、边缘到边缘排列的游戏资产而设计,这些资产需要在游戏使用前被分离、命名或编目。该技能支持分析图像、识别每个像素属于哪个对象、生成带编号的审查页面,并通过简短的编辑操作让用户定义每个资产。它特别擅长处理没有轮廓的扁平风格精灵,在有瓦片大小信息时能正确切割约90%的资产。该技能支持Claude Code、Codex和其他AI代理平台,需要Node环境,输入必须为PNG格式。

兼容平台✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/GabrielKimm/sprite-sheet-slicer/tree/HEAD/skills/sprite-sheet-slicer

Installed? Explore more 图像 skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

精灵表切片器 是做什么的?

这一行脚本掌管像素,而您掌管含义。

  • scripts/sheet.js 找出每个对象,精确知道每个像素属于哪个,并绘制带编号的审查页面。
  • 您查看页面,决定什么算作一个资产,并通过简短的编辑操作进行说明,操作使用打印在页面上的 id 来命名对象,使用 标尺 来指定位置。
  • 您永远不用猜测精灵的边缘在哪。从图片上读取的位置是近似的,因此脚本接受的唯一自由位置(带 px 的 cut)会被移动到3像素内最强的接缝处。

此处使用的术语:对象是脚本找到并编号的一个区域。资产是游戏需要的:一个道具、一个图标、一个瓦片。任务就是让每个对象恰好对应一个资产。单元格是瓦片网格的一个方格。

要求 Node 在 PATH 上(node --version)。无需安装任何东西。输入必须是 PNG。

命令以 node "${CLAUDE_SKILL_DIR}/scripts/sheet.js" <command> ... 形式运行,路径用引号括起来;--help 列出所有命令和选项。Claude Code 会在这些命令中填充技能文件夹。如果您看到的是以 ${CLAUDE_ 开头的占位符而不是实际路径(Codex 和其他代理),请将包含此 SKILL.md 的文件夹放在该位置。为每个工作表选择一个工作文件夹(WORK)和一个新的空输出文件夹(OUT),两者都应在技能文件夹之外。使用您的文件写入工具(Claude Code 中的 Write,Codex 中的 apply_patch)编写操作和名称文件,这些工具保存 UTF-8;拒绝使用 PowerShell 重定向生成的 UTF-16 文件。

要复制和勾选的进度列表:

[ ] 许可证已检查     [ ] 瓦片大小已找到
[ ] detect:警告已阅读
[ ] review:页面已阅读,工作表类型已确定
[ ] apply(第1轮)     [ ] 再次 review
[ ] names(如果需要)   [ ] export:覆盖完整
[ ] 报告

开始之前

  1. 检查许可证。 如果用户提供了商店页面或自述文件,请阅读其许可文本。如果它限制 AI 使用(“禁止 AI”、“禁止用于 AI 训练”、“不得供 AI 训练”),请停止并向用户询问如何处理。
    • 如果他们告诉您继续,请正常进行工作流程,并在报告中说明是他们做出的这个决定。
    • 如果他们希望美术作品远离 AI:运行 detect 和 review,告诉他们 WORK/pages 的位置,让他们自己查看并编写操作文件。不要打开页面、native.png 或任何精灵。您仍然可以为他们运行 apply、review、status 和 export,并阅读这些命令输出的文本。
  2. 找到瓦片大小。 包描述通常会说明(“16x16 瓦片”、“32x32 风格对齐到 16 网格”)。将其作为 --tile N 传递。这对于没有轮廓的美术作品最为重要:在没有轮廓的合成测试表和扁平阴影道具上,提供瓦片大小时脚本正确切割了约90%的资产,而没有时不足40%。如果描述说没有网格,请传递 --tile none。如果描述什么也没说,省略 --tile;脚本随后会尝试推断一个大小并说明。
  3. 一个工作表对应一个工作文件夹。 在工作文件夹上重新运行 detect 会重头开始处理该工作表。

工作流程

1. 检测

node "${CLAUDE_SKILL_DIR}/scripts/sheet.js" detect "<sheet.png>" --work "WORK" --tile 16

它会打印找到的背景、艺术风格(有轮廓或扁平;仅供参考)、瓦片大小、对象数量以及 WARNING 和 note 行。根据这些内容进行操作:

它打印的内容您需要做的
kind: scene_or_single_object对象非常少,其中一个占用了大部分美术区域。阅读图像。如果它是场景示意图(对象重叠、站在地面上),告知用户无法将其切割为干净的资产并停止。如果它是一个或几个大精灵,请继续。
background: none一个不透明图像,其背景未被识别。阅读图像,找到背景颜色,使用 --bg rrggbb 重新运行(如果是烘焙棋盘格,用逗号分隔颜色)。
"背景颜色也出现在美术作品内部"精灵边缘可能已损坏。告知用户使用透明源会更安全;继续。
"已移除背景颜色的封闭区域"在打包的表中是正常的。如果页面上精灵出现空洞,使用 --pockets large 或 --pockets keep 重新运行。
"读取为 xN 放大图像"图像是放大的预览版本,已被缩小。--tile 和所有位置都是原生像素单位。如果图像不是放大版本,使用 --scale 1 重新运行。
tile: 16px (inferred)根据对象对齐方式进行的猜测。如果包没有网格,使用 --tile none 重新运行;如果包指定了大小,请传递它。
tile: none没有网格。cells 和 tiles 操作不可用,cut 使用 px。
"斑点...已合并到它们相邻的对象中"通常是散乱的像素。如果包有小于六个像素的实际精灵,请参阅操作参考中的 split。
"几乎不可见的像素...已被视为透明"无需处理。

2. 审查

node "${CLAUDE_SKILL_DIR}/scripts/sheet.js" review --work "WORK"

此命令会写入 WORK/pages/*.png 和 WORK/objects.json,并打印提示。使用您的图像查看工具(Claude Code 中的 Read,Codex 中的 view_image)打开页面:如果页面不超过八个则全部打开;否则先打开列出标记对象的页面,然后查看其余页面的样本。页面之间略有重叠,因此靠近页面边缘的对象会以相同 id 出现在两个页面上。适合一个页面的工作表会绘制在一页上;超过600个对象的工作表仅获得包含标记对象的页面(如果没有标记对象则获得样本)。

阅读页面:

  • 美术作品以其真实颜色显示在深色棋盘格上。每个对象都有一个沿其像素边缘的彩色轮廓和一个相同颜色的编号。编号就是 id。它位于大对象内部和小对象旁边。由独立碎片组成的对象有一个编号和相同颜色的轮廓包围每个碎片。
  • 顶部和左侧的数字是标尺:对于有瓦片大小的工作表来说是单元格索引(单元格3从像素 3 x 瓦片大小 开始),否则是像素位置。
  • 白色双框标记一个标记对象。标记是提示检查,而非错误:
    • shares_cell:多个对象位于一个单元格内。
    • close_same_colours:另一个与其共享颜色的对象距离2像素或更少。
    • doubtful_border:对象触及网格边界(洋红色条),在此处切割或合并的选择很接近。细长的对角精灵跨越网格线时常出现此情况,且通常没问题。
    • exposed_fill:对象的填充直接紧贴另一个对象,之间没有轮廓:错误的切割,或者两个资产之间没有轮廓。
    • large_blob:远大于其他对象。通常是几个资产融合在一起。
    • speck:小于六个像素。
  • 青色虚线标记了脚本在没有网格的工作表上的切割接缝。
  • 没有轮廓的暗淡美术作品表示已被丢弃。

review 打印的提示告诉您图片无法显示的信息:哪些对象共享一个单元格,相邻对象相距多远,哪些对位于最近的间隙,以及哪些邻近对共享颜色。共享颜色的对写作 12+13@1px=28x28:id,间隙,以及两者的大小。这是最常见遗漏问题的主要线索——一个资产被绘制为几个分离的碎片,尽管其颜色与伙伴不同的碎片不会被列出。

当页面不够用时:

  • review --ids 12,13 会写入一张放大的页面,显示这些对象周围的区域(pages/focus_*.png),包含相邻对象,其他内容保持不变。一次给出一对靠得很近的 id;相隔很远的 id 不会生成比正常页面更大的页面。--zoom 可与此选项一起使用。适用于小精灵和任何您不确定的对。
  • review --zoom 8 会以更大尺寸重新渲染整个工作表。普通的 review 会恢复到默认值。
  • WORK/native.png 是原始大小的干净工作表。
  • status --list 每行打印一个对象的信息:id、单元格、边界框、面积、标记。

从 status --list 或 objects.json 中获取 id,而不仅仅是从图片中获取:检查对象的 cells 或 bbox 是否在您看到的位置。一个存在但不是您本意的 id 会被接受并修改错误的对象。

3. 决定和编辑

如果每个资产已经恰好有一个对象,跳过此步骤。不需要操作文件,您可以在当前修订版命名和导出。此步骤结束时的停止检查仍然适用。

否则,决定此工作表属于哪种类型,因为这会决定策略。references/sheet-kinds.md 描述了每种类型及其常见问题。

类型常用操作
带间隙的独立道具merge,cells 或 near 用于绘制为分离碎片的道具。在决定无事可做之前先检查提示。
边缘到边缘打包的道具如果两个道具仍然融合则 cut,如果一个道具被分割则 merge。
图标网格,每格一个图标使用一次 cells,然后 drop 任何标签框。
地形或墙壁瓦片集对仍然融合的块使用 tiles。跨越网格线绘制的墙壁:保持整体。
无网格检查青色接缝:错误的接缝使用 merge,两个对象仍然融合时使用带 px 的 cut。
混合类型每个区域按各自策略处理;cells 和 near 接受 region。

编写操作文件并应用它:

{ "rev": 0, "ops": [
  { "op": "cells" },
  { "op": "drop", "ids": [7, 31], "reason": "类别标签框" }
] }
node "${CLAUDE_SKILL_DIR}/scripts/sheet.js" apply --work "WORK" --ops "WORK/ops_r1.json"

rev 是 review 打印的修订号(也在 objects.json 中)。文件是全部或全无的:如果任何操作被拒绝,什么都不会改变;阅读消息,修复文件,再次应用。完整参考及示例:references/ops.md。

操作使用时机
merge ids几个碎片属于一个资产。
cells一个单元格内的所有内容是一个资产(图标网格,单元格内的松散碎片)。
near px许多资产被绘制为比独立资产更靠近的松散碎片。
cut id, axis, cell / cells / px两个或更多资产融合在一起。cells: [2, 4, 6] 一次切割一条带状区域。
tiles ids, 可选 span一个融合的块应变成每个单元格一个对象,或每个 span 的单元格一个对象。
split id撤销合并:回到对象的连接碎片。
drop ids, reason不是资产:标签文本、水印、颜色样本。
restore ids撤销丢弃。
ok ids您检查了一个标记对象,它是对的。可选。

优先使用批量操作(cells,near,tiles)而不是长 id 列表:更少的 id,更少的误读。

一个文件内的 id:操作按顺序执行,每个操作看到之前操作的结果。merge,cells 和 near 保留每个组中最小的 id,其他 id 保持不变,因此同一文件中的后续操作仍然可以使用它们。cut,tiles 和 split 会回收它们操作的 id 并创建新的 id,这些新 id 只能从 apply 输出中获知,因此任何需要这些新 id 的操作必须放在下一轮。

每次 apply 之后,再次运行 review 并在编写更多操作或名称之前阅读新页面。

一个还是两个? 两个相邻碎片可能是一个资产或两个。按此列表逐一排查:

  1. 它们位于一个单元格内,而工作表构建为一个单元格一个资产(图标网格):一个资产。
  2. 它们使用不同颜色绘制,或者明显是不同事物:两个资产。
  3. 共享颜色,并且两个合起来具有工作表其他资产的大小和位置,而单个碎片没有:一个资产。即使每个碎片有自己完整的轮廓也适用。提示给出了合起来的大小(=28x28);将其与 status --list 中单个对象的大小进行比较。跨越两个碎片的阴影带或高光,或者两者下方的一个阴影,都指向相同结论。
  4. 共享颜色,但每个碎片单独已经具有工作表其他资产的大小和位置(两个瓶子并排放置,每个和其他瓶子一样大):两个资产。
  5. 仍然不确定:将它们分开并在报告中列出。开发者可以合并两个精灵;将融合的精灵分开则更难。

间隙提示仅在松散碎片比独立资产更靠近时才有帮助。当两者都是2像素间距时无法区分,规则3决定。

当页面显示每个资产对应一个对象时停止。通常三轮就足够了;一次切割可能会留下需要进一步切割或丢弃的碎片,这需要另一轮。如果三轮后仍然有问题,无论如何都进行导出并在报告中说明。

在停止之前,请检查:

  • 没有对象包含两个不同的资产(cut,tiles)。最仔细地检查 large_blob 对象以及任何比相邻对象宽或高得多的对象。
  • 没有资产分布在多个对象上(merge,cells,near)。
  • 没有对象是资产以外的其他东西(drop)。
  • 每个标记对象已被检查一次。您判断正确的对象上保留的标记没有问题。

4. 命名(可选)

如果用户不需要名称,跳过此步骤:导出时不带 --names,每个资产保留生成的名称(obj_0042,tile_0107)。

否则,为当前修订版编写 WORK/names.json。命名您能识别的内容,其余留空。

{ "rev": 1,
  "sheet": { "kind": "图标网格", "notes": "16px 物品图标,下方有六个标签框" },
  "assets": {
    "12": { "name": "weapon_sword_iron", "category": "weapons", "tags": ["melee"], "confidence": "high" },
    "40": { "name": "food_loaf", "category": "food", "confidence": "low", "description": "棕色椭圆形,可能是面包或土豆" }
  } }
  • 键是作为纯数字的对象 id。名称是小写字母、数字和下划线,最多64个字符,且唯一。一个好的模式是 类别_事物_变体 (bench_wood_stocked,locker_red_open)。
  • sheet.kind,sheet.notes,category,tags 和 description 是自由文本,供阅读目录的人使用。
  • 如果工作表上有打印的标签文本,将其作为类别。
  • 根据轮廓内的美术作品判断颜色,绝不要根据轮廓或(...截断...)

相关技能