Exportar Sprite Sheet do Aseprite para a Godot

Você desenhou o personagem, animou a caminhada com onion skin e agora precisa ver aquilo se mexendo dentro do jogo. Esse é o passo que trava mais gente do que devia. Exportar sprite sheet do Aseprite para a Godot é um caminho curto quando você sabe quais três ou quatro opções marcar, e um pesadelo de frames cortados e animação borrada quando você marca no chute. Este guia cobre o fluxo inteiro: o diálogo Export Sprite Sheet, quando o JSON importa, e como montar o SpriteFrames num AnimatedSprite2D na Godot 4, pela grade ou por código.

A ideia central é simples: o Aseprite gera uma imagem PNG com todos os frames lado a lado, opcionalmente um arquivo JSON descrevendo onde cada frame está, e a Godot lê isso. O que atrapalha são os detalhes: tipo de layout, espaçamento entre frames, filtro de textura. Vamos um por um. Se você ainda está montando o fluxo de arte antes desta etapa, vale começar pelo guia de Aseprite para jogos, que cobre desde o desenho do sprite até a exportação.

O diálogo Export Sprite Sheet

No Aseprite, com o arquivo aberto e as animações já separadas em tags, vá em File > Export Sprite Sheet. A janela tem várias abas, e a maioria das opções você deixa no padrão. As que importam ficam em três lugares.

Antes de exportar, um lembrete que economiza retrabalho: se você ainda não organizou suas animações em tags nem usou o onion skin no Aseprite pra deixar a caminhada fluida, faça isso primeiro. Tag mal nomeada vira animação mal nomeada na engine, e você vai renomear tudo na mão depois.

Aba Layout: o tipo de arranjo dos frames

Na aba Layout, o campo Sheet Type define como os frames se organizam na imagem. As três opções que você vai encontrar:

• Horizontal Strip: todos os frames numa única linha, um do lado do outro. Simples e previsível. Bom pra uma animação só, ou pra quem vai fatiar por grade e não liga pra imagem ficar larga.
• By Rows: frames organizados em linhas, com uma animação embaixo da outra quando você combina com tags. É o mais usado pra personagem com várias animações, porque o resultado tem cara de grade regular e a Godot lê fácil.
• Packed: o Aseprite espreme todos os frames no menor retângulo possível, encaixando uns nos espaços vazios dos outros. Economiza textura, mas destrói a previsibilidade: a posição de cada frame vira arbitrária. Com Packed, o JSON deixa de ser opcional e passa a ser obrigatório, porque é a única forma de saber onde cada frame ficou.

Pra começar, use By Rows. Ele dá a grade regular que a importação por grade da Godot espera, e você não precisa mexer com JSON no primeiro projeto.

Ainda na aba Layout, ligue Border Padding e Spacing com 1 ou 2 pixels. Esse respiro entre os frames evita um bug clássico: a engine renderiza uma fatia de 1 pixel do frame vizinho na borda do sprite, o famoso texture bleeding. Dois pixels de espaçamento resolvem isso de vez.

Aba Sprite: separar por tag ou por camada

Na aba Sprite, o campo Split by decide o que vira frame separado. As opções relevantes:

• Split by Tag (ou marcar Tags como fonte do layout): cada tag de animação vira um bloco de frames no sheet. É o que você quer na maioria dos casos, porque mantém idle, run, jump e attack agrupadas e nomeadas.
• Split by Layers: cada camada vira uma linha própria. Útil quando você exporta partes separadas do personagem (corpo, arma, capa) pra recompor na engine, mas não é o fluxo padrão.

Pra um personagem comum com animações em tags, deixe o Aseprite considerar as tags e mantenha as camadas achatadas numa imagem só.

Aba Output: PNG mais JSON com Array

A aba Output é onde você define os arquivos que saem. Marque:

• Output File: o PNG do sprite sheet. Escolha o caminho, de preferência já dentro da pasta do seu projeto Godot.
• JSON Data: marque essa caixa se a engine ou um script for consumir os metadados. No dropdown ao lado, escolha Array em vez de Hash. O formato Array entrega os frames numa lista ordenada, que é mais direta de percorrer em código do que o formato Hash, indexado por nome.
• Meta > Tags: dentro das opções de meta do JSON, marque Tags pra incluir os nomes das animações e o intervalo de frames de cada uma. Sem isso, o JSON sabe onde os frames estão mas não sabe que run vai do frame 4 ao 9.

Se o seu sheet é uma grade regular exportada por By Rows e você vai fatiar pela grade na Godot, o JSON é dispensável. Marque-o quando usar Packed ou quando um script for ler as tags automaticamente.

Trazendo o PNG pra dentro da Godot

Copie o PNG (e o JSON, se exportou) pra dentro da pasta do projeto Godot. Assim que o arquivo aparece no painel FileSystem, a engine importa a textura sozinha. Antes de montar qualquer animação, resolva o filtro de textura, senão a pixel art vai chegar borrada.

A Godot 4 aplica filtro linear por padrão, que suaviza a imagem e transforma pixel art nítida numa papa. Vá em Project Settings > Rendering > Textures e mude o Default Texture Filter para Nearest. Isso corrige o projeto inteiro de uma vez, sem precisar ajustar textura por textura.

Feito isso, adicione um nó AnimatedSprite2D na sua cena. No Inspector dele, o campo Sprite Frames começa vazio. Clique nele e escolha New SpriteFrames. Um painel de edição do SpriteFrames abre na parte de baixo da tela. É aqui que o sprite sheet vira animação.

Montando o SpriteFrames pela grade

Com o painel SpriteFrames aberto, procure o botão Add frames from sprite sheet, o ícone de grade na barrinha de ferramentas do painel. Ele abre um diálogo que pede a textura do sheet.

Selecione o PNG que você importou. O diálogo mostra a imagem com uma grade sobreposta e alguns campos pra configurar:

• Horizontal e Vertical: quantas colunas e quantas linhas o sheet tem. Se você exportou 6 frames numa linha, é 6 horizontais e 1 vertical. Ajuste até a grade cair exatamente em cima de cada frame.
• Size: o tamanho de cada célula em pixels. A Godot costuma calcular sozinho a partir das divisões, mas confira se bate com o tamanho real do frame.
• Separation e Offset: se você exportou com Border Padding e Spacing, informe aqui o mesmo espaçamento que usou no Aseprite. É isso que faz a grade pular o respiro entre frames em vez de cortar a imagem no lugar errado.

Com a grade certa, selecione os frames que compõem a animação (clique e arraste sobre eles) e confirme em Add Frames. Eles entram na animação atual do SpriteFrames. Renomeie a animação de default pra walk, idle ou o nome que a tag tinha no Aseprite, e crie novas animações com o botão de adicionar pra repetir o processo com os outros blocos de frames. Ajuste o FPS de cada animação e marque Loop nas que devem repetir, como a caminhada e o idle.

Se você exportou com Packed ou quer fidelidade total às tags, o caminho pela grade fica trabalhoso, e aí compensa usar um plugin da Asset Library que lê o .aseprite ou o JSON e monta o SpriteFrames com as animações já separadas. Vale procurar quando o fluxo manual começar a cansar.

Tocando a animação por código

Montado o SpriteFrames, tocar uma animação é uma linha. Anexe um script ao nó AnimatedSprite2D e chame play com o nome da animação. Em GDScript 4 tipado:

extends AnimatedSprite2D

func _ready() -> void:
    play("walk")

O _ready roda quando o nó entra na cena, e play("walk") dispara a animação de nome walk. Se você marcou Loop nela no editor, ela repete sozinha. Pra trocar de animação em resposta ao jogador, o padrão é chamar play com o nome novo quando o estado muda, por exemplo play("jump") quando o personagem pula e play("idle") quando ele para. A Godot só reinicia a animação se o nome for diferente do que já está tocando, então pode chamar à vontade dentro do _process sem medo de travar o loop.

Um detalhe que confunde iniciante: play toca pra frente por padrão, mas existe play_backwards pra rodar ao contrário, útil pra reaproveitar uma animação de abrir como animação de fechar sem redesenhar frame nenhum.

Erros comuns que valem checar

Três problemas concentram quase todas as dúvidas de quem está exportando pela primeira vez.

Frame cortado ou fatia do vizinho aparecendo. Quase sempre é espaçamento. Ou você exportou com padding no Aseprite e não informou o Separation na Godot, ou o contrário. Os dois lados precisam concordar sobre quantos pixels de respiro existem entre os frames.

Animação borrada mesmo com Nearest ligado. Confira se você mudou o Default Texture Filter global e não só de uma textura. Se a textura foi importada antes da mudança, clique nela no FileSystem, vá na aba Import e force o filtro Nearest ali também, depois reimporte.

Animação toca rápido demais ou devagar demais. O FPS do SpriteFrames na Godot é independente da duração que você definiu nos frames do Aseprite. Ajuste o FPS de cada animação no painel até o ritmo bater com o que você animou.

Fechando

O fluxo é sempre o mesmo: no Aseprite, Export Sprite Sheet com layout By Rows, padding de 1 ou 2 pixels, e JSON com Array e Tags marcado só quando um script ou o modo Packed exigem. Na Godot, filtro Nearest no projeto, AnimatedSprite2D com um novo SpriteFrames, frames adicionados pela grade com o Separation certo, e play("nome") no _ready. Quando você faz isso duas ou três vezes, vira reflexo.

Vale lembrar que esse conforto de importar pixel art com poucos cliques é um dos motivos pelos quais a Godot brilha em 2D. Se você ainda está decidindo engine, a Godot vs Unity: comparação completa entra nesse e em outros pontos práticos. Mas se o seu jogo é 2D e a arte é pixel, o par Aseprite mais Godot resolve do desenho ao jogo sem atrito. Abra seu personagem, exporte o sheet e coloque ele pra andar na tela hoje.