Guia de scripts

Scripts são programas Lua que trabalham no sprite aberto. Eles usam o mesmo motor do editor: tudo o que você pode alterar à mão (ferramentas, camadas, quadros, cels, tags, slices, tiles e entradas da paleta), um script pode alterar com código. Use-os para gerar arte (árvores, pedras, texturas, campos de estrelas), para repetir uma edição tediosa ou para adicionar comandos seus aos menus.

Novo em scripts? Seu primeiro script mostra como escrever e executar um. Esta página cobre tudo o que está em volta.

O menu Scripts

Todos esses itens também estão na paleta de comandos (Ctrl+K).

O painel Scripts

O painel Scripts abre quando você cria ou abre um script (nos layouts padrão, acoplado à direita da tela, para que você veja o script desenhar; em um celular, na frente dela). Exibir > Painéis > Scripts o mostra e o oculta, e recarregar a página reabre o script que você tinha aberto (o último rascunho salvo). Ele tem um editor de código com realce de Lua, sugestões para toda função app. enquanto você digita e uma descrição quando você aponta para uma. Abaixo do código, uma área de saída mostra o que o script imprime e qualquer erro.

Ao longo do topo, da esquerda para a direita:

• O nome do script. Clique duas vezes nele para renomear o script. Um * significa que há alterações não salvas; ao lado dele, "rascunho" para um script que você não publicou, ou a versão que você está editando ("v2", "v2 · editado").
• Privado ou Compartilhado: quem pode ver o script na biblioteca. Clique para alterar.
• Referência da API de scripts (o livro) abre a referência em uma nova aba.
• Executar (o botão de reproduzir) executa o script no sprite ativo; um script com um formulário de configuração pede os valores antes. Enquanto ele roda, os controles de execução tomam o lugar do botão (abaixo).
• Salvar rascunho (o disquete) salva o script neste navegador.
• Publicar pede uma nota de lançamento opcional, depois salva o script e o publica como uma nova versão.
• Configurações do script (os controles deslizantes) abre as configurações do script: suas tags, quem pode vê-lo, seu formulário de configuração e suas versões publicadas.
• Ocultar painel fecha o painel. O script aberto continua listado no menu Arquivo, junto com os sprites: escolha o nome dele ali para mostrar o painel de novo.

O script de outra pessoa (aberto com Ver código na biblioteca) é somente leitura. A barra de ferramentas dele tem Fazer fork no lugar de Salvar rascunho e Publicar: isso o copia para um novo script seu, para você editar.

Executar, pausar e parar

Um script roda no sprite que você está olhando, e você o vê desenhar enquanto ele avança. Por mais que ele altere, uma execução é uma única etapa de desfazer: Ctrl+Z reverte a execução inteira.

Os scripts não têm limite de tempo. Enquanto um roda, os controles de execução permitem encerrá-lo antes:

No painel Scripts, são pequenos botões na barra de ferramentas. Um script executado a partir da biblioteca cobre o editor com uma janela que mostra o nome dele, a saída e os mesmos três controles, até terminar.

Quando um script falha, a saída mostra o erro; no painel, a linha em que ele falhou fica destacada. Um script não consegue pintar em uma camada bloqueada: o comando é recusado e o script para com um erro.

Escrever scripts

Toda função está na tabela app. A API de scripts documenta cada uma, gerada a partir do próprio editor, em seções:

• Drawing: as ferramentas como comandos (app.drawLine, app.floodFill, app.drawIsoShape...), Images para trabalhar pixel a pixel e Pixels para listas planas de pixels, preenchimentos e o conta-gotas;
• Document, Layers, Frames, Cels, Selection, Slices e Tilemaps;
• Palette, Adjustments e Brushes;
• utilitários: cálculos de Color, números Random com seed e o Editing context (as cores atuais, o pincel e as opções de ferramenta).

Algumas coisas que vale saber:

• Comece com print(app.describe()). app.describe() devolve a estrutura do sprite inteiro: camadas, quadros, cels, tags, slices, a seleção e as configurações atuais.
• As configurações que você omite vêm do editor. Um comando de desenho sem cor usa a cor de primeiro plano; sem pincel, o pincel atual; e assim por diante para cada opção de ferramenta.
• A seleção e a simetria só valem quando você pede. Passe respectSelection = true para continuar pintando dentro da seleção, e symmetry = app.getContext().symmetry para espelhar.
• Trabalhe pixel a pixel em uma Image. app.getImage(layer, frame) lê um cel para uma Image que vive dentro do script; img:getPixel e img:setPixel são baratos, então percorra quantos pixels quiser e depois grave de volta uma única vez com app.putImage(layer, frame, img). Cada chamada app.* é uma viagem até o editor; os métodos de uma Image, não. Em sprites indexados, img:getIndex e img:setIndex trabalham com índices da paleta.
• Use app.random para aleatoriedade. Um gerador criado com app.random.new(seed) produz os mesmos números para a mesma seed, então uma execução pode ser repetida exatamente. pairs() também percorre as chaves de uma tabela na mesma ordem em toda execução.
• Use app.color para cálculos de cor. Misturas, rampas e tons são calculados em um espaço de cor perceptual, que fica melhor do que tirar a média de valores hexadecimais.
• Imprima para conferir as coisas. print(...) escreve na área de saída; as tabelas são impressas por inteiro.

Por exemplo, este código espalha estrelas em uma nova camada; mude a seed para um céu diferente:

local layer = app.addLayer("Stars")
local frame = app.getActiveFrameId()

local rng = app.random.new(42)                        -- mesma seed, mesmas estrelas
local colors = app.color.ramp({ "#5a6b9e", "#ffffff" }, 4)

local img = app.getImage(layer, frame)                -- os pixels da camada, dentro do script
for i = 1, img.width * img.height // 40 do
  img:setPixel(rng:int(0, img.width - 1), rng:int(0, img.height - 1), rng:pick(colors))
end
app.putImage(layer, frame, img)                       -- gravado de volta como uma única alteração

Formulários de configuração

Um script pode pedir configurações antes de rodar: quando você escolhe Executar (na biblioteca ou no painel Scripts), abre-se um formulário com os campos dele (números, texto, caixas de seleção, escolhas, cores, e um pincel ou uma paleta das suas próprias bibliotecas), e o script lê o que você digitou na tabela app.config. Os campos podem aparecer ou sumir conforme as escolhas anteriores. Aleatorizar sorteia novos valores dentro dos intervalos que o autor do script escolheu, para variações rápidas. Todos os geradores oficiais funcionam assim.

Para dar um formulário a um dos seus scripts, escreva-o em JSON em Formulário de configuração nas configurações do script, no formato que a referência de Config forms descreve; as configurações dizem o que está errado antes de salvar. O formulário faz parte do rascunho e de cada versão publicada. Um script ainda deve ler todo campo como opcional e recorrer aos próprios padrões. Para entrada de dados enquanto um script roda, abra uma janela de script.

Janelas de script

Um script pode abrir uma janela própria com Dialog{}, construída do jeito que os scripts do Aseprite as constroem: rótulos, caixas de texto e de número, controles deslizantes, caixas de seleção, botões de opção, listas suspensas, campos de cor, fileiras de amostras de cor, botões e um seletor de arquivo (apenas arquivos de texto pequenos).

local dlg = Dialog{ title = "Quick Fill" }
dlg:color{ id = "paint", label = "Color", color = "#3a8f4a" }
dlg:button{ id = "fill", text = "Fill layer", onclick = function()
  local layer, frame = app.getActiveLayerId(), app.getActiveFrameId()
  app.floodFill(layer, frame, 0, 0, { color = dlg.data.paint })
end }
dlg:show{ wait = false }

• dlg:show{ wait = false } abre uma janela flutuante e o script espera, ocioso, enquanto você continua desenhando; cada clique de botão ou alteração a que ele reage é sua própria etapa de desfazer. Sem wait = false, a janela é modal: o editor fica bloqueado até você fechá-la.
• A barra de título da janela nomeia o script e a marca como de um script, e tudo nela é texto simples, então um script não consegue fazer passar a janela por parte do editor.
• Fechar a janela encerra o script; parar o script fecha as janelas dele.

A referência de Dialogs and commands tem todos os widgets e suas opções.

Comandos de script

Um script pode adicionar comandos aos menus do editor, do mesmo modo que um plugin do Aseprite. Defina uma função init(plugin) que os registra com plugin:newCommand:

local function mirror()
  app.flip("horizontal", app.getActiveLayerId())
end

function init(plugin)
  plugin:newCommand{ id = "mirror", title = "Mirror Layer", group = "layer", onclick = mirror }
end

Salve o script, depois escolha Scripts > Comandos de scripts... e pressione Instalar ao lado dele. O comando passa a aparecer:

• no menu que o group dele nomeia (file, file_import, edit, edit_transform, edit_fx, edit_adjustments, sprite, layer, frame, select ou view), mostrado com o nome do script; sem um grupo, em Scripts, em um submenu com o nome do script;
• na paleta de comandos;
• em Configurações > Atalhos de teclado..., onde você pode dar um atalho a ele.

Executar o comando executa o seu script salvo e depois o onclick do comando, como uma única etapa de desfazer. Depois de mudar quais comandos um script registra, pressione Reinstalar; Remover os tira dos menus. Um script pode adicionar até 32 comandos. Os comandos instalados ficam guardados neste navegador.

Para instalar comandos do script de outra pessoa, faça fork dele para os seus scripts primeiro.

Salvar e publicar

Seus scripts são salvos neste navegador, como seus sprites, e funcionam offline. Com o Sync, eles também ficam na sua conta e nos seus outros dispositivos.

Publicar compartilha um script na biblioteca de scripts. Todo script começa Privado, então só você o vê; escolha Compartilhado na biblioteca nas configurações dele (Configurações do script, ou o selo Privado) para listá-lo. Depois:

• Salvar rascunho mantém suas edições privadas. Quem usa a biblioteca sempre recebe a sua última versão publicada, nunca o rascunho.
• Publicar salva o rascunho e o transforma na próxima versão numerada, com a nota de lançamento que você digitar (mostrada no histórico de versões). As versões publicadas nunca mudam; publique de novo para criar uma nova.
• As configurações do script listam todas as versões publicadas. Ver código abre uma antiga somente leitura, e Restaurar no rascunho a copia para o seu rascunho.
• Um script pode ter até 3 tags, que ajudam as pessoas a encontrá-lo na biblioteca.

Publicar exige uma conta com Sync no pxstud.io. Executar, fazer fork e favoritar scripts (com uma conta gratuita) está em A biblioteca.

O que os scripts não podem fazer

Os scripts rodam em um ambiente isolado, então executar um script escrito por outra pessoa é seguro:

• Sem rede, arquivos nem carregamento de código. Um script não alcança a internet nem seus arquivos (exceto um arquivo de texto que você escolhe na janela dele) e não pode carregar outro código. As bibliotecas io, os e debug do Lua não estão lá; string, math, table, utf8 e coroutine estão.
• Apenas o sprite aberto. Um script edita o sprite em que você o executou, como uma única etapa de desfazer. Ele não pode abrir, salvar, exportar, fechar nem excluir sprites, usar a área de transferência, nem alterar a visualização e os painéis.
• Suas bibliotecas só quando você escolhe a partir delas. Um script vê um dos seus pincéis ou uma das suas paletas salvas apenas quando o formulário de configuração dele pede e você a escolhe.
• Um limite de memória. Uma execução não pode usar mais que uma quantidade definida de memória: para suas Images, seus dados Lua, os pixels que adiciona ao sprite e a etapa de desfazer que monta. Passado disso, o script é parado com um erro que diz qual foi, e o que ele fez até ali permanece como uma única etapa de desfazer, então um script descontrolado não consegue travar o editor nem empurrar suas etapas anteriores para fora do histórico de desfazer.

Não há limite de tempo; um script descontrolado sempre pode ser pausado ou parado.

Os geradores oficiais

A biblioteca de scripts do pxstud.io tem um conjunto de scripts oficiais, marcados como Oficial: geradores de gradientes, tabuleiros de xadrez, preenchimentos de ruído, paredes de tijolos, paralelepípedos, tábuas de madeira, texturas de grama e de água, raios, tornados, arco-íris, cometas, galáxias, planetas, estrelas, árvores, arbustos e pedras. Entre com uma conta gratuita, abra Scripts > Explorar a biblioteca de scripts..., escolha Oficiais e pressione Executar em um deles: preencha o formulário (ou pressione Aleatorizar) e ele desenha no seu sprite. Faça fork de um para ver como ele foi feito, ou para alterá-lo.