# API de scripts Lua do pxstud.io — Contexto de edição

> Parte da referência de scripts Lua do pxstud.io, cuja visão geral (https://pxstud.io/pt-br/docs/scripting.md) explica as convenções. Os grupos de opções e os tipos a que ela remete estão em https://pxstud.io/pt-br/docs/scripting/option-groups.md e https://pxstud.io/pt-br/docs/scripting/types.md. Tudo em um único arquivo (em inglês): https://pxstud.io/llms-full.txt. O índice de todo o site (em inglês): https://pxstud.io/llms.txt.

### Contexto de edição
As cores, o pincel, a simetria e as opções de ferramenta atuais, compartilhados com a barra de ferramentas do editor. Os comandos de desenho os usam para as cores, o pincel e as opções de ferramenta que não recebem; a simetria é apenas informativa e só é aplicada quando você a passa.

#### `app.getContext()` — lê
O contexto de edição: as configurações que os comandos de desenho usam para as cores, o pincel e as opções de ferramenta que você não passa, compartilhadas com a barra de ferramentas da interface. symmetry é o botão de simetria da barra de ferramentas, legível aqui mas NÃO aplicado implicitamente aos comandos: passe symmetry = app.getContext().symmetry a um comando de desenho para segui-lo. Campos: { foregroundColor, backgroundColor, brushSize, brushShape, brushAngle, customBrush, pixelPerfect, eraserRightClick, ink, shades, stabilizer, pressureSize, pressureAngle, pressureGradient, pressureMin, pressureMax, velocitySize, velocityAngle, velocityGradient, velocityMin, velocityMax, dynamicsMinSize, dynamicsMinAngle, dynamicsMaxAngle, dynamicsDither, dynamicsCurve, symmetry, symmetryX, symmetryY, tilemapMode, shapeFillMode, cornerRadius, selectionCornerRadius, cornerRadiusLinked, lineWidth, curvePixelPerfect, bucketFillMode, bucketTolerance, bucketCloseGap, bucketDiagonal, bucketStopAtGrid, bucketPattern, wandFillMode, wandTolerance, wandDiagonal, wandStopAtGrid, sprayRate, scatterX, scatterY, scatterCount, blurStrength, jumbleStrength, dodgeBurnStrength, dodgeBurnHueShift, ditherPattern, ditherDensity, gradientType, gradientDithering, gradientSnap, gradientColors, gradientStops, eyedropperSource, tileIndex, tileFlipH, tileFlipV, tileRotate90, tilePlace, isoShape, isoWidth, isoDepth, isoHeight, isoBevel, isoCap, isoStyle, isoHiddenEdges, isoDirection, isoAutoShade, isoColors }. As cores são tabelas { r, g, b, a }; symmetry é um array de eixos; customBrush é { width, height, mask (lista plana de 0/1) } ou nil. Altere-o com app.setContext.

Retorna (table): Tabela de contexto.

#### `app.setContext(props)` — altera
Altera o contexto de edição: as cores, o pincel, a simetria, o modo de tilemap e as opções de ferramenta atuais. Os comandos de desenho os usam para as opções que não recebem, exceto symmetry, que só é guardada para a interface (e pode ser lida via app.getContext) e nunca é aplicada a um comando a menos que você a passe. Compartilhado com a interface: a barra de ferramentas mostra a mudança, e ela persiste depois que o script termina. Não é uma edição que possa ser desfeita.

- `props` (table) — As chaves omitidas não mudam.
  - `foregroundColor` (color ("#rgb", "#rrggbb[aa]" or { r, g, b, a })) — A cor de pintura: a `color` de todo comando de desenho e a cor inicial do gradiente.
  - `backgroundColor` (color ("#rgb", "#rrggbb[aa]" or { r, g, b, a })) — A cor secundária: a cor final do gradiente e o que swapColors troca.
  - `brushSize` (integer 1–64) — Tamanho do pincel em pixels para as formas integradas (ignorado por um pincel personalizado). Também define o raio do spray (2x o tamanho).
  - `brushShape` (BrushShape: "circle" | "square" | "line" | "diamond" | "cross" | "x" | "star" | "horizontal" | "custom") — "line" é uma linha de 1px inclinada por `brushAngle`; "square" é girado por ele; "circle", "diamond", "cross", "x" e "star" o ignoram; "horizontal" é uma linha em ângulo 0 que o ignora; "custom" pinta `customBrush`.
  - `brushAngle` (integer 0–180) — Ângulo do pincel em graus (0-180): inclina o pincel "line" e gira o pincel "square". Ignorado pelas outras formas.
  - `customBrush` ({ width, height, mask } with mask a flat list of 0/1, or false to clear) — A máscara que um pincel personalizado pinta: { rows = { ".#.", "###", ".#." } } ou { width, height, mask } com mask sendo uma lista plana de 0/1. Normalmente definido com app.useBrush(name) a partir de um pincel definido com app.defineBrush. Sem uma máscara, um pincel personalizado pinta um ponto de 1px.
  - `pixelPerfect` (boolean) — Remove os degraus duplicados dos cantos em traços à mão livre (qualquer tamanho de pincel); o pincel é carimbado ao longo do caminho corrigido.
  - `eraserRightClick` (EraserRightClick: "background" | "replace") — Botão direito da borracha: "background" pinta a cor de fundo em todo lugar que toca, "replace" transforma em cor de fundo só os pixels da cor de primeiro plano (Aseprite).
  - `ink` (Ink: "copy" | "simple" | "lock-alpha" | "shading") — Como a tinta (traços, spray, formas, linhas, polígono, contorno, balde, gradiente, fillSelection) se combina com os pixels existentes: "copy" os substitui (o padrão), "simple" faz composição alfa, "lock-alpha" recolore apenas os pixels visíveis, "shading" avança os pixels ao longo de `shades`.
  - `shades` (a list of colors ("#rrggbb[aa]" or { r, g, b, a }), in order) — A rampa ao longo da qual a tinta shading avança, em ordem: a caixa de Tons do editor (ou o intervalo de paleta selecionado). Os comandos de desenho a usam quando ink é shading.
  - `stabilizer` (integer 0–64) — Intensidade do estabilizador para traços à mão livre: cada ponto é calculado em média com os N pontos anteriores, suavizando tremores (o traço fica atrás do cursor). 0 = desativado.
  - `pressureSize` (boolean) — Deixa a pressão da caneta (o mouse conta como pressão máxima) controlar o tamanho do pincel, de dynamicsMinSize até brushSize.
  - `pressureAngle` (boolean) — Deixa a pressão da caneta (o mouse conta como pressão máxima) controlar o ângulo do pincel, de dynamicsMinAngle a dynamicsMaxAngle.
  - `pressureGradient` (boolean) — Deixa a pressão da caneta (o mouse conta como pressão máxima) misturar a cor de foregroundColor para backgroundColor ao longo do traço.
  - `pressureMin` (integer 0–100) — Leitura (em porcentagem) do sensor de pressão que corresponde ao extremo baixo. Maior que pressureMax inverte o mapeamento.
  - `pressureMax` (integer 0–100) — Leitura (em porcentagem) do sensor de pressão que corresponde ao extremo alto.
  - `velocitySize` (boolean) — Deixa a velocidade do ponteiro controlar o tamanho do pincel, de dynamicsMinSize até brushSize.
  - `velocityAngle` (boolean) — Deixa a velocidade do ponteiro controlar o ângulo do pincel, de dynamicsMinAngle a dynamicsMaxAngle.
  - `velocityGradient` (boolean) — Deixa a velocidade do ponteiro misturar a cor de foregroundColor para backgroundColor ao longo do traço.
  - `velocityMin` (integer 0–100) — Leitura (em porcentagem) do sensor de velocidade que corresponde ao extremo baixo. Maior que velocityMax inverte o mapeamento.
  - `velocityMax` (integer 0–100) — Leitura (em porcentagem) do sensor de velocidade que corresponde ao extremo alto.
  - `dynamicsMinSize` (integer 1–64) — Tamanho do pincel no extremo baixo de um sensor mapeado para o tamanho (o extremo alto é brushSize).
  - `dynamicsMinAngle` (integer 0–180) — Ângulo do pincel no extremo baixo de um sensor mapeado para o ângulo.
  - `dynamicsMaxAngle` (integer 0–180) — Ângulo do pincel no extremo alto de um sensor mapeado para o ângulo.
  - `dynamicsDither` (boolean) — As dinâmicas de gradiente escolhem foregroundColor ou backgroundColor por pixel (dithering ordenado) em vez de misturar. Em sprites indexed, as misturas se ajustam à cor de paleta mais próxima.
  - `dynamicsCurve` (integer 25–400) — Curva de sensibilidade em porcentagem: o valor do sensor é elevado a curve/100 (100 = linear; acima de 100 exige mais pressão/velocidade para fazer efeito).
  - `symmetry` (lista de SymmetryAxis: "horizontal" | "vertical" | "diagonal" | "antidiagonal") — A configuração de simetria do sprite ativo (cada sprite guarda a sua, como a posição do eixo): eixos de espelhamento pelo centro de simetria. Apenas informação legível: os comandos de desenho não a aplicam, a menos que você passe symmetry = app.getContext().symmetry. Vazio = desativada; vários eixos se combinam (horizontal + vertical = 4 direções).
  - `symmetryX` (a number (multiple of 0.5), or false to re-center) — Onde fica o eixo de simetria vertical (e o ponto em que as duas diagonais se cruzam): pixels a partir da borda esquerda da tela, um múltiplo de 0.5 (inteiro = entre pixels, x.5 = pelo meio de um pixel). nil = centralizado. Como symmetry, apenas informação legível: passe symmetryX = app.getContext().symmetryX a um comando de desenho para segui-lo. Defina false para recentralizar.
  - `symmetryY` (a number (multiple of 0.5), or false to re-center) — Onde fica o eixo de simetria horizontal (e o cruzamento das diagonais): pixels a partir da borda superior da tela, um múltiplo de 0.5. nil = centralizado. Defina false para recentralizar.
  - `tilemapMode` (TilemapEditMode: "tiles" | "pixels-edit" | "pixels-auto") — Como a tinta de pixel trata uma camada de tilemap: "pixels-auto" dá a cada célula pintada o seu próprio tile, "pixels-edit" edita o tile compartilhado no lugar (todo posicionamento é atualizado), "tiles" permite apenas carimbar tiles inteiros.
  - `shapeFillMode` (FillMode: "outline" | "filled") — Retângulos, elipses, polígonos e curvas fechadas: contorno ou preenchidos.
  - `cornerRadius` (an integer 0–1024 for every corner, or a list of four { topLeft, topRight, bottomRight, bottomLeft }) — Retângulo: raios dos cantos em pixels, no sentido horário a partir do canto superior esquerdo (0 = canto reto), cada um limitado à metade do lado menor.
  - `selectionCornerRadius` (an integer 0–1024 for every corner, or a list of four { topLeft, topRight, bottomRight, bottomLeft }) — Seleção retangular: raios dos cantos em pixels, no sentido horário a partir do canto superior esquerdo (0 = canto reto).
  - `cornerRadiusLinked` (boolean) — A barra de opções de ferramenta edita os quatro raios dos cantos juntos (um único campo Raio) em vez de um campo por canto.
  - `lineWidth` (integer 1–64) — Ferramentas Linha e Curva: espessura em pixels (1 = uma linha rígida de 1px); linhas mais largas têm pontas arredondadas.
  - `curvePixelPerfect` (boolean) — Ferramenta Curva: remove os cantos em L que uma curva de 1px acumula, para linhas de pixel art limpas.
  - `bucketFillMode` (BucketFillMode: "contiguous" | "global") — Balde de tinta: apenas a região conectada, ou todos os pixels correspondentes.
  - `bucketTolerance` (integer 0–255) — Balde de tinta: a maior diferença por canal que ainda conta como a mesma cor.
  - `bucketCloseGap` (integer 0–5) — Preenchimento (contíguo): trata como fechadas as falhas no contorno de até esta largura em pixels, para que o preenchimento não vaze por elas. 0 = desativado.
  - `bucketDiagonal` (boolean) — Balde de tinta (contíguo): também se espalha para vizinhos diagonais (8 conectados), então a região vaza por linhas diagonais de 1px.
  - `bucketStopAtGrid` (boolean) — Balde de tinta: confina a região à célula da grade em que o clique cai.
  - `bucketPattern` (FillPattern: "solid" | "checker" | "dither25" | "dither75" | "hstripes" | "vstripes" | "diagonal" | "grid" | "dots" | "bricks") — Preenchimento: pinta um padrão repetido de duas cores (a cor do preenchimento e a outra entre primeiro plano/fundo) em vez de uma cor sólida. "solid" = sem padrão.
  - `wandFillMode` (BucketFillMode: "contiguous" | "global") — Varinha mágica: apenas a região conectada, ou todos os pixels correspondentes. Separado do bucketFillMode do balde de tinta.
  - `wandTolerance` (integer 0–255) — Varinha mágica: a maior diferença por canal que ainda conta como a mesma cor. Separada da bucketTolerance do balde de tinta.
  - `wandDiagonal` (boolean) — Varinha mágica (contíguo): também se espalha para vizinhos diagonais (8 conectados), então a região vaza por linhas diagonais de 1px.
  - `wandStopAtGrid` (boolean) — Varinha mágica: confina a região à célula da grade em que o clique cai.
  - `sprayRate` (integer 1–64) — Spray: pontos por ponto.
  - `scatterX` (integer 0–64) — Dispersão: a que distância, em pixels, cada carimbo pode cair à esquerda ou à direita do caminho.
  - `scatterY` (integer 0–64) — Dispersão: a que distância, em pixels, cada carimbo pode cair acima ou abaixo do caminho.
  - `scatterCount` (integer 1–16) — Dispersão: carimbos colocados a cada passo ao longo do caminho.
  - `blurStrength` (integer 1–4) — Desfoque: raio da vizinhança em pixels.
  - `jumbleStrength` (integer 0–100) — Embaralhar: porcentagem de chance de cada pixel tocado ser embaralhado.
  - `dodgeBurnStrength` (integer 1–100) — Subexpor/Superexpor: quanto a luminosidade OKLCH de cada pixel tocado se move (100 = metade do caminho do preto ao branco).
  - `dodgeBurnHueShift` (integer 0–60) — Subexpor/Superexpor: graus que o matiz OKLCH de cada pixel tocado gira em direção ao amarelo quente (subexpor) ou ao azul frio (superexpor), sem passar dele; 0 mantém o matiz.
  - `ditherPattern` (DitherPattern: "bayer2" | "bayer4" | "bayer8" | "dots" | "lines-h" | "lines-v" | "diagonal" | "noise") — Pincel de dithering: o padrão ordenado com que ele pinta. Os padrões se repetem a partir do canto superior esquerdo do sprite, então os traços se alinham.
  - `ditherDensity` (integer 0–100) — Pincel de dithering: a parcela dos pixels do padrão que ele pinta, em porcentagem (50 com bayer2 é um tabuleiro de xadrez).
  - `gradientType` (GradientType: "linear" | "radial") — Gradiente: uma rampa reta entre os pontos ou irradiando do ponto inicial.
  - `gradientDithering` (GradientDithering: "none" | "bayer2" | "bayer4" | "bayer8" | "dots" | "lines-h" | "lines-v" | "diagonal" | "noise") — Gradiente: o padrão de dithering ordenado (none = uma rampa suave).
  - `gradientSnap` (GradientSnap: "free" | "palette") — Gradiente: misturas livres ou apenas cores da paleta (cada pixel na cor de paleta mais próxima; o dithering alterna entre cores de paleta vizinhas).
  - `gradientColors` (GradientColors: "fg-bg" | "stops") — Gradiente: vai da cor de primeiro plano à de fundo ou ao longo de gradientStops ("stops"; com menos de duas paradas, volta para primeiro plano e fundo).
  - `gradientStops` (a list of { color, position } (position 0-1, in order), or a list of colors spread evenly) — Gradiente: a rampa de várias paradas a partir do ponto inicial, como entradas { color, position } (position de 0 a 1, em ordem; duas na mesma posição fazem uma borda rígida). Uma lista simples de cores é distribuída uniformemente. Usada quando gradientColors é "stops"; a barra Paradas do editor a edita.
  - `eyedropperSource` (EyedropperSource: "composite" | "layer") — Conta-gotas: amostra o que a tela mostra ou apenas a camada ativa.
  - `tileIndex` (integer ≥ 0) — Carimbo de tiles: o tile a posicionar, a partir de 1 (0 = o tile vazio).
  - `tileFlipH` (boolean) — Carimbo de tiles: espelha horizontalmente os tiles posicionados.
  - `tileFlipV` (boolean) — Carimbo de tiles: espelha verticalmente os tiles posicionados.
  - `tileRotate90` (boolean) — Carimbo de tiles: gira os tiles posicionados em 90° no sentido horário.
  - `tilePlace` (boolean) — Posicionar tiles: em uma camada de tilemap, o lápis, a borracha, a linha, as ferramentas de forma e o balde posicionam o tile do carimbo de tiles (o apagam, no caso da borracha) nas células que cobrem, em vez de pintar pixels.
  - `isoShape` (IsoShape: "box" | "ramp" | "stairs" | "pyramid" | "prism" | "cylinder" | "cone" | "sphere" | "dome") — Ferramenta Forma isométrica: o sólido que ela desenha.
  - `isoWidth` (integer 1–1024) — Ferramenta Forma isométrica: base ao longo de x (para baixo e à direita), em unidades isométricas (uma linha da escada da aresta cada).
  - `isoDepth` (integer 1–1024) — Ferramenta Forma isométrica: base ao longo de y (para baixo e à esquerda), em unidades isométricas.
  - `isoHeight` (integer 0–1024) — Ferramenta Forma isométrica: altura em pixels (0 = plana).
  - `isoBevel` (integer 0–1024) — Ferramenta Forma isométrica: apenas caixas, quantos pixels as arestas superiores são chanfradas (0 = reta).
  - `isoCap` (integer 2–4) — Ferramenta Forma isométrica: o trecho plano nos vértices superior e inferior, 2 (par), 3 (ímpar) ou 4 (múltiplos de quatro). É também o passo de arrasto de W / D (2 unidades com cap 4).
  - `isoStyle` (IsoShapeStyle: "filled" | "outline" | "filled-outline") — Ferramenta Forma isométrica: faces, contorno ou ambos.
  - `isoHiddenEdges` (boolean) — Ferramenta Forma isométrica: desenha também as arestas atrás do sólido.
  - `isoDirection` (IsoDirection: "+x" | "-x" | "+y" | "-y") — Ferramenta Forma isométrica: para que lado descem uma rampa ou uma escada, ou para que lado ficam voltadas as inclinações de um prisma.
  - `isoAutoShade` (boolean) — Ferramenta Forma isométrica: deriva as cinco cores da cor de primeiro plano ao longo de `shades` (true) ou usa isoColors (false).
  - `isoColors` (a list of colors ("#rrggbb[aa]" or { r, g, b, a }), in order) — Ferramenta Forma isométrica: as cores usadas quando isoAutoShade está desativado, em ordem: contorno, aresta interna, topo, esquerda, direita.

Não retorna nada.

#### `app.swapColors()` — altera
Troca as cores de primeiro plano e de fundo (o X da interface).

Não retorna nada.