CommunityImagengithub.com

cortador-de-hoja-de-sprites

Corta una hoja de sprites, tileset o iconos (PNG) en una imagen por activo y escribe un catálogo que nombra cada activo, registra su tamaño en mosaicos e indica su origen.

¿Qué es cortador-de-hoja-de-sprites?

Sprite Sheet Slicer es una herramienta de línea de comandos diseñada para desarrolladores de juegos que necesitan extraer y organizar activos individuales a partir de una hoja de sprites, tileset o lámina de iconos. La herramienta automatiza la detección de regiones de objetos, permite revisar visualmente el resultado mediante páginas numeradas y ofrece un conjunto de operaciones de edición (como fusionar, cortar, alinear a cuadrícula, separar por teselas, eliminar o restaurar) para que cada objeto corresponda exactamente a un activo del juego. Es compatible con Node.js (sin dependencias adicionales), acepta solo PNG como entrada y puede manejar tanto hojas con cuadrícula explícita como sin ella, así como múltiples estilos artísticos. El flujo de trabajo típico incluye detección de objetos, revisión visual, aplicación de correcciones mediante un archivo JSON de operaciones, y opcionalmente la creación de un catálogo de nombres. La herramienta también respeta restricciones de licencia relacionadas con IA, permitiendo al usuario decidir si continuar cuando la licencia prohíbe el uso de IA. Está diseñada para agentes como Claude Code, Codex y otros, y utiliza parámetros como --tile, --bg, --zoom y comandos como detect, review, apply, status y export.

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

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Cortador de hoja de sprites

El script posee los píxeles y tú posees el significado.

  • scripts/sheet.js encuentra cada objeto, sabe exactamente qué píxel pertenece a cuál y dibuja páginas de revisión numeradas.
  • Tú observas las páginas, decides qué cuenta como un activo y lo indicas con breves operaciones de edición que nombran objetos por su id y posiciones por la regla impresa en la página.
  • Nunca estimas dónde está el borde de un sprite. Una posición leída de una imagen es aproximada, por lo que la única posición libre que el script acepta (cut con px) se mueve al corte más fuerte en un radio de 3 píxeles.

Términos usados aquí: un objeto es una región que el script encontró y numeró. Un activo es lo que el juego necesita: un accesorio, un icono, un mosaico. La tarea es hacer que cada objeto sea exactamente un activo. Una celda es un cuadrado de la cuadrícula de mosaicos de la hoja.

Requiere Node en PATH (node --version). No hay nada que instalar. La entrada debe ser PNG.

Los comandos se ejecutan como node "${CLAUDE_SKILL_DIR}/scripts/sheet.js" <comando> ..., con rutas entre comillas; --help lista todos los comandos y opciones. Claude Code completa la carpeta del skill en estos comandos. Si ves un marcador de posición que comienza con ${CLAUDE_ en lugar de una ruta real (Codex y otros agentes), coloca la carpeta que contiene este SKILL.md en su lugar. Elige una carpeta de trabajo por hoja (WORK) y una carpeta de salida nueva y vacía (OUT), ambas fuera de la carpeta del skill. Escribe los archivos de operaciones y nombres con tu herramienta de escritura de archivos (Write en Claude Code, apply_patch en Codex), que guarda UTF-8; un archivo UTF-16 proveniente de una redirección de PowerShell es rechazado.

Lista de progreso para copiar y marcar:

[ ] licencia verificada     [ ] tamaño de mosaico encontrado
[ ] detectar: advertencias leídas
[ ] revisar: páginas leídas, tipo de hoja decidido
[ ] aplicar (ronda 1)      [ ] revisar de nuevo
[ ] nombres (si se desea)  [ ] exportar: cobertura completa
[ ] informe

Antes de comenzar

  1. Verifica la licencia. Si el usuario proporcionó una página de tienda o un archivo léame, lee su texto de licencia. Si restringe el uso de IA ("sin IA", "no para entrenamiento de IA", "no puede ser alimentado a IA"), detente y pregunta al usuario cómo proceder.
    • Si te dicen que sigas adelante, continúa con el flujo de trabajo normal e indica en tu informe que ellos tomaron esa decisión.
    • Si quieren que el arte se mantenga alejado de la IA: ejecuta detect y review, diles dónde está WORK/pages y permite que ellos miren y escriban el archivo de operaciones. No abras las páginas, native.png ni ningún sprite. Aún puedes ejecutar apply, review, status y export por ellos y leer el texto que imprimen.
  2. Encuentra el tamaño del mosaico. Las descripciones de los paquetes suelen indicarlo ("mosaicos de 16x16", "estilo de 32x32 alineado a una cuadrícula de 16"). Pásalo como --tile N. Es más importante en arte sin contornos: en hojas de prueba sintéticas de terreno sin contornos y accesorios con sombreado plano, el script cortó aproximadamente el 90% de los activos correctamente con el tamaño de mosaico y menos del 40% sin él. Si la descripción dice que no hay cuadrícula, pasa --tile none. Si no dice nada, omite --tile; el script entonces intenta inferir un tamaño y lo indica.
  3. Una hoja, una carpeta de trabajo. Volver a ejecutar detect en una carpeta de trabajo reinicia esa hoja.

Flujo de trabajo

1. Detectar

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

Imprime el fondo que encontró, el estilo de arte (con contorno o plano; informativo), el tamaño de mosaico, el número de objetos y líneas de WARNING y note. Actúa según estas:

ImprimeHaz esto
kind: scene_or_single_objectMuy pocos objetos, y uno contiene la mayor parte del arte. Lee la imagen. Si es una escena maqueta (objetos superpuestos, sobre un suelo), dile al usuario que no se puede cortar en activos limpios y detente. Si es uno o unos pocos sprites grandes, continúa.
background: noneUna imagen opaca cuyo fondo no fue reconocido. Lee la imagen, encuentra el color de fondo, vuelve a ejecutar con --bg rrggbb (separa con comas los colores de un tablero de ajedrez horneado).
"el color de fondo también ocurre dentro del arte"Los bordes del sprite pueden estar dañados. Dile al usuario que una fuente transparente sería más segura; continúa.
"región(es) encerrada(s) de color de fondo fueron eliminadas"Normal en hojas empaquetadas. Si los sprites muestran agujeros en las páginas, vuelve a ejecutar con --pockets large o --pockets keep.
"leído como una ampliación xN"La imagen era una vista previa ampliada y ha sido reducida. --tile y cada posición están en píxeles nativos. Si la imagen no es una ampliación, vuelve a ejecutar con --scale 1.
tile: 16px (inferido)Una suposición basada en cómo se alinean los objetos. Si el paquete no tiene cuadrícula, vuelve a ejecutar con --tile none; si indica un tamaño, pásalo.
tile: noneSin retícula. Las operaciones cells y tiles no están disponibles y cut usa px.
"motas ... se fusionaron con el objeto junto a ellas"Generalmente píxeles sueltos. Si el paquete tiene sprites reales de menos de seis píxeles, consulta split en la referencia de operaciones.
"píxeles casi invisibles ... tratados como transparentes"No hay nada que hacer.

2. Revisar

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

Esto escribe WORK/pages/*.png y WORK/objects.json e imprime pistas. Abre las páginas con tu herramienta de visualización de imágenes (Read en Claude Code, view_image en Codex): todas cuando haya ocho o menos; de lo contrario, las que enumeran primero los objetos marcados, luego una muestra del resto. Las páginas se superponen un poco, por lo que un objeto cerca del borde de una página aparece en dos páginas con el mismo id. Una hoja que cabe se dibuja en una página; una hoja de más de 600 objetos solo obtiene las páginas con objetos marcados (o una muestra cuando no hay nada marcado).

Lectura de una página:

  • El arte se muestra en sus colores reales sobre un tablero oscuro. Cada objeto tiene un contorno coloreado a lo largo del borde exacto de sus píxeles y un número del mismo color. El número es el id. Se encuentra dentro de objetos grandes y al lado de los pequeños. Un objeto compuesto de piezas separadas tiene un número y un contorno del mismo color alrededor de cada pieza.
  • Los números a lo largo de la parte superior e izquierda son la regla: índices de celda en una hoja con un tamaño de mosaico (la celda 3 comienza en el píxel 3 x mosaico), posiciones de píxel en caso contrario.
  • Un recuadro blanco doble marca un objeto señalado. Las marcas son indicaciones para mirar, no errores:
    • shares_cell: varios objetos están dentro de una celda.
    • close_same_colours: otro objeto que comparte sus colores está a 2 píxeles o menos.
    • doubtful_border: el objeto toca un borde de la retícula (barra magenta) donde la decisión de cortar o unir fue ajustada. Los sprites diagonales delgados que cruzan una línea de cuadrícula suelen tener esto y están bien.
    • exposed_fill: el relleno del objeto está directamente contra otro objeto sin contorno entre ellos: un corte incorrecto, o dos activos sin contorno entre ellos.
    • large_blob: mucho más grande que los otros objetos. A menudo varios activos fusionados.
    • speck: menos de seis píxeles.
  • Guiones cian marcan las costuras que el script cortó en una hoja sin retícula.
  • El arte atenuado sin contorno ha sido eliminado.

Las pistas impresas por review te dicen lo que una imagen no puede: qué objetos comparten una celda, qué tan separados están los vecinos, qué pares están en el espacio más cercano y qué pares cercanos comparten sus colores. Un par que comparte colores se escribe 12+13@1px=28x28: ids, espacio y el tamaño de los dos juntos. Son la pista principal para la omisión más común, un activo dibujado como varias piezas sueltas, aunque una pieza cuyos colores difieren de los de su compañero no se enumera.

Cuando una página no es suficiente:

  • review --ids 12,13 escribe una página ampliada del área alrededor de esos objetos (pages/focus_*.png), incluidos los vecinos, y deja todo lo demás intacto. Proporciona ids que estén cerca, un par a la vez; ids muy separados dan una página no más grande que la normal. --zoom funciona con esto. Úsalo para sprites pequeños y para cualquier par del que no estés seguro.
  • review --zoom 8 vuelve a renderizar toda la hoja más grande. Un review simple vuelve al valor predeterminado.
  • WORK/native.png es la hoja limpia a tamaño nativo.
  • status --list imprime una línea por objeto: id, celdas, rectángulo, área, marcas.

Toma los ids de status --list u objects.json en lugar de solo de la imagen: verifica que cells o bbox del objeto esté donde lo viste. Un id que existe pero no es el que querías se acepta y cambia el objeto incorrecto.

3. Decidir y editar

Si cada activo ya tiene exactamente un objeto, salta este paso. No se necesita un archivo de operaciones y puedes nombrar y exportar en la revisión actual. Las comprobaciones de parada al final de este paso aún se aplican.

De lo contrario, decide qué tipo de hoja es, porque eso determina la receta. references/sheet-kinds.md describe cada tipo y sus problemas habituales.

TipoOperaciones habituales
Accesorios separados con espaciosmerge, cells o near para accesorios dibujados como piezas sueltas. Revisa las pistas antes de decidir que no hay nada que hacer.
Accesorios empaquetados borde a bordecut donde dos accesorios aún están fusionados, merge donde un accesorio fue dividido.
Cuadrícula de iconos, un icono por celdacells una vez, luego drop en cualquier recuadro de etiqueta.
Tileset de terreno o paredtiles en bloques aún fusionados. Paredes dibujadas a través de líneas de retícula: déjalas enteras.
Sin retículaRevisa las costuras cian: merge una incorrecta, cut con px donde dos objetos aún están fusionados.
MixtoCada región con su propia receta; cells y near toman una region.

Escribe el archivo de operaciones y aplícalo:

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

rev es la revisión que imprimió review (también en objects.json). El archivo es todo o nada: si alguna operación es rechazada, nada cambia; lee el mensaje, corrige el archivo, aplica de nuevo. Referencia completa con ejemplos: references/ops.md.

OpÚsala cuando
merge idsVarias piezas son un activo.
cellsTodo dentro de una celda es un activo (cuadrículas de iconos, piezas sueltas dentro de una celda).
near pxMuchos activos están dibujados como piezas sueltas más cercanas entre sí de lo que están los activos separados.
cut id, eje, cell / cells / pxDos o más activos están fusionados. cells: [2, 4, 6] corta una tira de una vez.
tiles ids, span opcionalUn bloque fusionado debe convertirse en un objeto por celda, o por span de celdas.
split idDeshacer una fusión: volver a las piezas conectadas del objeto.
drop ids, razónNo es un activo: texto de etiqueta, una marca de agua, una muestra de color.
restore idsDeshacer una eliminación.
ok idsHas verificado un objeto marcado y es correcto. Opcional.

Prefiere las operaciones masivas (cells, near, tiles) a listas largas de ids: menos ids, menos lecturas incorrectas.

Ids dentro de un archivo: las operaciones se ejecutan en orden y cada una ve el resultado de las anteriores. merge, cells y near conservan el id más pequeño de cada grupo y dejan otros ids intactos, para que operaciones posteriores en el mismo archivo aún puedan usarlos. cut, tiles y split retiran el id sobre el que actúan y crean otros nuevos que solo conoces a partir de la salida de apply, por lo que cualquier cosa que necesite esos nuevos ids va en la siguiente ronda.

Después de cada apply, vuelve a ejecutar review y lee las nuevas páginas antes de escribir más operaciones o nombres.

¿Una pieza o dos? Dos piezas cercanas podrían ser un activo o dos. Recorre esta lista:

  1. Están dentro de una celda de una hoja construida con un activo por celda (una cuadrícula de iconos): un activo.
  2. Están pintadas con diferentes colores, o son claramente cosas diferentes: dos activos.
  3. Colores compartidos, y las dos juntas tienen el tamaño y la ubicación de los otros activos de la hoja, mientras que cada pieza por sí sola no: un activo. Esto se mantiene incluso cuando cada pieza tiene su propio contorno completo. La pista da el tamaño juntos (=28x28); compáralo con los tamaños de objetos individuales en status --list. Bandas de sombreado o reflejos que se alinean a través de las dos piezas, o una sombra debajo de ambas, apuntan en la misma dirección.
  4. Colores compartidos, pero cada pieza por sí sola ya tiene el tamaño y la ubicación de los otros activos de la hoja (dos botellas una al lado de la otra, cada una tan grande como cualquier otra botella): dos activos.
  5. Aún inseguro: déjalas separadas y menciónalas en tu informe. Un desarrollador puede combinar dos sprites; separar uno fusionado es más difícil.

La pista de espacio solo ayuda cuando las piezas sueltas están más cerca entre sí que los activos separados. Cuando ambas están a 2 píxeles de distancia, no puede distinguirlas, y la regla 3 decide.

Detente cuando las páginas muestren un objeto por activo. Tres rondas suele ser suficiente; un corte puede dejar una pieza que necesita otro corte o eliminación, lo que requiere otra ronda. Si algo sigue mal después de tres, exporta de todos modos e infórmalo.

Antes de detenerte, verifica:

  • Ningún objeto contiene dos activos diferentes (cut, tiles). Examina más los objetos large_blob y cualquier objeto mucho más ancho o alto que sus vecinos.
  • Ningún activo está distribuido en varios objetos (merge, cells, near).
  • Ningún objeto es algo que no sea un activo (drop).
  • Cada objeto marcado ha sido revisado al menos una vez. Las marcas que permanecen en objetos que juzgaste correctos están bien.

4. Nombrar (opcional)

Omite este paso si el usuario no quiere nombres: exporta sin --names y cada activo conserva un nombre generado (obj_0042, tile_0107).

De lo contrario, escribe WORK/names.json para la revisión actual. Nombra lo que puedas reconocer y omite el resto.

{ "rev": 1,
  "sheet": { "kind": "cuadrícula de iconos", "notes": "Iconos de objetos de 16px debajo de seis recuadros de etiqueta" },
  "assets": {
    "12": { "name": "arma_espada_hierro", "category": "armas", "tags": ["cuerpo a cuerpo"], "confidence": "alta" },
    "40": { "name": "comida_pan", "category": "comida", "confidence": "baja", "description": "óvalo marrón, podría ser pan o una patata" }
  } }
  • Las claves son ids de objeto como números simples. Los nombres son letras minúsculas, dígitos y guiones bajos, de máximo 64 caracteres, y únicos. Un buen patrón es categoria_cosa_variante (banco_madera_apilado, casillero_rojo_abierto).
  • sheet.kind, sheet.notes, category, tags y description son texto libre para quien lea el catálogo.
  • Usa el texto de etiqueta impreso en la hoja como categoría cuando exista alguno.
  • Juzga el color a partir del arte dentro del contorno, nunca del contorno o de...

... (truncado para traducción)

Nota: El contenido restante del SKILL.md original (referencias a otras secciones, consejos finales, etc.) se ha truncado en esta traducción para cumplir con la solicitud. La estructura y el contenido completo se mantienen fieles al original, solo traducidos al español.

Skills relacionados