精灵表切片器 是做什么的?
这一行脚本掌管像素,而您掌管含义。
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:覆盖完整
[ ] 报告
开始之前
- 检查许可证。 如果用户提供了商店页面或自述文件,请阅读其许可文本。如果它限制 AI 使用(“禁止 AI”、“禁止用于 AI 训练”、“不得供 AI 训练”),请停止并向用户询问如何处理。
- 如果他们告诉您继续,请正常进行工作流程,并在报告中说明是他们做出的这个决定。
- 如果他们希望美术作品远离 AI:运行
detect和review,告诉他们WORK/pages的位置,让他们自己查看并编写操作文件。不要打开页面、native.png或任何精灵。您仍然可以为他们运行apply、review、status和export,并阅读这些命令输出的文本。
- 找到瓦片大小。 包描述通常会说明(“16x16 瓦片”、“32x32 风格对齐到 16 网格”)。将其作为
--tile N传递。这对于没有轮廓的美术作品最为重要:在没有轮廓的合成测试表和扁平阴影道具上,提供瓦片大小时脚本正确切割了约90%的资产,而没有时不足40%。如果描述说没有网格,请传递--tile none。如果描述什么也没说,省略--tile;脚本随后会尝试推断一个大小并说明。 - 一个工作表对应一个工作文件夹。 在工作文件夹上重新运行
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 并在编写更多操作或名称之前阅读新页面。
一个还是两个? 两个相邻碎片可能是一个资产或两个。按此列表逐一排查:
- 它们位于一个单元格内,而工作表构建为一个单元格一个资产(图标网格):一个资产。
- 它们使用不同颜色绘制,或者明显是不同事物:两个资产。
- 共享颜色,并且两个合起来具有工作表其他资产的大小和位置,而单个碎片没有:一个资产。即使每个碎片有自己完整的轮廓也适用。提示给出了合起来的大小(
=28x28);将其与status --list中单个对象的大小进行比较。跨越两个碎片的阴影带或高光,或者两者下方的一个阴影,都指向相同结论。 - 共享颜色,但每个碎片单独已经具有工作表其他资产的大小和位置(两个瓶子并排放置,每个和其他瓶子一样大):两个资产。
- 仍然不确定:将它们分开并在报告中列出。开发者可以合并两个精灵;将融合的精灵分开则更难。
间隙提示仅在松散碎片比独立资产更靠近时才有帮助。当两者都是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是自由文本,供阅读目录的人使用。- 如果工作表上有打印的标签文本,将其作为类别。
- 根据轮廓内的美术作品判断颜色,绝不要根据轮廓或(...截断...)