スプライトシートスライサー は何をしますか?
スクリプトがピクセルを所有し、あなたが意味を所有します。
scripts/sheet.jsはすべてのオブジェクトを見つけ、どのピクセルがどのオブジェクトに属するかを正確に把握し、番号付きのレビューページを描画します。- あなたはそのページを見て、何を1つのアセットと見なすかを決定し、オブジェクトをidで、プレースをページに印刷されたルーラーで指定する短い編集操作で指示します。
- スプライトのエッジの位置を推測する必要はありません。画像から読み取った位置は近似値であるため、スクリプトが受け入れる唯一の自由位置(
cutのpx)は、3ピクセル以内で最も強いシームに移動されます。
ここで使用する用語:オブジェクト はスクリプトが見つけて番号を付けた1つの領域です。アセット はゲームが必要とするもの: 1つのプロップ、1つのアイコン、1つのタイルです。仕事は、すべてのオブジェクトを正確に1つのアセットにすることです。セル はシートのタイルグリッドの1つの正方形です。
NodeがPATHに必要です(node --version)。インストールは不要です。入力はPNGでなければなりません。
コマンドは node "${CLAUDE_SKILL_DIR}/scripts/sheet.js" <command> ... として実行され、パスは引用符で囲みます。--help ですべてのコマンドとオプションが一覧表示されます。Claude Codeはこれらのコマンド内のスキルフォルダを自動的に補完します。${CLAUDE_ で始まるプレースホルダーが実際のパスの代わりに表示される場合(Codexや他のエージェント)、このSKILL.mdが置かれているフォルダをその場所に指定してください。シートごとにワークフォルダ(WORK)と新しく空の出力フォルダ(OUT)を選択し、どちらもスキルフォルダの外に配置してください。opsファイルとnamesファイルは、ファイル書き込みツール(Claude CodeのWrite、Codexのapply_patch)で作成してください。これらはUTF-8で保存されます。PowerShellのリダイレクトによるUTF-16ファイルは拒否されます。
コピーしてチェックするための進行状況リスト:
[ ] ライセンス確認 [ ] タイルサイズ特定
[ ] detect: 警告を確認
[ ] review: ページを確認、シートの種類を決定
[ ] apply (ラウンド1) [ ] 再度review
[ ] names (必要な場合) [ ] export: カバレッジ完了
[ ] report
開始前
- ライセンスを確認してください。 ユーザーがストアページやREADMEを提供した場合、そのライセンステキストを読んでください。AIの使用を制限している場合(「no AI」「not for AI training」「may not be fed to AI」など)、停止してユーザーにどう進めるか尋ねてください。
- ユーザーが続行するように指示した場合、通常のワークフローを続行し、レポートでその判断をユーザーが行ったことを記載してください。
- ユーザーがアートワークをAIから遠ざけたい場合:
detectとreviewを実行し、WORK/pagesの場所をユーザーに伝え、ユーザーが自分で確認してopsファイルを記述できるようにしてください。ページ、native.png、またはスプライトを開かないでください。apply、review、status、exportはユーザーに代わって実行し、それらの出力テキストを読み取ることは許可されています。
- タイルサイズを見つけてください。 パックの説明には通常、タイルサイズが記載されています(「16x16 tiles」「32x32 style aligned to a 16 grid」)。
--tile Nとして渡してください。これは、アウトラインのないアートの場合に最も重要です。アウトラインのない合成テストシートとフラットシェーディングのプロップでは、スクリプトはタイルサイズを使用するとアセットの約90%を正しくカットしましたが、タイルサイズなしでは40%未満でした。説明にグリッドがないと記載されている場合は、--tile noneを渡してください。何も記載がない場合は、--tileを省略してください。スクリプトはサイズを推測しようとし、その旨を表示します。 - 1シートにつき1つのワークフォルダ。 ワークフォルダで
detectを再実行すると、そのシートの処理は最初からやり直しになります。
ワークフロー
1. Detect
node "${CLAUDE_SKILL_DIR}/scripts/sheet.js" detect "<sheet.png>" --work "WORK" --tile 16
検出された背景、アートスタイル(アウトラインあり/フラット、参考情報)、タイルサイズ、オブジェクト数、および WARNING と note 行が出力されます。これらに応じて行動してください:
| 出力 | 行うこと |
|---|---|
kind: scene_or_single_object | オブジェクトが非常に少なく、1つがほとんどのアートワークを占めています。画像を読んでください。モックアップシーン(オブジェクトが重なり合い、床に立っている)の場合は、クリーンなアセットにカットできないことをユーザーに伝えて停止してください。1つまたは数個の大きなスプライトの場合は、続行してください。 |
background: none | 不透明な画像で背景が認識されませんでした。画像を読み、背景色を見つけ、--bg rrggbb を付けて再実行してください(ベイクされたチェッカーボードの色はカンマ区切り)。 |
| 「background colour also occurs inside the artwork」 | スプライトのエッジが損傷している可能性があります。透明なソースの方が安全であることをユーザーに伝えてください。続行してください。 |
| 「enclosed region(s) of background colour were removed」 | パックされたシートでは正常です。スプライトに穴があるようにページに表示される場合は、--pockets large または --pockets keep を付けて再実行してください。 |
| 「read as a xN enlargement」 | 画像が拡大されたプレビューであり、縮小されました。--tile とすべての位置はネイティブピクセル単位です。画像が拡大でない場合は、--scale 1 を付けて再実行してください。 |
tile: 16px (inferred) | オブジェクトの整列から推測された値です。パックにグリッドがない場合は --tile none を付けて再実行し、サイズが指定されている場合はそのサイズを渡してください。 |
tile: none | 格子なし。cells および tiles 操作は使用できず、cut は px を使用します。 |
| 「speck(s) ... were merged into the object next to them」 | 通常は孤立ピクセルです。パックに6ピクセル未満の実際のスプライトが含まれている場合は、opsリファレンスの split を参照してください。 |
| 「nearly invisible pixel(s) ... treated as transparent」 | 何もする必要はありません。 |
2. Review
node "${CLAUDE_SKILL_DIR}/scripts/sheet.js" review --work "WORK"
これにより、WORK/pages/*.png と WORK/objects.json が書き込まれ、ヒントが表示されます。画像表示ツール(Claude CodeのRead、Codexのview_image)でページを開いてください: 8ページ以下の場合はすべて開き、それより多い場合はフラグ付きオブジェクトをリストアップしたページを最初に開き、次に残りのサンプルを開きます。ページは少し重複しているため、ページの端近くにあるオブジェクトは同じIDで2ページに表示されます。収まるシートは1ページに描画され、600オブジェクトを超えるシートの場合は、フラグ付きオブジェクトのあるページのみが生成されます(フラグがない場合はサンプルのみ)。
ページの読み方:
- アートワークは暗いチェッカーボード上に本来の色で表示されます。各オブジェクトには、ピクセルの正確なエッジに沿った色付きの輪郭と、同じ色の番号があります。番号がidです。大きなオブジェクトの内側と、小さなオブジェクトの横に配置されます。複数の部分から構成されるオブジェクトは、1つの番号と、各部分の周りに同じ色の輪郭を持ちます。
- 上部と左側の数字はルーラーです。タイルサイズのあるシートの場合はセルインデックス(セル3はピクセル3 x タイルサイズから開始)、それ以外の場合はピクセル位置です。
- 白い二重ボックスはフラグ付きオブジェクトを示します。フラグは確認を促すものであり、エラーではありません:
shares_cell: 複数のオブジェクトが1つのセル内にあります。close_same_colours: 色を共有する別のオブジェクトが2ピクセル以内にあります。doubtful_border: オブジェクトが格子の境界線(マゼンタのバー)に接しており、カットするか結合するかの判断が微妙でした。格子線を横切る細い斜めのスプライトはこれが頻繁に発生しますが、問題ありません。exposed_fill: オブジェクトの塗りつぶしが、間のアウトラインなしで別のオブジェクトに直接隣接しています: 誤ったカット、または2つのアセット間にアウトラインがない状態です。large_blob: 他のオブジェクトよりもはるかに大きいです。多くの場合、複数のアセットが融合しています。speck: 6ピクセル未満です。
- シアンのダッシュは、格子のないシートでスクリプトがカットしたシームを示します。
- 輪郭のない薄暗いアートワークはドロップされています。
review によって表示されるヒントは、画像だけではわからないことを教えてくれます: どのオブジェクトがセルを共有しているか、隣接するオブジェクトの距離、最も近いギャップにあるペア、およびそれらのペアのうち色を共有しているもの。色共有ペアは 12+13@1px=28x28 のように書かれます: ID、ギャップ、および2つを合わせたサイズ。これらは、1つのアセットが複数のバラバラのピースとして描かれている場合の最も一般的な見逃しの主な手がかりとなります(ただし、パートナーと色が異なるピースはリストされません)。
ページだけでは不十分な場合:
review --ids 12,13は、これらのオブジェクト周辺の領域(隣接オブジェクトを含む)の拡大ページ1枚(pages/focus_*.png)を書き込み、それ以外はそのままにします。近くにあるIDを一度に1ペアずつ指定してください。遠く離れたIDを指定すると、通常のページと同じ大きさのページになります。--zoomと組み合わせて使用できます。小さなスプライトや、判断に迷うペアに使用してください。review --zoom 8はシート全体を大きく再レンダリングします。通常のreviewはデフォルトに戻ります。WORK/native.pngはネイティブサイズのクリーンなシートです。status --listはオブジェクトごとに1行(ID、セル、ボックス、面積、フラグ)を出力します。
IDは status --list または objects.json から取得し、画像だけから判断しないでください: オブジェクトの cells または bbox が、あなたが見た場所と一致していることを確認してください。存在するが意図したものではないIDを指定すると、間違ったオブジェクトが変更されてしまいます。
3. 決定と編集
すべてのアセットがすでに1つのオブジェクトになっている場合は、このステップをスキップしてください。opsファイルは不要で、現在のリビジョンで名前を付けてエクスポートできます。このステップの最後にある停止チェックは引き続き適用されます。
それ以外の場合は、これがどの種類のシートかを決定します。これによってレシピが決まります。references/sheet-kinds.md に各種類とその一般的な問題が記載されています。
| 種類 | 一般的な操作 |
|---|---|
| ギャップのある個別のプロップ | バラバラのピースとして描かれたプロップには merge、cells、near を使用。何もすることがないと判断する前にヒントを確認してください。 |
| エッジツーエッジでパックされたプロップ | 2つのプロップがまだ融合している場合は cut、1つのプロップが分割されている場合は merge。 |
| アイコングリッド、セルあたり1アイコン | 一度 cells を実行し、次にラベルボックスを drop。 |
| 地形または壁のタイルセット | まだ融合しているブロックには tiles。格子線をまたいで描かれた壁: そのままにします。 |
| 格子なし | シアンのシームを確認: 誤ったシームは merge、2つのオブジェクトがまだ融合している場合は cut を px で実行。 |
| 混合 | 各領域を独自のレシピで処理。cells と near は region を受け付けます。 |
opsファイルを記述して適用します:
{ "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 | 複数のピースが1つのアセットである場合。 |
cells | 1つのセル内のすべてが1つのアセットである場合(アイコングリッド、セル内のバラバラのピース)。 |
near px | 多くのアセットが、個別のアセット同士の距離よりも近くにバラバラのピースとして描かれている場合。 |
cut id, axis, cell / cells / px | 2つ以上のアセットが融合している場合。cells: [2, 4, 6] は一度にストリップをカットします。 |
tiles ids, optional span | 融合されたブロックを、セルごと、またはセルの span ごとに1つのオブジェクトにする必要がある場合。 |
split id | マージを元に戻す: オブジェクトの連結されたピースに戻します。 |
drop ids, reason | アセットではないもの: ラベルテキスト、透かし、カラースウォッチ。 |
restore ids | ドロップを元に戻す。 |
ok ids | フラグ付きオブジェクトを確認し、正しいと判断した場合。オプション。 |
一括操作(cells、near、tiles)を長いIDリストよりも優先してください: IDが少なくなり、読み間違いも減ります。
1つのファイル内のID: 操作は順番に実行され、それぞれ前の操作の結果を参照します。merge、cells、near は各グループの最小のIDを保持し、他のIDはそのままにしておくため、同じファイル内の後続の操作でもそれらを使用できます。cut、tiles、split は操作対象のIDを廃棄し、apply出力からのみ判明する新しいIDを作成するため、それらの新しいIDを必要とするものは次のラウンドに回します。
applyのたびに、再度 review を実行し、新しいopsやnamesを書く前に新しいページを読んでください。
1ピースか2ピースか? 近くにある2つのピースは、1つのアセットである場合と2つのアセットである場合があります。以下のリストを順に確認してください:
- それらが、セルあたり1アセットで構築されたシート(アイコングリッド)の1つのセル内にある場合: 1つのアセット。
- 異なる色で描かれている、または明らかに異なるものである場合: 2つのアセット。
- 色を共有しており、2つを合わせたサイズと配置がシートの他のアセットと一致し、各ピース単独では一致しない場合: 1つのアセット。これは、各ピースがそれぞれ独自の完全なアウトラインを持っている場合でも当てはまります。ヒントは合わせたサイズ(
=28x28)を示します。status --listの単一オブジェクトのサイズと比較してください。2つのピースにまたがって整列するシェーディングバンドやハイライト、または両方の下にある1つの影も、同じ方向を示します。 - 色を共有しているが、各ピース単独ですでにシートの他のアセットと同じサイズと配置を持っている場合(2本のボトルが並んでいて、それぞれが他のすべてのボトルと同じ大きさ): 2つのアセット。
- まだ判断できない場合: それらを分離したままにして、レポートにリストしてください。開発者は2つのスプライトを結合できます。融合したものを引き離すのはより困難です。
ギャップのヒントは、バラバラのピースが個別のアセット同士よりも近くにある場合にのみ役立ちます。両方が2ピクセル離れている場合、ヒントはそれらを区別できず、ルール3で判断します。
ページにアセットごとに1つのオブジェクトが表示されたら停止してください。通常は3ラウンドで十分です。カットにより、さらなるカットやドロップが必要なピースが残る場合があり、その場合はもう1ラウンドかかります。3ラウンド後もまだ問題がある場合は、とにかくエクスポートして報告してください。
停止する前に、以下を確認してください:
- 1つのオブジェクトに2つの異なるアセットが含まれていないこと(
cut、tiles)。large_blobオブジェクトと、隣接オブジェクトよりもはるかに幅広または高さのあるオブジェクトを特に注意深く確認してください。 - アセットが複数のオブジェクトに分散していないこと(
merge、cells、near)。 - アセット以外のオブジェクトがないこと(
drop)。 - 各フラグ付きオブジェクトが一度確認されていること。あなたが正しいと判断したオブジェクトに残っているフラグは問題ありません。
4. 名前付け(オプション)
ユーザーが名前を必要としない場合は、このステップをスキップしてください。--names なしでエクスポートすると、すべてのアセットは生成された名前(obj_0042、tile_0107)を保持します。
それ以外の場合は、現在のリビジョンの WORK/names.json を記述してください。認識できるものに名前を付け、残りは省略してください。
{ "rev": 1,
"sheet": { "kind": "アイコングリッド", "notes": "6つのラベルボックスの下にある16pxのアイテムアイコン" },
"assets": {
"12": { "name": "weapon_sword_iron", "category": "weapons", "tags": ["melee"], "confidence": "high" },
"40": { "name": "food_loaf", "category": "food", "confidence": "low", "description": "茶色の楕円形、パンかジャガイモの可能性" }
} }
- キーはプレーンな数字としてのオブジェクトIDです。名前は小文字、数字、アンダースコアで構成され、最大64文字、一意である必要があります。良いパターンは
category_thing_variant(bench_wood_stocked、locker_red_open)です。 sheet.kind、sheet.notes、category、tags、descriptionは、カタログを読む人向けの自由テキストです。- シートに印刷されたラベルテキストがある場合は、それをカテゴリとして使用してください。
- 色は、輪郭やその他のマークアップではなく、輪郭の内側のアートワークから判断してください。
5. エクスポート
node "${CLAUDE_SKILL_DIR}/scripts/sheet.js" export --work "WORK" --out "OUT" [--names "WORK/names.json"]
OUT に各アセットのPNGと catalogue.json が書き込まれます。coverage/ フォルダには、元のシート上で各ピクセルがどのアセットに属するかを色分けした画像カバレッジマップが含まれます。カバレッジが完了していない場合(黒いピクセルがある場合)、エクスポートは成功しますが、レポートでその旨を伝えてください。
カタログは、エクスポートを実行したエージェントが読むためのものです。誰かがデータを必要としている場合は、カタログファイルへのパスを伝えてください。
6. レポート
ユーザーに書いてください。何をしたか、なぜそうしたか、何が未解決かを含めてください。apply と review の出力はレポートの一部であり、そのまま印刷しても問題ありません。
エッジケース
tileは、それが理にかなっている場合にのみ想定されるサイズを設定します。画像が63x63ピクセルで--tile 16を渡すと、スクリプトはそれを64に拡張せず、代わりにtile_latticeは3列3行になります。- 外部ツールは、
detectの前にWORK/pagesまたはWORK/native.pngを編集または作成しないでください。reviewはそれらを上書きします。 - 画像ファイル名にアポストロフィが含まれている場合は、引用符で囲み、二重引用符を使用してください。
リファレンス
- ops.md: 編集操作の完全なリファレンス。
- sheet-kinds.md: シートの種類と各レシピ。
- catalogue.json: エクスポートされたカタログの構造。