精靈圖表切片器 是做什麼的?
腳本擁有像素,你擁有意義。
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 檔案將被拒絕。
要複製和勾選的進度列表:
[ ] 許可證已檢查 [ ] 圖塊大小已找到
[ ] 偵測:警告已閱讀
[ ] 審查:頁面已閱讀,圖表類型已決定
[ ] 應用(第 1 輪) [ ] 再次審查
[ ] 名稱(如果需要) [ ] 匯出:覆蓋率完整
[ ] 報告
開始之前
- 檢查許可證。 如果使用者提供了商店頁面或 readme,請閱讀其許可證文字。如果它限制了 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, optional 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,因此任何需要這些新 id 的操作都必須在下一輪中進行。
每次應用後,再次執行 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": "武器", "tags": ["近戰"], "confidence": "high" },
"40": { "name": "food_loaf", "category": "食物", "confidence": "low", "description": "棕色橢圓形,可能是麵包或馬鈴薯" }
} }
- 鍵是作為純數字的物件 id。名稱是 lowercase letters, digits and underscores,最多 64 個字元,且必須唯一。一個好的模式是
category_thing_variant(bench_wood_stocked、locker_red_open)。 sheet.kind、sheet.notes、category、tags和description是供閱讀目錄的人使用的自由文字。- 當圖表上印有標籤文字時,將其用作類別。
- 從輪廓內的藝術品判斷顏色,永遠不要從輪廓或輪廓本身判斷。
- 如果你不確定一個資源的名稱或類別,請使用
"confidence": "low"並新增一個description。