# Guia de scripts

Escreva scripts Lua que desenham e editam seus sprites, execute scripts e geradores da biblioteca e adicione suas próprias janelas e comandos de menu.

_Os atalhos estão escritos para Windows e Linux. No Mac, use ⌘ Cmd onde está Ctrl e ⌥ Option no lugar de Alt._

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](https://pxstud.io/pt-br/docs/scripting/first-script.md) mostra como escrever e executar um. Esta
página cobre tudo o que está em volta.

## O menu Scripts

| Item | O que faz |
| - | - |
| Scripts > Novo script... | Dá nome a um novo script e o abre no painel Scripts. |
| Scripts > Abrir meu script... | Lista seus scripts: escolha um para abri-lo, ou renomeie ou exclua. Os últimos cinco que você abriu aparecem no menu, logo abaixo. |
| Scripts > Explorar a biblioteca de scripts... | A biblioteca de scripts: pesquise, execute, faça fork e favorite scripts compartilhados, incluindo os geradores oficiais. Veja [A biblioteca](https://pxstud.io/pt-br/docs/manual/guides/library.md). |
| Scripts > Comandos de scripts... | Instala comandos de menu a partir dos seus scripts ([abaixo](https://pxstud.io/pt-br/docs/scripting/guide.md#script-commands)). |
| Scripts > API de scripting | Abre a referência da [API de scripts](https://pxstud.io/pt-br/docs/scripting.md) em uma nova aba. |

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.

![O painel Scripts mostrando o código de um script, com a barra de ferramentas no topo e a saída impressa abaixo](https://pxstud.io/scripting/images/first-script-panel.light.webp)

_O painel Scripts_

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](https://pxstud.io/pt-br/docs/scripting/guide.md#config-forms) pede os valores antes. Enquanto ele roda, os controles
  de execução tomam o lugar do botão ([abaixo](https://pxstud.io/pt-br/docs/scripting/guide.md#running-pausing-and-stopping)).
- **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:

| Controle | O que faz |
| - | - |
| **Pausar** / **Continuar** | Para o script onde ele está, mesmo no meio de um laço, e o retoma depois. |
| **Parar** | Encerra o script e mantém o que ele já fez. |
| **Parar e reverter** | Encerra o script e desfaz tudo o que ele alterou. |

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](https://pxstud.io/pt-br/docs/scripting.md) documenta cada uma, gerada a
partir do próprio editor, em seções:

- [Drawing](https://pxstud.io/pt-br/docs/scripting/drawing.md): as ferramentas como comandos (`app.drawLine`,
  `app.floodFill`, `app.drawIsoShape`...), [Images](https://pxstud.io/pt-br/docs/scripting/images.md) para trabalhar pixel a
  pixel e [Pixels](https://pxstud.io/pt-br/docs/scripting/pixels.md) para listas planas de pixels, preenchimentos e o
  conta-gotas;
- [Document](https://pxstud.io/pt-br/docs/scripting/document.md), [Layers](https://pxstud.io/pt-br/docs/scripting/layers.md),
  [Frames](https://pxstud.io/pt-br/docs/scripting/frames.md), [Cels](https://pxstud.io/pt-br/docs/scripting/cels.md),
  [Selection](https://pxstud.io/pt-br/docs/scripting/selection.md), [Slices](https://pxstud.io/pt-br/docs/scripting/slices.md) e
  [Tilemaps](https://pxstud.io/pt-br/docs/scripting/tilemaps.md);
- [Palette](https://pxstud.io/pt-br/docs/scripting/palette.md), [Adjustments](https://pxstud.io/pt-br/docs/scripting/adjustments.md) e
  [Brushes](https://pxstud.io/pt-br/docs/scripting/brushes.md);
- utilitários: cálculos de [Color](https://pxstud.io/pt-br/docs/scripting/color.md), números [Random](https://pxstud.io/pt-br/docs/scripting/random.md)
  com seed e o [Editing context](https://pxstud.io/pt-br/docs/scripting/context.md) (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:

```lua
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](https://pxstud.io/pt-br/docs/scripting/config-forms.md)
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).

```lua
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](https://pxstud.io/pt-br/docs/scripting/dialogs.md) 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`:

```lua
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](https://pxstud.io/pt-br/docs/manual/concepts/how-work-is-organized.md#where-things-are-kept), 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](https://pxstud.io/pt-br/docs/manual/guides/library.md).

## 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.