Cortador de folha de sprites
O script é dono dos pixels e você é dono do significado.
scripts/sheet.jsencontra 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 (
cutcompx) é 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
- 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
detectereview, diga a eles onde estáWORK/pagese deixe-os olhar e escrever o arquivo de ops. Não abra as páginas,native.pngou qualquer sprite. Você ainda pode executarapply,review,statuseexportpara eles e ler o texto que esses imprimem.
- 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--tilede fora; o script então tenta inferir um tamanho e informa. - Uma folha, uma pasta de trabalho. Executar
detectnovamente 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:
| Imprime | Faça isto |
|---|---|
kind: scene_or_single_object | Muito 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: none | Uma 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: none | Sem 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,13escreve 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.--zoomfunciona com isso. Use para sprites pequenos e para qualquer par sobre o qual você não tem certeza.review --zoom 8re-renderiza a folha inteira maior. Umreviewsimples volta ao padrão.WORK/native.pngé a folha limpa em tamanho nativo.status --listimprime 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.
| Tipo | Ops usuais |
|---|---|
| Props separados com lacunas | merge, 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 borda | cut onde dois props ainda estão fundidos, merge onde um prop foi dividido. |
| Grade de ícones, um ícone por célula | cells uma vez, depois drop em quaisquer caixas de rótulo. |
| Tileset de terreno ou parede | tiles em blocos ainda fundidos. Paredes desenhadas através de linhas de lattice: deixe inteiras. |
| Sem lattice | Verifique as costuras ciano: merge uma errada, cut com px onde dois objetos ainda estão fundidos. |
| Misto | Cada 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.
| Op | Use quando |
|---|---|
merge ids | Várias peças são um asset. |
cells | Tudo dentro de uma célula é um asset (grades de ícones, peças soltas dentro de uma célula). |
near px | Muitos assets são desenhados como peças soltas mais próximas do que assets separados estão. |
cut id, axis, cell / cells / px | Dois ou mais assets estão fundidos. cells: [2, 4, 6] corta uma tira de uma vez. |
tiles ids, span opcional | Um bloco fundido deve se tornar um objeto por célula, ou por span de células. |
split id | Desfazer uma mesclagem: de volta às peças conectadas do objeto. |
drop ids, reason | Não é um asset: texto de rótulo, marca d'água, amostra de cor. |
restore ids | Desfazer um drop. |
ok ids | Você 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:
- 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.
- Elas são pintadas com cores diferentes, ou são claramente coisas diferentes: dois assets.
- 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 emstatus --list. Bandas de sombreamento ou realces que se alinham entre as duas peças, ou uma sombra sob ambas, apontam no mesmo sentido. - 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.
- 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 objetoslarge_blobe 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,tagsedescriptionsã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]