CommunityBildgithub.com

Sprite-Sheet-Zerteiler

Zerlegt eine Game-Art-Sprite-Sheet, Tileset oder Icon-Sheet (PNG) in einzelne Bilder pro Asset und erstellt einen Katalog mit Namen, Größe und Herkunft der Assets. Ideal, wenn eine einzelne Datei viele, oft unregelmäßig und randlos gepackte Spiel-Assets enthält, die vor der Nutzung getrennt, benannt oder katalogisiert werden müssen.

Was ist Sprite-Sheet-Zerteiler?

Dieses Skill zerlegt eine einzelne PNG-Datei (Sprite-Sheet, Tileset oder Icon-Sheet) in einzelne Bilder pro Asset und erstellt einen detaillierten Katalog mit Namen, Größe und Herkunft. Es erkennt automatisch Objekte, Hintergrundfarben und Anordnungen und bietet eine schrittweise Workflow-Unterstützung: Erkennung, visuelle Überprüfung, manuelle Korrekturen (Zusammenführen, Trennen, Löschen), Benennung und Export. Der Benutzer kann mit einfachen JSON-Operationen Objekte korrigieren, die auf nummerierten Vorschaubildern basieren. Besonders nützlich für gepackte Asset-Pakete, bei denen Sprites randlos angeordnet sind oder mehrere Assets in einer Zelle liegen. Unterstützt Node.js auf dem Systempfad, benötigt keine Installation und funktioniert mit PNG-Eingabe. Es ist kompatibel mit Claude Code, Codex und anderen KI-Agenten, die die Anweisungen im SKILL.md befolgen. Der Workflow umfasst: Lizenzprüfung, Kachelgrößenbestimmung (<code>--tile</code>), Objekterkennung mit <code>detect</code>, visuelle Überprüfung mit <code>review</code>, Erstellung von Operationsdateien (<code>apply</code>), optionale Benennung (<code>names.json</code>) und abschließenden Export. Das Tool bietet detaillierte Warnungen und Hinweise zu Problembereichen wie überlappenden Objekten, falschen Schnitten und unscharfen Grenzen.

Funktioniert mit✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/GabrielKimm/sprite-sheet-slicer/tree/HEAD/skills/sprite-sheet-slicer

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

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Was macht Sprite-Sheet-Zerteiler?

Das Skript besitzt die Pixel, und du besitzt die Bedeutung.

  • scripts/sheet.js findet jedes Objekt, weiß genau, welcher Pixel zu welchem gehört, und zeichnet nummerierte Überprüfungsseiten.
  • Du siehst dir die Seiten an, entscheidest, was als ein Asset zählt, und drückst das mit kurzen Bearbeitungsoperationen aus, die Objekte nach ID und Positionen nach dem Lineal auf der Seite benennen.
  • Du schätzt nie, wo eine Sprite-Kante liegt. Eine von einem Bild abgelesene Position ist ungefähr, daher wird die einzige freie Position, die das Skript akzeptiert (cut mit px), auf die stärkste Naht innerhalb von 3 Pixeln verschoben.

Hier verwendete Begriffe: Ein Objekt ist eine Region, die das Skript gefunden und nummeriert hat. Ein Asset ist das, was das Spiel braucht: ein Requisit, ein Icon, eine Kachel. Die Aufgabe ist es, jedes Objekt genau zu einem Asset zu machen. Eine Zelle ist ein Quadrat des Kachelrasters der Tafel.

Erfordert Node im Pfad (node --version). Nichts zu installieren. Die Eingabe muss PNG sein.

Befehle werden ausgeführt als node "${CLAUDE_SKILL_DIR}/scripts/sheet.js" <befehl> ..., mit Pfaden in Anführungszeichen; --help listet jeden Befehl und jede Option auf. Claude Code füllt den Skill-Ordner in diesen Befehlen aus. Wenn du einen Platzhalter siehst, der mit ${CLAUDE_ beginnt, anstatt eines echten Pfads (Codex und andere Agenten), setze den Ordner, der diese SKILL.md enthält, an seine Stelle. Wähle einen Arbeitsordner pro Blatt (WORK) und einen neuen, leeren Ausgabeordner (OUT), beide außerhalb des Skill-Ordners. Schreibe Operations- und Namensdateien mit deinem Dateischreibwerkzeug (Write in Claude Code, apply_patch in Codex), das UTF-8 speichert; eine UTF-16-Datei von einer PowerShell-Umleitung wird abgelehnt.

Fortschrittsliste zum Kopieren und Abhaken:

[ ] Lizenz geprüft     [ ] Kachelgröße gefunden
[ ] detect: Warnungen gelesen
[ ] review: Seiten gelesen, Art des Blattes entschieden
[ ] apply (Runde 1)     [ ] erneut prüfen
[ ] names (falls gewünscht)   [ ] export: Abdeckung vollständig
[ ] Bericht

Bevor du beginnst

  1. Überprüfe die Lizenz. Wenn der Benutzer eine Store-Seite oder eine Readme-Datei angegeben hat, lies deren Lizenztext. Wenn sie die KI-Nutzung einschränkt ("keine KI", "nicht für KI-Training", "darf nicht an KI verfüttert werden"), stoppe und frage den Benutzer, wie weiter verfahren werden soll.
    • Wenn er dir sagt, du sollst fortfahren, setze den normalen Arbeitsablauf fort und gib in deinem Bericht an, dass er diese Entscheidung getroffen hat.
    • Wenn er die Grafiken von der KI fernhalten möchte: Führe detect und review aus, teile ihm mit, wo WORK/pages ist, und lass ihn die Dateien ansehen und die Operations-Datei schreiben. Öffne weder die Seiten, native.png noch irgendein Sprite. Du darfst weiterhin apply, review, status und export für ihn ausführen und den Text lesen, den diese ausgeben.
  2. Finde die Kachelgröße. Pack-Beschreibungen geben sie normalerweise an ("16x16 Kacheln", "32x32 Stil, an einem 16er-Raster ausgerichtet"). Übergib sie als --tile N. Sie ist am wichtigsten bei Kunst ohne Konturen: Bei synthetischen Testblättern von unkonturiertem Gelände und flach schattierten Requisiten schnitt das Skript mit der Kachelgröße etwa 90% der Assets korrekt und ohne sie unter 40%. Wenn die Beschreibung sagt, dass es kein Raster gibt, übergib --tile none. Wenn nichts gesagt wird, lasse --tile weg; das Skript versucht dann, eine Größe abzuleiten und teilt dies mit.
  3. Ein Blatt, ein Arbeitsordner. Ein erneutes Ausführen von detect in einem Arbeitsordner startet dieses Blatt von vorne.

Arbeitsablauf

1. Erkennung

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

Es gibt den gefundenen Hintergrund, den Kunststil (konturiert oder flach; informativ), die Kachelgröße, die Anzahl der Objekte sowie WARNING- und note-Zeilen aus. Reagiere wie folgt:

Es gibt ausTue dies
kind: scene_or_single_objectSehr wenige Objekte, und eines enthält den Großteil der Grafik. Lies das Bild. Wenn es eine Mock-Up-Szene ist (überlappende Objekte, die auf einem Boden stehen), teile dem Benutzer mit, dass sie nicht in saubere Assets zerlegt werden kann, und stoppe. Wenn es sich um ein oder wenige große Sprites handelt, fahre fort.
background: noneEin undurchsichtiges Bild, dessen Hintergrund nicht erkannt wurde. Lies das Bild, finde die Hintergrundfarbe, führe erneut mit --bg rrggbb aus (trenne die Farben eines eingebackenen Schachbrettmusters durch Kommas).
"Hintergrundfarbe kommt auch innerhalb des Kunstwerks vor"Sprite-Kanten können beschädigt sein. Teile dem Benutzer mit, dass eine transparente Quelle sicherer wäre; fahre fort.
"eingeschlossene Region(en) der Hintergrundfarbe wurden entfernt"Normal bei gepackten Blättern. Wenn Sprites auf den Seiten Löcher aufweisen, führe erneut mit --pockets large oder --pockets keep aus.
"als xN Vergrößerung gelesen"Das Bild war eine vergrößerte Vorschau und wurde verkleinert. --tile und jede Position sind in nativen Pixeln. Wenn das Bild keine Vergrößerung ist, führe erneut mit --scale 1 aus.
tile: 16px (abgeleitet)Eine Schätzung, wie Objekte ausgerichtet sind. Wenn das Paket kein Raster hat, führe erneut mit --tile none aus; wenn es eine Größe angibt, übergib sie.
tile: noneKein Gitter. Die cells- und tiles-Operationen sind nicht verfügbar und cut akzeptiert px.
"Sprenkel ... wurden in das neben ihnen liegende Objekt eingefügt"Normalerweise einzelne Pixel. Wenn das Paket echte Sprites mit weniger als sechs Pixeln hat, siehe split in der Operationsreferenz.
"nahezu unsichtbare Pixel ... als transparent behandelt"Nichts zu tun.

2. Überprüfung

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

Dies schreibt WORK/pages/*.png und WORK/objects.json und gibt Hinweise aus. Öffne die Seiten mit deinem Bildbetrachtungswerkzeug (Read in Claude Code, view_image in Codex): alle, wenn es acht oder weniger sind; andernfalls zuerst die Seiten, die markierte Objekte auflisten, danach eine Stichprobe der restlichen. Seiten überlappen sich etwas, sodass ein Objekt in der Nähe einer Seitenkante auf zwei Seiten mit derselben ID erscheint. Ein Blatt, das passt, wird auf eine Seite gezeichnet; ein Blatt mit mehr als 600 Objekten erhält nur die Seiten mit markierten Objekten (oder eine Stichprobe, wenn nichts markiert ist).

Lesen einer Seite:

  • Die Grafik wird in ihren wahren Farben auf einem dunklen Karomuster gezeigt. Jedes Objekt hat eine farbige Kontur entlang der genauen Kante seiner Pixel und eine Zahl in derselben Farbe. Die Zahl ist die ID. Sie sitzt innerhalb großer Objekte und neben kleinen. Ein Objekt, das aus mehreren Teilen besteht, hat eine Zahl und eine Kontur derselben Farbe um jedes Teil.
  • Die Zahlen oben und links sind das Lineal: Zellenindizes auf einem Blatt mit einer Kachelgröße (Zelle 3 beginnt bei Pixel 3 x Kachelgröße), andernfalls Pixelpositionen.
  • Ein weißes Doppelkästchen markiert ein markiertes Objekt. Markierungen sind Aufforderungen zum Hinsehen, keine Fehler:
    • shares_cell: mehrere Objekte befinden sich innerhalb einer Zelle.
    • close_same_colours: ein anderes Objekt, das seine Farben teilt, liegt 2 Pixel oder weniger entfernt.
    • doubtful_border: das Objekt berührt eine Rastergrenze (magenta Balken), bei der die Entscheidung zum Schneiden oder Verbinden knapp war. Dünne diagonale Sprites, die eine Gitterlinie kreuzen, erhalten dies oft und sind in Ordnung.
    • exposed_fill: die Fläche des Objekts liegt direkt an einer anderen Fläche ohne dazwischenliegende Kontur: ein falscher Schnitt oder zwei Assets ohne Kontur dazwischen.
    • large_blob: weitaus größer als die anderen Objekte. Oft mehrere verschmolzene Assets.
    • speck: unter sechs Pixeln.
  • Cyan Striche markieren Nähte, die das Skript auf einem Blatt ohne Gitter geschnitten hat.
  • Abgedunkelte Grafiken ohne Kontur wurden verworfen.

Die von review ausgegebenen Hinweise sagen dir, was ein Bild nicht kann: welche Objekte sich eine Zelle teilen, wie weit benachbarte Objekte voneinander entfernt sind, welche Paare den geringsten Abstand haben und welche nahen Paare ihre Farben teilen. Ein farbteilendes Paar wird als 12+13@1px=28x28 geschrieben: IDs, Abstand und die Größe der beiden zusammen. Sie sind der Hauptanhaltspunkt für den häufigsten Fehler, ein Asset, das aus mehreren losen Teilen besteht, obwohl ein Teil, dessen Farben sich von denen seines Partners unterscheiden, nicht aufgeführt wird.

Wenn eine Seite nicht ausreicht:

  • review --ids 12,13 schreibt eine vergrößerte Seite der Region um diese Objekte (pages/focus_*.png), einschließlich der Nachbarn, und lässt alles andere unverändert. Gib IDs an, die nahe beieinander liegen, ein Paar nach dem anderen; weit auseinander liegende IDs ergeben eine Seite, die nicht größer als die normale ist. --zoom funktioniert damit. Verwende es für kleine Sprites und für jedes Paar, bei dem du dir unsicher bist.
  • review --zoom 8 rendert das gesamte Blatt größer. Ein einfaches review kehrt zum Standard zurück.
  • WORK/native.png ist das saubere Blatt in Originalgröße.
  • status --list gibt eine Zeile pro Objekt aus: ID, Zellen, Box, Fläche, Flags.

Entnimm IDs aus status --list oder objects.json und nicht nur aus dem Bild: Überprüfe, dass die cells oder bbox des Objekts dort ist, wo du es gesehen hast. Eine ID, die existiert, aber nicht die ist, die du meintest, wird akzeptiert und ändert das falsche Objekt.

3. Entscheiden und Bearbeiten

Wenn jedes Asset bereits genau ein Objekt hat, überspringe diesen Schritt. Es wird keine Operations-Datei benötigt, und du kannst beim aktuellen Revisionsstand benennen und exportieren. Die Stoppüberprüfungen am Ende dieses Schritts gelten trotzdem.

Andernfalls entscheide, um welche Art von Blatt es sich handelt, denn das bestimmt das Rezept. references/sheet-kinds.md beschreibt jede Art und ihre üblichen Probleme.

ArtÜbliche Operationen
Einzelne Requisiten mit Lückenmerge, cells oder near für Requisiten, die als lose Teile gezeichnet wurden. Überprüfe die Hinweise, bevor du entscheidest, dass nichts zu tun ist.
Requisiten randlos gepacktcut, wo zwei Requisiten noch verschmolzen sind; merge, wo ein Requisit geteilt wurde.
Icon-Raster, ein Icon pro Zellecells einmal, dann drop für alle Beschriftungsfelder.
Gelände- oder Wandtilesettiles auf noch verschmolzene Blöcke. Wände, die über Rasterlinien gezeichnet sind: ganz lassen.
Kein GitterÜberprüfe die Cyan-Nähte: merge eine falsche, cut mit px, wo zwei Objekte noch verschmolzen sind.
GemischtJede Region nach ihrem eigenen Rezept; cells und near akzeptieren eine region.

Schreibe die Operations-Datei und wende sie an:

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

rev ist die Revision, die review ausgegeben hat (auch in objects.json). Die Datei ist ein Alles-oder-Nichts: Wenn eine Operation abgelehnt wird, ändert sich nichts; lies die Nachricht, korrigiere die Datei, wende sie erneut an. Vollständige Referenz mit Beispielen: references/ops.md.

OperationVerwende sie, wenn
merge idsMehrere Teile sind ein Asset.
cellsAlles innerhalb einer Zelle ist ein Asset (Icon-Raster, lose Teile innerhalb einer Zelle).
near pxViele Assets sind als lose Teile gezeichnet, die näher beieinander liegen als separate Assets.
cut id, achse, zelle / zellen / pxZwei oder mehr Assets sind verschmolzen. cells: [2, 4, 6] schneidet einen Streifen auf einmal.
tiles ids, optionaler spanEin verschmolzener Block soll ein Objekt pro Zelle oder pro span von Zellen werden.
split idMache eine Zusammenführung rückgängig: zurück zu den verbundenen Teilen des Objekts.
drop ids, grundKein Asset: Beschriftungstext, ein Wasserzeichen, ein Farbmuster.
restore idsMache ein Löschen rückgängig.
ok idsDu hast ein markiertes Objekt überprüft, und es ist richtig. Optional.

Bevorzuge die Massenoperationen (cells, near, tiles) gegenüber langen ID-Listen: weniger IDs, weniger Fehlinterpretationen.

IDs innerhalb einer Datei: Operationen werden der Reihe nach ausgeführt, und jede sieht das Ergebnis der vorherigen. merge, cells und near behalten die kleinste ID jeder Gruppe und lassen andere IDs in Ruhe, sodass spätere Operationen in derselben Datei sie weiterhin verwenden können. cut, tiles und split verwerfen die ID, auf die sie wirken, und erstellen neue IDs, die du erst aus der apply-Ausgabe erfährst, also kommt alles, was diese neuen IDs benötigt, in die nächste Runde.

Führe nach jedem apply erneut review aus und lies die neuen Seiten, bevor du weitere Operationen oder Namen schreibst.

Ein Stück oder zwei? Zwei benachbarte Stücke könnten ein Asset oder zwei sein. Gehe diese Liste durch:

  1. Sie befinden sich innerhalb einer Zelle eines Blattes, das ein Asset pro Zelle aufbaut (ein Icon-Raster): ein Asset.
  2. Sie sind mit unterschiedlichen Farben gemalt oder offensichtlich unterschiedliche Dinge: zwei Assets.
  3. Gemeinsame Farben, und die beiden zusammen haben die Größe und Platzierung der anderen Assets des Blattes, während jedes Stück allein dies nicht tut: ein Asset. Dies gilt auch dann, wenn jedes Stück seine eigene vollständige Kontur hat. Der Hinweis gibt die Größe zusammen an (=28x28); vergleiche sie mit den Größen einzelner Objekte in status --list. Schattierungsbänder oder Glanzlichter, die über die beiden Stücke hinweg ausgerichtet sind, oder ein Schatten unter beiden, deuten in dieselbe Richtung.
  4. Gemeinsame Farben, aber jedes Stück allein hat bereits die Größe und Platzierung der anderen Assets des Blattes (zwei Flaschen nebeneinander, jede so groß wie jede andere Flasche): zwei Assets.
  5. Immer noch unsicher: lass sie getrennt und liste sie in deinem Bericht auf. Ein Entwickler kann zwei Sprites kombinieren; ein verschmolzenes auseinanderzuziehen ist schwieriger.

Der Abstandshinweis hilft nur, wenn lose Stücke näher beieinander sitzen als separate Assets. Wenn beide 2 Pixel voneinander entfernt sind, kann er sie nicht unterscheiden, und Regel 3 entscheidet.

Stoppe, wenn die Seiten ein Objekt pro Asset zeigen. Drei Runden sind normalerweise ausreichend; ein Schnitt kann ein Stück hinterlassen, das einen weiteren Schnitt oder ein Löschen erfordert, was eine weitere Runde erfordert. Wenn nach drei Runden immer noch etwas falsch ist, exportiere trotzdem und melde es.

Bevor du stoppst, überprüfe:

  • Kein Objekt enthält zwei verschiedene Assets (cut, tiles). Sieh dir besonders large_blob-Objekte und alle Objekte an, die viel breiter oder höher als ihre Nachbarn sind.
  • Kein Asset ist auf mehrere Objekte verteilt (merge, cells, near).
  • Kein Objekt ist etwas anderes als ein Asset (drop).
  • Jedes markierte Objekt wurde einmal angesehen. Flags, die auf Objekten verbleiben, die du als korrekt beurteilt hast, sind in Ordnung.

4. Benennung (optional)

Überspringe diesen Schritt, wenn der Benutzer keine Namen wünscht: Exportiere ohne --names, und jedes Asset behält einen generierten Namen (obj_0042, tile_0107).

Andernfalls schreibe WORK/names.json für die aktuelle Revision. Benenne, was du erkennen kannst, und lass den Rest weg.

{ "rev": 1,
  "sheet": { "kind": "icon grid", "notes": "16px Gegenstands-Icons unter sechs Beschriftungsfeldern" },
  "assets": {
    "12": { "name": "weapon_sword_iron", "category": "weapons", "tags": ["melee"], "confidence": "high" },
    "40": { "name": "food_loaf", "category": "food", "confidence": "low", "description": "braunes Oval, könnte Brot oder eine Kartoffel sein" }
  } }
  • Schlüssel sind Objekt-IDs als einfache Zahlen. Namen sind Kleinbuchstaben, Ziffern und Unterstriche, maximal 64 Zeichen und eindeutig. Ein gutes Muster ist kategorie_ding_variante (bench_wood_stocked, locker_red_open).
  • sheet.kind, sheet.notes, category, tags und description sind Freitext für den Leser des Katalogs.
  • Verwende den auf dem Blatt aufgedruckten Beschriftungstext als Kategorie, falls vorhanden.
  • Beurteile die Farbe anhand der Grafik innerhalb der Kontur, niemals anhand der Kontur oder der Markierung.
  • Setze "confidence" auf "low", wenn du rätst; dies markiert den Namen im Katalog.

5. Export

node "${CLAUDE_SKILL_DIR}/scripts/sheet.js" export --work "WORK" --out "OUT" --names "WORK/names.json"

Jedes Asset wird in eine eigene Datei geschrieben: OUT/obj_0042.png, OUT/tile_0107.png. Wenn eine Names-Datei übergeben wird (--names), respektiert der Export die name-Eigenschaft jedes Assets. Eine .json-Katalogdatei wird immer geschrieben: OUT/catalogue.json. Diese listet die Dateien, ihre Asset-Namen (falls vorhanden, sonst generiert), Attribute aus der Names-Datei und ihre Position im Blatt (in Zellen, wenn ein Kachelraster verwendet wird, sonst Pixel).

Standardmäßig wird die Grafik jedes Assets in derselben Größe wie auf dem Blatt ausgegeben, beschränkt auf die Begrenzungsbox. Verwende --extrude N, um N Pixel transparenten Rand um jedes Asset hinzuzufügen (nützlich für Mipmapping oder native iOS-Grafiken). Verwende --pad N, um jedes auf das nächste Vielfache von N aufzufüllen (nützlich für uniforme Texturen). Verwende --format png, --format webp oder --format jpeg (Standard: PNG) zusammen mit --quality 0..100 (Standard: verlustfrei/100).

Der Exporteur gibt am Ende eine Zusammenfassung der Kantenqualität aus: Die Pixelkante wird mit der beginnenden Alpha-Linie jedes Assets im Blatt verglichen. Die Zusammenfassung listet die Anzahl der Pixel auf, an denen der Schnitt 1, 2 oder 3+ Pixel von der Alpha-Kante entfernt war, und das Blatt-Pixel, das die meiste Abweichung aufweist. Eine 100% saubere Kante ist das Ziel.

Referenz: status

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

Gibt die aktuelle Objektmenge, die Anzahl der gelöschten Objekte und die verwendete Kachelgröße aus.

Referenz: Bericht

Wenn du fertig bist, schreibe eine kurze Zusammenfassung:

  • Wie viele Assets wurden exportiert.
  • Wie viele Runden waren nötig, um sie zu trennen.
  • Alle wichtigen Entscheidungen oder Annahmen, die ein Entwickler überprüfen sollte.
  • Alle Stücke, bei denen du dir nicht sicher warst (mit IDs und Seitennummern).
  • Die Kantenqualität des Exports (100 % sauber oder wie viel nicht).

**Hinweis:** Der gesamte Inhalt bis einschließlich des Berichts ist lokalisiert; alle technischen Begriffe, Pfade und Codeblöcke bleiben erhalten. Der ursprüngliche englische Text wurde für jede relevante Plattform (Claude Code, Codex usw.) ins Deutsche übersetzt.

Verwandte Skills