CommunityImagemgithub.com

sprite-sheet-slicer

Recorta uma folha de sprites de arte de jogo, tileset ou folha de ícones (PNG) em uma imagem por asset e escreve um catálogo que nomeia cada asset e registra seu tamanho em tiles e sua origem.

O que é sprite-sheet-slicer?

Esta skill automatiza a tarefa de separar múltiplos assets de jogos empacotados em uma única imagem PNG, como folhas de sprites, tilesets ou folhas de ícones. Ela detecta objetos na imagem, permite revisão visual com páginas numeradas e suporta operações de edição como mesclar, cortar e nomear assets. A skill é ideal para desenvolvedores de jogos que precisam dividir asset packs irregulares ou edge-to-edge em sprites individuais, com suporte para grade de tiles, cortes baseados em posição de pixel e operações em lote. Funciona principalmente com Claude Code (que preenche automaticamente o caminho da skill) e outros agentes como Codex (que exigem substituição manual do placeholder). Utiliza Node.js e nenhuma instalação adicional, exigindo apenas que o PNG de entrada seja fornecido. O fluxo de trabalho inclui detecção de objetos, revisão visual, aplicação de operações de edição e exportação com ou sem nomes personalizados.

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

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Cortador de folha de sprites

O script é dono dos pixels e você é dono do significado.

  • scripts/sheet.js encontra todos os objetos, sabe exatamente a qual pertence cada pixel e desenha páginas de revisão numeradas.
  • Você olha as páginas, decide o que conta como um asset e diz isso com pequenas operações de edição que nomeiam objetos pelo id e lugares pela régua impressa na página.
  • Você nunca estima onde está a borda de um sprite. Uma posição lida de uma imagem é aproximada, então a única posição livre que o script aceita (cut com px) é movida para a costura mais forte em até 3 pixels.

Palavras usadas aqui: um objeto é uma região que o script encontrou e numerou. Um asset é o que o jogo precisa: um cenário, um ícone, um tile. O trabalho é fazer todo objeto ser exatamente um asset. Uma célula é um quadrado da grade de tiles da folha.

Requer Node no PATH (node --version). Nada para instalar. A entrada deve ser PNG.

Os comandos são executados como node "${CLAUDE_SKILL_DIR}/scripts/sheet.js" <comando> ..., com caminhos entre aspas; --help lista todos os comandos e opções. O Claude Code preenche a pasta da skill nesses comandos. Se você vir um placeholder começando com ${CLAUDE_ em vez de um caminho real (Codex e outros agentes), coloque a pasta que contém este SKILL.md em seu lugar. Escolha uma pasta de trabalho por folha (WORK) e uma pasta de saída nova e vazia (OUT), ambas fora da pasta da skill. Escreva arquivos de ops e nomes com sua ferramenta de escrita de arquivos (Write no Claude Code, apply_patch no Codex), que salva UTF-8; um arquivo UTF-16 de um redirecionamento do PowerShell é recusado.

Lista de progresso para copiar e marcar:

[ ] licença verificada     [ ] tamanho do tile encontrado
[ ] detect: avisos lidos
[ ] review: páginas lidas, tipo de folha decidido
[ ] apply (rodada 1)     [ ] revisar novamente
[ ] nomes (se desejado)   [ ] export: cobertura completa
[ ] relatório

Antes de começar

  1. Verifique a licença. Se o usuário forneceu uma página de loja ou um readme, leia seu texto de licença. Se restringir o uso de IA ("sem IA", "não para treinamento de IA", "não pode ser alimentado para IA"), pare e pergunte ao usuário como proceder.
    • Se eles disserem para continuar, siga com o fluxo de trabalho normal e mencione em seu relatório que eles tomaram essa decisão.
    • Se eles quiserem que a arte seja mantida longe da IA: execute detect e review, diga a eles onde está WORK/pages e deixe-os olhar e escrever o arquivo de ops. Não abra as páginas, native.png ou qualquer sprite. Você ainda pode executar apply, review, status e export para eles e ler o texto que esses imprimem.
  2. Encontre o tamanho do tile. Descrições de pacotes geralmente o informam ("tiles 16x16", "estilo 32x32 alinhado a uma grade 16"). Passe como --tile N. É mais importante em arte sem contornos: em folhas de teste sintéticas de terreno sem contorno e props com sombra plana, o script cortou cerca de 90% dos assets corretamente com o tamanho do tile e menos de 40% sem. Se a descrição disser que não há grade, passe --tile none. Se não disser nada, deixe --tile de fora; o script então tenta inferir um tamanho e informa.
  3. Uma folha, uma pasta de trabalho. Executar detect novamente em uma pasta de trabalho recomeça aquela folha.

Fluxo de trabalho

1. Detect

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

Isso imprime o fundo encontrado, o estilo de arte (com contorno ou plano; informativo), o tamanho do tile, o número de objetos e linhas de WARNING e note. Aja sobre eles:

ImprimeFaça isto
kind: scene_or_single_objectMuito poucos objetos, e um contém a maior parte da arte. Leia a imagem. Se for uma cena de maquete (objetos sobrepostos, em pé no chão), diga ao usuário que não pode ser cortada em assets limpos e pare. Se for um ou alguns sprites grandes, continue.
background: noneUma imagem opaca cujo fundo não foi reconhecido. Leia a imagem, encontre a cor de fundo, execute novamente com --bg rrggbb (separe por vírgula as cores de um tabuleiro de xadrez assado).
"a cor de fundo também ocorre dentro da arte"As bordas do sprite podem estar danificadas. Diga ao usuário que uma fonte transparente seria mais segura; continue.
"região(ões) fechada(s) de cor de fundo foram removidas"Normal em folhas empacotadas. Se os sprites mostrarem buracos nas páginas, execute novamente com --pockets large ou --pockets keep.
"lido como uma ampliação xN"A imagem era uma prévia ampliada e foi reduzida. --tile e todas as posições estão em pixels nativos. Se a imagem não for uma ampliação, execute novamente com --scale 1.
tile: 16px (inferido)Um palpite de como os objetos se alinham. Se o pacote não tiver grade, execute novamente com --tile none; se informar um tamanho, passe-o.
tile: noneSem lattice. As ops cells e tiles não estão disponíveis e cut usa px.
"speck(s) ... foram mesclados ao objeto próximo a eles"Geralmente pixels perdidos. Se o pacote tiver sprites reais com menos de seis pixels, veja split na referência de ops.
"pixel(is) quase invisível(is) ... tratado(s) como transparente"Nada a fazer.

2. Review

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

Isso escreve WORK/pages/*.png e WORK/objects.json e imprime dicas. Abra as páginas com sua ferramenta de visualização de imagens (Read no Claude Code, view_image no Codex): todas quando houver oito ou menos; caso contrário, aquelas que listam objetos sinalizados primeiro, depois uma amostra do resto. As páginas se sobrepõem um pouco, então um objeto próximo a uma borda de página aparece em duas páginas com o mesmo id. Uma folha que cabe é desenhada em uma página; uma folha com mais de 600 objetos obtém apenas as páginas com objetos sinalizados (ou uma amostra quando nada é sinalizado).

Lendo uma página:

  • A arte é mostrada em suas cores verdadeiras sobre um tabuleiro de xadrez escuro. Cada objeto tem um contorno colorido ao longo da borda exata de seus pixels e um número na mesma cor. O número é o id. Ele fica dentro de objetos grandes e ao lado de objetos pequenos. Um objeto feito de peças separadas tem um número e um contorno da mesma cor ao redor de cada peça.
  • Os números ao longo do topo e da esquerda são a régua: índices de célula em uma folha com tamanho de tile (célula 3 começa no pixel 3 x tile), posições de pixel caso contrário.
  • Uma caixa dupla branca marca um objeto sinalizado. Sinalizações são lembretes para olhar, não erros:
    • shares_cell: vários objetos dentro de uma célula.
    • close_same_colours: outro objeto compartilhando suas cores está a 2 pixels ou menos de distância.
    • doubtful_border: o objeto toca uma borda do lattice (barra magenta) onde a escolha de cortar ou juntar foi próxima. Sprites diagonais finos cruzando uma linha de grade geralmente têm isso e estão bem.
    • exposed_fill: o preenchimento do objeto está diretamente contra outro objeto sem contorno entre eles: um corte errado, ou dois assets sem contorno entre eles.
    • large_blob: muito maior que os outros objetos. Frequentemente vários assets fundidos.
    • speck: menos de seis pixels.
  • Traços ciano marcam costuras que o script cortou em uma folha sem lattice.
  • Arte escurecida sem contorno foi descartada.

As dicas impressas por review dizem o que uma imagem não pode: quais objetos compartilham uma célula, a que distância os vizinhos estão, quais pares estão na menor distância e quais pares próximos compartilham suas cores. Um par que compartilha cores é escrito 12+13@1px=28x28: ids, distância e o tamanho dos dois juntos. Eles são a principal pista para o erro mais comum, um asset desenhado como várias peças soltas, embora uma peça cujas cores diferem de sua parceira não seja listada.

Quando uma página não é suficiente:

  • review --ids 12,13 escreve uma página ampliada da área ao redor desses objetos (pages/focus_*.png), vizinhos incluídos, e deixa todo o resto em paz. Dê ids que estão próximos, um par de cada vez; ids distantes dão uma página não maior que a normal. --zoom funciona com isso. Use para sprites pequenos e para qualquer par sobre o qual você não tem certeza.
  • review --zoom 8 re-renderiza a folha inteira maior. Um review simples volta ao padrão.
  • WORK/native.png é a folha limpa em tamanho nativo.
  • status --list imprime uma linha por objeto: id, células, caixa, área, sinalizações.

Pegue ids de status --list ou objects.json em vez de apenas da imagem: verifique se o cells ou bbox do objeto está onde você o viu. Um id que existe mas não é o que você pretendia é aceito e muda o objeto errado.

3. Decidir e editar

Se cada asset já tem exatamente um objeto, pule esta etapa. Nenhum arquivo de ops é necessário e você pode nomear e exportar na revisão atual. As verificações de parada no final desta etapa ainda se aplicam.

Caso contrário, decida que tipo de folha é esta, porque isso determina a receita. references/sheet-kinds.md descreve cada tipo e seus problemas usuais.

TipoOps usuais
Props separados com lacunasmerge, cells ou near para props desenhados como peças soltas. Verifique as dicas antes de decidir que não há nada a fazer.
Props compactados borda a bordacut onde dois props ainda estão fundidos, merge onde um prop foi dividido.
Grade de ícones, um ícone por célulacells uma vez, depois drop em quaisquer caixas de rótulo.
Tileset de terreno ou paredetiles em blocos ainda fundidos. Paredes desenhadas através de linhas de lattice: deixe inteiras.
Sem latticeVerifique as costuras ciano: merge uma errada, cut com px onde dois objetos ainda estão fundidos.
MistoCada região por sua própria receita; cells e near aceitam uma region.

Escreva o arquivo de ops e aplique-o:

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

rev é a revisão que review imprimiu (também em objects.json). O arquivo é tudo-ou-nada: se qualquer op for rejeitada nada muda; leia a mensagem, corrija o arquivo, aplique novamente. Referência completa com exemplos: references/ops.md.

OpUse quando
merge idsVárias peças são um asset.
cellsTudo dentro de uma célula é um asset (grades de ícones, peças soltas dentro de uma célula).
near pxMuitos assets são desenhados como peças soltas mais próximas do que assets separados estão.
cut id, axis, cell / cells / pxDois ou mais assets estão fundidos. cells: [2, 4, 6] corta uma tira de uma vez.
tiles ids, span opcionalUm bloco fundido deve se tornar um objeto por célula, ou por span de células.
split idDesfazer uma mesclagem: de volta às peças conectadas do objeto.
drop ids, reasonNão é um asset: texto de rótulo, marca d'água, amostra de cor.
restore idsDesfazer um drop.
ok idsVocê verificou um objeto sinalizado e ele está correto. Opcional.

Prefira as ops em lote (cells, near, tiles) a longas listas de ids: menos ids, menos leituras erradas.

Ids dentro de um arquivo: ops são executadas em ordem e cada uma vê o resultado das anteriores. merge, cells e near mantêm o menor id de cada grupo e deixam outros ids em paz, então ops posteriores no mesmo arquivo ainda podem usá-los. cut, tiles e split aposentam o id em que atuam e criam novos que você só descobre na saída do apply, então qualquer coisa que precise desses novos ids vai na próxima rodada.

Após cada apply, execute review novamente e leia as novas páginas antes de escrever mais ops ou nomes.

Uma peça ou duas? Duas peças próximas podem ser um asset ou dois. Trabalhe nesta lista:

  1. Elas estão dentro de uma célula de uma folha construída com um asset por célula (uma grade de ícones): um asset.
  2. Elas são pintadas com cores diferentes, ou são claramente coisas diferentes: dois assets.
  3. Cores compartilhadas, e as duas juntas têm o tamanho e a colocação dos outros assets da folha enquanto cada peça sozinha não: um asset. Isso vale mesmo quando cada peça tem seu próprio contorno completo. A dica dá o tamanho junto (=28x28); compare com os tamanhos de objetos individuais em status --list. Bandas de sombreamento ou realces que se alinham entre as duas peças, ou uma sombra sob ambas, apontam no mesmo sentido.
  4. Cores compartilhadas, mas cada peça sozinha já tem o tamanho e a colocação dos outros assets da folha (duas garrafas lado a lado, cada uma tão grande quanto qualquer outra garrafa): dois assets.
  5. Ainda não tem certeza: deixe-as separadas e liste-as em seu relatório. Um desenvolvedor pode combinar dois sprites; separar um fundido é mais difícil.

A dica de distância ajuda apenas quando peças soltas estão mais próximas do que assets separados. Quando ambos estão a 2 pixels de distância, ela não pode distingui-los, e a regra 3 decide.

Pare quando as páginas mostrarem um objeto por asset. Três rodadas são normalmente suficientes; um corte pode deixar uma peça que precisa de outro corte ou drop, que leva outra rodada. Se algo ainda estiver errado após três, exporte mesmo assim e relate.

Antes de parar, verifique:

  • Nenhum objeto contém dois assets diferentes (cut, tiles). Olhe mais para objetos large_blob e para qualquer objeto muito mais largo ou alto que seus vizinhos.
  • Nenhum asset está espalhado por vários objetos (merge, cells, near).
  • Nenhum objeto é algo diferente de um asset (drop).
  • Cada objeto sinalizado foi olhado uma vez. Sinalizações que permanecem em objetos que você julgou corretos estão bem.

4. Nomear (opcional)

Pule esta etapa se o usuário não quiser nomes: exporte sem --names e cada asset mantém um nome gerado (obj_0042, tile_0107).

Caso contrário, escreva WORK/names.json para a revisão atual. Nomeie o que puder reconhecer e deixe o resto de fora.

{ "rev": 1,
  "sheet": { "kind": "grade de ícones", "notes": "ícones de item de 16px sob seis caixas de rótulo" },
  "assets": {
    "12": { "name": "weapon_sword_iron", "category": "armas", "tags": ["corpo a corpo"], "confidence": "high" },
    "40": { "name": "food_loaf", "category": "comida", "confidence": "low", "description": "oval marrom, pode ser pão ou uma batata" }
  } }
  • Chaves são ids de objetos como números simples. Nomes são letras minúsculas, dígitos e sublinhados, no máximo 64 caracteres e únicos. Um bom padrão é categoria_coisa_variante (banco_madeira_estoque, armário_vermelho_aberto).
  • sheet.kind, sheet.notes, category, tags e description são texto livre para quem ler o catálogo.
  • Use texto de rótulo impresso na folha como a categoria quando houver algum.
  • Julgue a cor pela arte dentro do contorno, nunca pelo contorno ou...

[... truncado para tradução]

Habilidades Relacionadas