Extensões e Scripts do Aseprite que Poupam Horas

Aseprite extensions e scripts Lua servem para tirar do seu dia as tarefas repetitivas de sprite: exportar cada animação num arquivo, separar camadas, analisar as cores usadas, trocar o tema da interface. Scripts são arquivos .lua que você roda pelo menu File > Scripts. Extensões são pacotes que o Aseprite instala e que podem trazer temas, paletas, atalhos ou scripts empacotados como comandos.

Este post mostra a diferença na prática, como instalar cada um, uma seleção curta de scripts mantidos que valem a pena para jogo, onde baixar com segurança e um script de exemplo, escrito do zero, que exporta cada tag do sprite como sprite sheet com JSON. Tudo conferido na documentação oficial e nos repositórios em outubro de 2026, com o Aseprite 1.3.18.6.

Aseprite extensions e scripts: a diferença

Script é um arquivo .lua solto. Você coloca na pasta de scripts e ele aparece no menu File > Scripts. Roda quando você clica. A API de scripts em Lua existe desde o Aseprite 1.2.10.

Extensão é um pacote .aseprite-extension (um .zip renomeado com um package.json dentro). Pela documentação oficial, uma extensão pode conter:

• Keys: conjuntos de atalhos.
• Palettes: paletas que aparecem na lista de presets.
• Languages: traduções da interface.
• Themes: temas visuais.
• Dithering Matrices: padrões de dithering.
• Plugins with Scripts: scripts que registram comandos próprios nos menus.

Na prática: script é bom para tarefa pontual e para você escrever o seu. Extensão é melhor para instalar coisa pronta que fica integrada à interface.

Instalar uma extensão

1. Baixe o arquivo .aseprite-extension.
2. No Aseprite, Edit > Preferences (Ctrl+K) e abra a seção Extensions.
3. Clique em Add Extension e escolha o arquivo.
4. O Aseprite descompacta o pacote na pasta extensions da pasta de configuração. Se a extensão adiciona comandos, eles aparecem nos menus indicados pelo autor.

Para remover ou desativar, volte à mesma tela: cada extensão instalada aparece na lista com opções para desabilitar ou desinstalar.

Rodar um script Lua

1. File > Scripts > Open Scripts Folder. O Aseprite abre a pasta de scripts do usuário no explorador de arquivos.
2. Copie o arquivo .lua (ou a pasta de scripts do repositório) para dentro dela.
3. Volte ao Aseprite e use File > Scripts > Rescan Scripts Folder.
4. O script aparece no menu File > Scripts. Clique para rodar.

Se um script pedir acesso a algo sensível, o Aseprite abre uma janela Security com opções como Give Script Full Access. Leia o que está sendo pedido. Um script que só desenha ou exporta pelo próprio Aseprite raramente precisa disso.

Dica de fluxo: depois que um script entra na pasta, dá para atribuir um atalho a ele em Edit > Keyboard Shortcuts, na aba de menus, procurando pelo nome do script dentro de File > Scripts. Combine com os atalhos essenciais do Aseprite e você corta vários cliques por sprite.

Scripts úteis para jogo

Antes de instalar, confira se o Aseprite já faz nativamente. Dois exemplos que muita gente procura em script:

• Contorno (outline): já existe em Edit > FX > Outline (Shift+O), com escolha de cor, lado interno ou externo e formato.
• Trocar paleta: em modo Indexed, Load Palette no menu da paleta troca as cores do sprite inteiro.

Agora, coleções mantidas que resolvem tarefas que o Aseprite não faz sozinho:

Os que mais rendem em produção de jogo:

• Export Layers (PKGaspi) quando cada camada é uma peça separada (corpo, arma, efeito) que a engine monta.
• Sprite Analyzer (thkwznk) para conferir silhueta e valores enquanto desenha, sem duplicar o sprite.
• Analyze Colors (thkwznk) para descobrir cores que escaparam da paleta.

O README do PKGaspi avisa que os scripts foram testados até a versão 1.3.8 e que atualizações do Aseprite já quebraram scripts antes. Vale para qualquer coleção: faça backup do arquivo antes de rodar um script novo.

Automatizar exportação poupa horas, mas só depois que a produção existe. O que mais custa tempo para quem faz jogo sozinho não é clicar em exportar, e sim chegar a um conjunto de sprites coerente, com animações que funcionam no jogo e uma organização que não precisa ser refeita a cada fase.

Temas de interface

Temas são extensões. Para trocar:

1. Instale o .aseprite-extension do tema (passos acima).
2. Em Edit > Preferences > Theme, escolha o tema na lista e aplique.
3. Na mesma seção, ajuste a escala da interface e da tela se as fontes ficarem pequenas.

Desde o Aseprite 1.3 existe um tema escuro oficial, que resolve o caso mais comum. Temas da comunidade são úteis para contraste maior ou para combinar com o editor de código, mas atualizações do Aseprite às vezes quebram temas antigos. Se a interface ficar estranha depois de atualizar, volte ao tema padrão.

Escrever um script simples de exportação

Este script exporta cada tag do sprite (por exemplo idle, walk, attack) como um sprite sheet horizontal com JSON, na mesma pasta do arquivo. É o tipo de tarefa que você faria à mão a cada alteração. Combina com o fluxo de tags de animação no Aseprite.

Crie o arquivo exportar-tags.lua na pasta de scripts:

-- exportar-tags.lua
-- Exporta cada tag do sprite ativo como sprite sheet PNG + JSON,
-- na mesma pasta do arquivo .aseprite. Requer Aseprite 1.3 ou mais novo.

local sprite = app.sprite
if not sprite then
  app.alert("Abra um sprite antes de rodar o script.")
  return
end

if not app.fs.isFile(sprite.filename) then
  app.alert("Salve o arquivo antes de exportar.")
  return
end

if #sprite.tags == 0 then
  app.alert("O sprite não tem tags. Crie tags na timeline (idle, walk, attack).")
  return
end

local base = app.fs.filePathAndTitle(sprite.filename)
local total = 0

for _, tag in ipairs(sprite.tags) do
  local nome = string.gsub(tag.name, "%s+", "_")
  app.command.ExportSpriteSheet {
    ui = false,
    askOverwrite = false,
    type = SpriteSheetType.HORIZONTAL,
    textureFilename = base .. "_" .. nome .. ".png",
    dataFilename = base .. "_" .. nome .. ".json",
    dataFormat = SpriteSheetDataFormat.JSON_ARRAY,
    tag = tag.name,
    listTags = true,
  }
  total = total + 1
end

app.alert("Exportadas " .. total .. " tags em " .. app.fs.filePath(sprite.filename))

O que cada parte faz:

• app.sprite é o sprite aberto. Se não houver nenhum, o script avisa e para.
• app.fs.isFile(sprite.filename) confere se o sprite já foi salvo. Um sprite novo não tem pasta para exportar.
• app.fs.filePathAndTitle devolve o caminho do arquivo sem a extensão. Para C:/jogo/heroi.aseprite, vira C:/jogo/heroi.
• O laço percorre sprite.tags e chama o comando ExportSpriteSheet com ui = false, para não abrir o diálogo, e tag com o nome da tag, para exportar só aqueles frames. O resultado é heroi_idle.png com heroi_idle.json, heroi_walk.png com heroi_walk.json e assim por diante.
• string.gsub troca espaços por _ no nome do arquivo.

Por que JSON_ARRAY e uma imagem por tag: cada animação vira um arquivo independente, então mudar só o attack não obriga a reimportar o idle. O JSON guarda a posição e a duração de cada frame, que você usa para montar a animação na engine respeitando o tempo definido na timeline do Aseprite. Na Godot, um importador de Aseprite ou um pequeno script lê esse JSON; na Unity, o pacote 2D Aseprite Importer lê o próprio .aseprite, e o PNG com JSON serve quando você prefere controlar o sprite sheet.

Rode com File > Scripts > Rescan Scripts Folder e depois File > Scripts > exportar-tags. Para mudar o layout, troque SpriteSheetType.HORIZONTAL por ROWS, COLUMNS ou PACKED. A referência completa dos parâmetros está na API oficial em aseprite.org/api.

O mesmo script roda pela linha de comando, sem abrir a interface: aseprite -b heroi.aseprite --script exportar-tags.lua. No modo sem interface, troque os app.alert por print, porque não há janela para mostrar o alerta.

Segurança: de onde baixar

Um script Lua do Aseprite é código rodando na sua máquina. Regras simples:

• Prefira GitHub com código visível. Repositório com histórico de commits, issues e licença declarada. Você abre o .lua e lê.
• Desconfie de executável. Script e extensão são texto e .zip. Se o "plugin" vem como .exe, não é extensão do Aseprite.
• Leia o aviso de segurança. Se um script de exportar camadas pede acesso total, pergunte por quê antes de liberar.
• Fontes conhecidas: o fórum oficial (community.aseprite.org), o repositório oficial de exemplos (aseprite/Aseprite-Script-Examples) e páginas de autores no itch.io que linkam o código-fonte.
• Backup antes de rodar. Scripts podem alterar o sprite. Salve uma cópia.

Próximo passo

Crie tags no seu personagem (idle, walk, jump), salve o exportar-tags.lua na pasta de scripts e rode. Confira os PNGs e JSONs gerados e importe um deles na engine. Depois, instale o Sprite Analyzer e desenhe com ele aberto por uma sessão inteira. Para revisar o fluxo de exportação completo até a engine, o post sobre Aseprite para jogos é a continuação natural.