Que fait Découpeur de feuille de sprites ?
Le script possède les pixels et vous possédez la signification.
scripts/sheet.jstrouve chaque objet, sait exactement quel pixel appartient à quel objet, et dessine des pages de révision numérotées.- Vous regardez les pages, décidez ce qui compte comme une ressource, et le dites avec de courtes opérations d'édition qui nomment les objets par leur id et les emplacements par la règle imprimée sur la page.
- Vous n'estimez jamais où se trouve le bord d'un sprite. Une position lue sur une image est approximative, donc la seule position libre que le script accepte (
cutavecpx) est déplacée vers la couture la plus forte dans un rayon de 3 pixels.
Mots utilisés ici : un objet est une région que le script a trouvée et numérotée. Une ressource est ce dont le jeu a besoin : un accessoire, une icône, une tuile. Le travail consiste à faire en sorte que chaque objet corresponde exactement à une ressource. Une cellule est un carré de la grille de tuiles de la feuille.
Nécessite Node sur le PATH (node --version). Rien à installer. L'entrée doit être un PNG.
Les commandes s'exécutent comme node "${CLAUDE_SKILL_DIR}/scripts/sheet.js" <commande> ..., avec les chemins entre guillemets ; --help liste chaque commande et option. Claude Code remplit le dossier de compétence dans ces commandes. Si vous voyez un espace réservé commençant par ${CLAUDE_ au lieu d'un chemin réel (Codex et autres agents), mettez le dossier qui contient ce SKILL.md à sa place. Choisissez un dossier de travail par feuille (WORK) et un dossier de sortie nouveau et vide (OUT), tous deux en dehors du dossier de compétence. Écrivez les fichiers d'opérations et de noms avec votre outil d'écriture de fichiers (Write dans Claude Code, apply_patch dans Codex), qui enregistre en UTF-8 ; un fichier UTF-16 provenant d'une redirection PowerShell est refusé.
Liste de progression à copier et à cocher :
[ ] licence vérifiée [ ] taille de tuile trouvée
[ ] détection : avertissements lus
[ ] révision : pages lues, type de feuille décidé
[ ] appliquer (tour 1) [ ] réviser à nouveau
[ ] noms (si souhaité) [ ] export : couverture complète
[ ] rapport
Avant de commencer
- Vérifiez la licence. Si l'utilisateur a fourni une page de vente ou un fichier readme, lisez son texte de licence. Si elle restreint l'utilisation par IA ("pas d'IA", "pas pour l'entraînement IA", "ne peut pas être fourni à une IA"), arrêtez-vous et demandez à l'utilisateur comment procéder.
- S'ils vous disent de continuer, poursuivez avec le flux de travail normal et dites dans votre rapport qu'ils ont pris cette décision.
- S'ils veulent que les illustrations soient tenues à l'écart de l'IA : exécutez
detectetreview, dites-leur où se trouveWORK/pages, et laissez-les regarder et écrire le fichier d'opérations. N'ouvrez pas les pages,native.pngou tout sprite. Vous pouvez toujours exécuterapply,review,statusetexportpour eux et lire le texte qu'ils impriment.
- Trouvez la taille de tuile. Les descriptions de packs indiquent généralement cette taille ("tuiles 16x16", "style 32x32 aligné sur une grille 16"). Passez-la comme
--tile N. Elle est très importante sur les illustrations sans contour : sur des feuilles de test synthétiques de terrain sans contour et d'accessoires à ombrage plat, le script a découpé environ 90 % des ressources correctement avec la taille de tuile et moins de 40 % sans. Si la description dit qu'il n'y a pas de grille, passez--tile none. Si elle ne dit rien, omettez--tile; le script essaie alors de déduire une taille et le mentionne. - Une feuille, un dossier de travail. Relancer
detectsur un dossier de travail recommence cette feuille.
Flux de travail
1. Détection
node "${CLAUDE_SKILL_DIR}/scripts/sheet.js" detect "<feuille.png>" --work "WORK" --tile 16
Il imprime l'arrière-plan trouvé, le style artistique (contourné ou plat ; informatif), la taille de tuile, le nombre d'objets, et des lignes WARNING et note. Agissez sur ceux-ci :
| Il imprime | Faites ceci |
|---|---|
kind: scene_or_single_object | Très peu d'objets, et l'un d'eux contient la majeure partie de l'illustration. Lisez l'image. S'il s'agit d'une scène maquette (objets qui se chevauchent, debout sur un sol), dites à l'utilisateur qu'elle ne peut pas être découpée en ressources propres et arrêtez-vous. S'il s'agit d'un ou de quelques grands sprites, continuez. |
background: none | Une image opaque dont l'arrière-plan n'a pas été reconnu. Lisez l'image, trouvez la couleur de fond, relancez avec --bg rrggbb (séparez par des virgules les couleurs d'un damier cuit). |
| "la couleur de fond apparaît également à l'intérieur de l'illustration" | Les bords des sprites peuvent être endommagés. Dites à l'utilisateur qu'une source transparente serait plus sûre ; continuez. |
| "des régions fermées de couleur de fond ont été supprimées" | Normal sur les feuilles tassées. Si les sprites montrent des trous sur les pages, relancez avec --pockets large ou --pockets keep. |
| "lu comme un agrandissement xN" | L'image était un aperçu agrandi et a été réduite. --tile et chaque position sont en pixels natifs. Si l'image n'est pas un agrandissement, relancez avec --scale 1. |
tile: 16px (déduite) | Une estimation basée sur l'alignement des objets. Si le pack n'a pas de grille, relancez avec --tile none ; s'il indique une taille, passez-la. |
tile: none | Pas de grille. Les opérations cells et tiles ne sont pas disponibles et cut utilise px. |
| "des taches ... ont été fusionnées avec l'objet à côté d'elles" | Généralement des pixels isolés. Si le pack contient de vrais sprites de moins de six pixels, voyez split dans la référence des opérations. |
| "des pixels presque invisibles ... traités comme transparents" | Rien à faire. |
2. Révision
node "${CLAUDE_SKILL_DIR}/scripts/sheet.js" review --work "WORK"
Cela écrit WORK/pages/*.png et WORK/objects.json et imprime des indices. Ouvrez les pages avec votre outil de visualisation d'images (Read dans Claude Code, view_image dans Codex) : toutes lorsqu'il y en a huit ou moins ; sinon celles listant d'abord les objets signalés, puis un échantillon du reste. Les pages se chevauchent un peu, donc un objet près du bord d'une page apparaît sur deux pages avec le même id. Une feuille qui tient est dessinée sur une seule page ; une feuille de plus de 600 objets ne reçoit que les pages avec des objets signalés (ou un échantillon quand rien n'est signalé).
Lecture d'une page :
- L'illustration est montrée dans ses vraies couleurs sur un damier sombre. Chaque objet a un contour coloré le long du bord exact de ses pixels et un numéro dans la même couleur. Le numéro est l'id. Il se trouve à l'intérieur des grands objets et à côté des petits. Un objet fait de pièces séparées a un numéro et un contour de la même couleur autour de chaque pièce.
- Les numéros le long du haut et de la gauche sont la règle : indices de cellule sur une feuille avec une taille de tuile (la cellule 3 commence au pixel 3 x taille de tuile), positions en pixels sinon.
- Une double boîte blanche marque un objet signalé. Les signalements sont des invites à regarder, pas des erreurs :
shares_cell: plusieurs objets se trouvent à l'intérieur d'une seule cellule.close_same_colours: un autre objet partageant ses couleurs se trouve à 2 pixels ou moins.doubtful_border: l'objet touche une bordure de grille (barre magenta) où le choix de couper ou joindre était serré. Les sprites diagonaux fins traversant une ligne de grille reçoivent souvent ceci et sont corrects.exposed_fill: le remplissage de l'objet est directement contre un autre objet sans contour entre eux : une coupe incorrecte, ou deux ressources sans contour entre elles.large_blob: bien plus grand que les autres objets. Souvent plusieurs ressources fusionnées.speck: moins de six pixels.
- Des tirets cyan marquent les coutures que le script a coupées sur une feuille sans grille.
- Les illustrations atténuées sans contour ont été supprimées.
Les indices imprimés par review vous disent ce qu'une image ne peut pas : quels objets partagent une cellule, à quelle distance se trouvent les voisins, quelles paires sont à l'écart le plus proche, et quelles paires proches partagent leurs couleurs. Une paire partageant des couleurs est écrite 12+13@1px=28x28 : ids, écart, et taille des deux ensemble. Ce sont les principaux indices pour l'erreur la plus courante, une ressource dessinée comme plusieurs pièces détachées, bien qu'une pièce dont les couleurs diffèrent de celles de son partenaire ne soit pas listée.
Quand une page ne suffit pas :
review --ids 12,13écrit une page agrandie de la zone autour de ces objets (pages/focus_*.png), voisins inclus, et laisse tout le reste tranquille. Donnez des ids qui sont proches les uns des autres, une paire à la fois ; des ids éloignés donnent une page pas plus grande que la normale.--zoomfonctionne avec. Utilisez-le pour les petits sprites et pour toute paire dont vous n'êtes pas sûr.review --zoom 8ré-affiche toute la feuille en plus grand. Un simplereviewrevient à la valeur par défaut.WORK/native.pngest la feuille propre à la taille native.status --listimprime une ligne par objet : id, cellules, boîte, zone, indicateurs.
Prenez les ids de status --list ou objects.json plutôt que de la seule image : vérifiez que les cells ou bbox de l'objet correspondent à l'endroit où vous l'avez vu. Un id qui existe mais n'est pas celui que vous vouliez est accepté et modifie le mauvais objet.
3. Décider et éditer
Si chaque ressource a déjà exactement un objet, sautez cette étape. Aucun fichier d'opérations n'est nécessaire et vous pouvez nommer et exporter à la révision actuelle. Les vérifications d'arrêt à la fin de cette étape s'appliquent toujours.
Sinon, décidez de quel type de feuille il s'agit, car cela détermine la recette. references/sheet-kinds.md décrit chaque type et ses problèmes habituels.
| Type | Opérations habituelles |
|---|---|
| Accessoires séparés avec espacements | merge, cells ou near pour les accessoires dessinés comme pièces détachées. Vérifiez les indices avant de décider qu'il n'y a rien à faire. |
| Accessoires tassés bord à bord | cut là où deux accessoires sont encore fusionnés, merge là où un accessoire a été divisé. |
| Grille d'icônes, une icône par cellule | cells une fois, puis drop pour les boîtes d'étiquettes. |
| Tileset de terrain ou de mur | tiles sur les blocs encore fusionnés. Murs dessinés à travers les lignes de grille : laissez entiers. |
| Pas de grille | Vérifiez les coutures cyan : merge une couture erronée, cut avec px là où deux objets sont encore fusionnés. |
| Mixte | Chaque région avec sa propre recette ; cells et near prennent une region. |
Écrivez le fichier d'opérations et appliquez-le :
{ "rev": 0, "ops": [
{ "op": "cells" },
{ "op": "drop", "ids": [7, 31], "reason": "boîtes d'étiquettes de catégorie" }
] }
node "${CLAUDE_SKILL_DIR}/scripts/sheet.js" apply --work "WORK" --ops "WORK/ops_r1.json"
rev est la révision que review a imprimée (également dans objects.json). Le fichier est tout-ou-rien : si une opération est rejetée, rien ne change ; lisez le message, corrigez le fichier, réappliquez. Référence complète avec exemples : references/ops.md.
| Opération | Utilisez-la quand |
|---|---|
merge ids | Plusieurs pièces sont une seule ressource. |
cells | Tout ce qui se trouve à l'intérieur d'une cellule est une ressource (grilles d'icônes, pièces détachées dans une cellule). |
near px | De nombreuses ressources sont dessinées comme des pièces détachées plus proches les unes des autres que les ressources séparées. |
cut id, axe, cellule / cellules / px | Deux ressources ou plus sont fusionnées. cells: [2, 4, 6] coupe une bande en une seule fois. |
tiles ids, étendue optionnelle | Un bloc fusionné doit devenir un objet par cellule, ou par span de cellules. |
split id | Annuler une fusion : revenir aux pièces connectées de l'objet. |
drop ids, raison | Pas une ressource : texte d'étiquette, filigrane, échantillon de couleur. |
restore ids | Annuler une suppression. |
ok ids | Vous avez vérifié un objet signalé et il est correct. Optionnel. |
Préférez les opérations groupées (cells, near, tiles) aux longues listes d'ids : moins d'ids, moins d'erreurs de lecture.
Ids dans un même fichier : les opérations s'exécutent dans l'ordre et chacune voit le résultat des précédentes. merge, cells et near conservent le plus petit id de chaque groupe et laissent les autres ids tranquilles, donc les opérations ultérieures dans le même fichier peuvent encore les utiliser. cut, tiles et split retirent l'id sur lequel ils agissent et créent de nouveaux ids que vous n'apprenez qu'à partir du résultat d'application, donc tout ce qui nécessite ces nouveaux ids va dans le tour suivant.
Après chaque application, exécutez review à nouveau et lisez les nouvelles pages avant d'écrire plus d'opérations ou de noms.
Une pièce ou deux ? Deux pièces proches pourraient être une ressource ou deux. Parcourez cette liste :
- Elles se trouvent à l'intérieur d'une cellule d'une feuille construite avec une ressource par cellule (une grille d'icônes) : une ressource.
- Elles sont peintes avec des couleurs différentes, ou sont clairement des choses différentes : deux ressources.
- Couleurs partagées, et les deux ensemble ont la taille et le placement des autres ressources de la feuille alors que chaque pièce seule ne les a pas : une ressource. Cela tient même lorsque chaque pièce a son propre contour complet. L'indice donne la taille ensemble (
=28x28) ; comparez-la avec les tailles des objets uniques dansstatus --list. Des bandes d'ombrage ou des reflets qui s'alignent entre les deux pièces, ou une ombre sous les deux, indiquent la même chose. - Couleurs partagées, mais chaque pièce seule a déjà la taille et le placement des autres ressources de la feuille (deux bouteilles côte à côte, chacune aussi grande que toutes les autres bouteilles) : deux ressources.
- Toujours incertain : laissez-les séparées et listez-les dans votre rapport. Un développeur peut combiner deux sprites ; séparer une ressource fusionnée est plus difficile.
L'indice d'écart n'aide que lorsque les pièces détachées sont plus proches les unes des autres que les ressources séparées. Quand les deux sont à 2 pixels de distance, il ne peut pas les distinguer, et la règle 3 décide.
Arrêtez-vous lorsque les pages montrent un objet par ressource. Trois tours sont normalement suffisants ; une coupe peut laisser une pièce qui nécessite une coupe ou une suppression supplémentaire, ce qui prend un autre tour. Si quelque chose est encore faux après trois, exportez quand même et signalez-le.
Avant de vous arrêter, vérifiez :
- Aucun objet ne contient deux ressources différentes (
cut,tiles). Regardez le plus attentivement les objetslarge_blobet tout objet beaucoup plus large ou plus haut que ses voisins. - Aucune ressource n'est répartie sur plusieurs objets (
merge,cells,near). - Aucun objet n'est autre chose qu'une ressource (
drop). - Chaque objet signalé a été examiné une fois. Les indicateurs qui restent sur des objets que vous avez jugés corrects sont acceptables.
4. Nommer (optionnel)
Sautez cette étape si l'utilisateur ne veut pas de noms : exportez sans --names et chaque ressource conserve un nom généré (obj_0042, tile_0107).
Sinon, écrivez WORK/names.json pour la révision actuelle. Nommez ce que vous pouvez reconnaître et omettez le reste.
{ "rev": 1,
"sheet": { "kind": "grille d'icônes", "notes": "Icônes d'objets 16px sous six boîtes d'étiquettes" },
"assets": {
"12": { "name": "arme_epee_fer", "category": "armes", "tags": ["melee"], "confidence": "high" },
"40": { "name": "nourriture_pain", "category": "nourriture", "confidence": "low", "description": "ovale marron, pourrait être du pain ou une pomme de terre" }
} }
- Les clés sont les ids d'objets sous forme de nombres simples. Les noms sont en lettres minuscules, chiffres et underscores, au maximum 64 caractères, et uniques. Un bon modèle est
categorie_chose_variante(banc_bois_rembourre,casier_rouge_ouvert). sheet.kind,sheet.notes,category,tagsetdescriptionsont du texte libre pour quiconque lit le catalogue.- Utilisez le texte d'étiquette imprimé sur la feuille comme catégorie lorsqu'il y en a.
- Jugez la couleur à partir de l'illustration à l'intérieur du contour, jamais à partir du contour ou de la couleur de fond.
- Mettez une ressource non reconnaissable dans
misc(divers) ouunknown(inconnu).
5. Exporter
node "${CLAUDE_SKILL_DIR}/scripts/sheet.js" export --work "WORK" --out "OUT" [--names "WORK/names.json"] [--padding 2]
Écrit OUT/*.png, un par ressource, et OUT/catalogue.json ou OUT/catalogue.csv. Tous les sprites qui partagent la même catégorie sont dans un sous-dossier OUT/<catégorie>/.
--padding 0 coupe exactement au bord des pixels, pratique pour les icônes. --padding 2 (ou plus) laisse un espace, ce qui est important pour les textures de terrain qui autrement saignent d'une face à l'autre de la tuile voisine dans le rendu.
--atlas écrit une seule feuille. --trim supprime les lignes de pixels entièrement transparentes sur les bords de chaque sprite.
6. Rapport
Terminez par un résumé de ce qui s'est passé, le nombre de ressources exportées, tout problème restant, et où se trouve le catalogue. Utilisez status si vous souhaitez une liste lisible par machine.
Références
- references/ops.md — Référence complète des opérations avec exemples.
- references/sheet-kinds.md — Types de feuilles et leurs problèmes habituels.
Notes de version
- Si la compétence est installée dans un projet de jeu, elle peut réutiliser une taille de tuile ou un dossier de sortie à partir de la configuration du projet (
package.json, fichier de build). Sinon, chaque exécution part de zéro. L'importation directe via le système de modules de Node n'est pas prise en charge ; exécutez-la toujours via le scrip de shell.