# API de scripts Lua do pxstud.io — Configurações de contexto

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

## Configurações de contexto
As configurações que os comandos de desenho usam para cada opção não informada: os mesmos valores que a barra de ferramentas do editor mostra. Leia-as com `app.getContext()` e altere-as com `app.setContext({ ... })`. Elas não fazem parte do documento e não podem ser desfeitas.

- `foregroundColor` (color — "#rgb", "#rrggbb[aa]" or { r, g, b, a }; padrão { r = 0, g = 0, b = 0, a = 255 }) — A cor de pintura: o `color` de todo comando de desenho e a cor inicial do gradiente.
- `backgroundColor` (color — "#rgb", "#rrggbb[aa]" or { r, g, b, a }; padrão { r = 255, g = 255, b = 255, a = 255 }) — A cor secundária: a cor final do gradiente e o que swapColors troca.
- `brushSize` (integer 1–64; padrão 1) — Tamanho do pincel em pixels para as formas embutidas (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"; padrão "circle") — "line" é uma linha de 1px inclinada por `brushAngle`; "square" é girado por ele; "circle", "diamond", "cross", "x" e "star" o ignoram; "horizontal" é uma linha no ângulo 0 que o ignora; "custom" pinta `customBrush`.
- `brushAngle` (integer 0–180; padrão 0) — Ângulo do pincel em graus (0-180): inclina o pincel "line" e gira o pincel "square". Ignorado pelas outras formas.
- `customBrush` ({ width, height, mask } or false; padrão nil) — A máscara que um pincel personalizado pinta: { rows = { ".#.", "###", ".#." } } ou { width, height, mask } com mask uma lista plana de 0/1. Normalmente definida 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; padrão false) — Remove os degraus de canto duplicados dos traços à mão livre (qualquer tamanho de pincel); o pincel é carimbado ao longo do caminho corrigido.
- `eraserRightClick` (EraserRightClick: "background" | "replace"; padrão "background") — Botão direito da borracha: "background" pinta a cor de fundo em tudo que toca, "replace" transforma só os pixels da cor de primeiro plano na cor de fundo (Aseprite).
- `ink` (Ink: "copy" | "simple" | "lock-alpha" | "shading"; padrão "copy") — 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" percorre os pixels ao longo de `shades`.
- `shades` (list of colors — "#rgb", "#rrggbb[aa]" or { r, g, b, a }; padrão {}) — A rampa que a tinta de sombreamento percorre, em ordem: a caixa Sombras do editor (ou a faixa de paleta selecionada). Os comandos de desenho a usam quando a tinta é shading.
- `stabilizer` (integer 0–64; padrão 0) — Força do estabilizador para traços à mão livre: cada ponto é calculado como média com os N pontos anteriores, suavizando a tremedeira (o traço fica atrás do cursor). 0 = desativado.
- `pressureSize` (boolean; padrão true) — 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; padrão false) — Deixa a pressão da caneta (o mouse conta como pressão máxima) controlar o ângulo do pincel, de dynamicsMinAngle até dynamicsMaxAngle.
- `pressureGradient` (boolean; padrão false) — Deixa a pressão da caneta (o mouse conta como pressão máxima) misturar a cor de foregroundColor a backgroundColor ao longo do traço.
- `pressureMin` (integer 0–100; padrão 0) — Leitura (em porcentagem) do sensor de pressão que corresponde ao extremo inferior. Maior que pressureMax inverte o mapeamento.
- `pressureMax` (integer 0–100; padrão 100) — Leitura (em porcentagem) do sensor de pressão que corresponde ao extremo superior.
- `velocitySize` (boolean; padrão false) — Deixa a velocidade do ponteiro controlar o tamanho do pincel, de dynamicsMinSize até brushSize.
- `velocityAngle` (boolean; padrão false) — Deixa a velocidade do ponteiro controlar o ângulo do pincel, de dynamicsMinAngle até dynamicsMaxAngle.
- `velocityGradient` (boolean; padrão false) — Deixa a velocidade do ponteiro misturar a cor de foregroundColor a backgroundColor ao longo do traço.
- `velocityMin` (integer 0–100; padrão 0) — Leitura (em porcentagem) do sensor de velocidade que corresponde ao extremo inferior. Maior que velocityMax inverte o mapeamento.
- `velocityMax` (integer 0–100; padrão 100) — Leitura (em porcentagem) do sensor de velocidade que corresponde ao extremo superior.
- `dynamicsMinSize` (integer 1–64; padrão 1) — Tamanho do pincel no extremo inferior de um sensor mapeado para o tamanho (o extremo superior é brushSize).
- `dynamicsMinAngle` (integer 0–180; padrão 0) — Ângulo do pincel no extremo inferior de um sensor mapeado para o ângulo.
- `dynamicsMaxAngle` (integer 0–180; padrão 180) — Ângulo do pincel no extremo superior de um sensor mapeado para o ângulo.
- `dynamicsDither` (boolean; padrão false) — As dinâmicas de gradiente escolhem foregroundColor ou backgroundColor por pixel (dithering ordenado) em vez de misturar. Sprites indexados ajustam as misturas para a cor da paleta mais próxima.
- `dynamicsCurve` (integer 25–400; padrão 100) — 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` (list of SymmetryAxis: "horizontal" | "vertical" | "diagonal" | "antidiagonal"; padrão {}) — A configuração de simetria do sprite ativo (cada sprite guarda a sua, como a posição do eixo): eixos de espelhamento passando pelo centro de simetria. Apenas informação de leitura — 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` (number (multiple of 0.5) or false; padrão nil) — 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, múltiplo de 0.5 (inteiro = entre pixels, x.5 = pelo meio de um pixel). nil = centralizado. Como symmetry, apenas informação de leitura: passe symmetryX = app.getContext().symmetryX a um comando de desenho para segui-lo. Defina false para recentralizar.
- `symmetryY` (number (multiple of 0.5) or false; padrão nil) — Onde fica o eixo de simetria horizontal (e o cruzamento das diagonais): pixels a partir da borda superior da tela, múltiplo de 0.5. nil = centralizado. Defina false para recentralizar.
- `tilemapMode` (TilemapEditMode: "tiles" | "pixels-edit" | "pixels-auto"; padrão "pixels-auto") — Como a pintura de pixels trata uma camada de tilemap: "pixels-auto" dá a cada célula pintada seu próprio tile, "pixels-edit" edita o tile compartilhado no lugar (toda posição colocada é atualizada), "tiles" permite apenas carimbar tiles inteiros.
- `shapeFillMode` (FillMode: "outline" | "filled"; padrão "outline") — Retângulos, elipses, polígonos e curvas fechadas: contorno ou preenchidos.
- `cornerRadius` (integer 0–1024 (every corner), or a list of four, clockwise from the top-left; padrão { 0, 0, 0, 0 }) — 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` (integer 0–1024 (every corner), or a list of four, clockwise from the top-left; padrão { 0, 0, 0, 0 }) — Seleção retangular: raios dos cantos em pixels, no sentido horário a partir do canto superior esquerdo (0 = canto reto).
- `cornerRadiusLinked` (boolean; padrão true) — A barra de opções da ferramenta edita os quatro raios dos cantos juntos (um único campo Raio) em vez de um campo por canto.
- `lineWidth` (integer 1–64; padrão 1) — Ferramentas Linha e Curva: espessura em pixels (1 = uma linha rígida de 1px); linhas mais largas têm pontas arredondadas.
- `curvePixelPerfect` (boolean; padrão true) — Ferramenta Curva: remove os cantos em L que uma curva de 1px acumula, para linhas de pixel art limpas.
- `bucketFillMode` (BucketFillMode: "contiguous" | "global"; padrão "contiguous") — Balde de tinta: apenas a região conectada, ou todos os pixels correspondentes.
- `bucketTolerance` (integer 0–255; padrão 0) — Balde de tinta: a maior diferença por canal que ainda conta como a mesma cor.
- `bucketCloseGap` (integer 0–5; padrão 0) — Balde de tinta (contíguo): trata como fechadas as lacunas no contorno de até esta largura em pixels, para que o preenchimento não vaze por elas. 0 = desativado.
- `bucketDiagonal` (boolean; padrão false) — 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; padrão false) — 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"; padrão "solid") — Balde de tinta: pinta um padrão repetido de duas cores (a cor de preenchimento e a outra entre primeiro plano/fundo) em vez de uma cor sólida. "solid" = sem padrão.
- `wandFillMode` (BucketFillMode: "contiguous" | "global"; padrão "contiguous") — Varinha mágica: apenas a região conectada, ou todos os pixels correspondentes. Separado do bucketFillMode do balde de tinta.
- `wandTolerance` (integer 0–255; padrão 0) — 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; padrão false) — 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; padrão false) — Varinha mágica: confina a região à célula da grade em que o clique cai.
- `sprayRate` (integer 1–64; padrão 8) — Spray: pontos por ponto.
- `scatterX` (integer 0–64; padrão 8) — Dispersão: a que distância cada carimbo pode cair à esquerda ou à direita do caminho, em pixels.
- `scatterY` (integer 0–64; padrão 8) — Dispersão: a que distância cada carimbo pode cair acima ou abaixo do caminho, em pixels.
- `scatterCount` (integer 1–16; padrão 2) — Dispersão: carimbos colocados a cada passo ao longo do caminho.
- `blurStrength` (integer 1–4; padrão 1) — Desfoque: raio da vizinhança em pixels.
- `jumbleStrength` (integer 0–100; padrão 100) — Embaralhar: chance, em porcentagem, de cada pixel tocado ser embaralhado.
- `dodgeBurnStrength` (integer 1–100; padrão 25) — Subexpor/Superexpor: quanto a luminosidade OKLCH de cada pixel tocado se move (100 = metade do caminho do preto ao branco).
- `dodgeBurnHueShift` (integer 0–60; padrão 0) — 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"; padrão "bayer2") — Pincel de dithering: o padrão ordenado pelo qual 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; padrão 50) — Pincel de dithering: a parcela dos pixels do padrão que ele pinta, em porcentagem (50 com bayer2 é um xadrez).
- `gradientType` (GradientType: "linear" | "radial"; padrão "linear") — Gradiente: uma rampa reta entre os pontos, ou irradiando a partir do ponto inicial.
- `gradientDithering` (GradientDithering: "none" | "bayer2" | "bayer4" | "bayer8" | "dots" | "lines-h" | "lines-v" | "diagonal" | "noise"; padrão "bayer4") — Gradiente: o padrão de dithering ordenado (none = uma rampa suave).
- `gradientSnap` (GradientSnap: "free" | "palette"; padrão "free") — Gradiente: misturas livres, ou apenas cores da paleta (cada pixel vira a cor da paleta mais próxima; o dithering alterna entre cores vizinhas da paleta).
- `gradientColors` (GradientColors: "fg-bg" | "stops"; padrão "fg-bg") — 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` (list of up to 32 { color, position } (position 0–1, in order), or of colors spread evenly; padrão {}) — Gradiente: a rampa de várias paradas a partir do ponto inicial, como entradas { color, position } (position 0-1, em ordem; duas na mesma posição formam uma borda rígida). Uma lista simples de cores é distribuída igualmente. Usada quando gradientColors é "stops"; a barra Paradas do editor a edita.
- `eyedropperSource` (EyedropperSource: "composite" | "layer"; padrão "composite") — Conta-gotas: amostra o que a tela mostra, ou apenas a camada ativa.
- `tileIndex` (integer ≥ 0; padrão 1) — Carimbo de tile: o tile a colocar, começando em 1 (0 = o tile vazio).
- `tileFlipH` (boolean; padrão false) — Carimbo de tile: inverte horizontalmente os tiles colocados.
- `tileFlipV` (boolean; padrão false) — Carimbo de tile: inverte verticalmente os tiles colocados.
- `tileRotate90` (boolean; padrão false) — Carimbo de tile: gira os tiles colocados em 90° no sentido horário.
- `tilePlace` (boolean; padrão false) — Colocar tiles: em uma camada de tilemap, o lápis, a borracha, a linha, as ferramentas de forma e o balde colocam o tile do carimbo de tile (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"; padrão "box") — Ferramenta Forma isométrica: o sólido que ela desenha.
- `isoWidth` (integer 1–1024; padrão 8) — Ferramenta Forma isométrica: base ao longo de x (para baixo e à direita), em unidades iso (uma fileira da escada da borda cada).
- `isoDepth` (integer 1–1024; padrão 8) — Ferramenta Forma isométrica: base ao longo de y (para baixo e à esquerda), em unidades iso.
- `isoHeight` (integer 0–1024; padrão 8) — Ferramenta Forma isométrica: altura em pixels (0 = plano).
- `isoBevel` (integer 0–1024; padrão 0) — Ferramenta Forma isométrica: só para caixas, quantos pixels as bordas superiores são chanfradas (0 = reto).
- `isoCap` (integer 2–4; padrão 3) — 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"; padrão "filled-outline") — Ferramenta Forma isométrica: faces, contorno, ou ambos.
- `isoHiddenEdges` (boolean; padrão false) — Ferramenta Forma isométrica: desenha também as bordas atrás do sólido.
- `isoDirection` (IsoDirection: "+x" | "-x" | "+y" | "-y"; padrão "+x") — Ferramenta Forma isométrica: para que lado uma rampa ou escada descem, ou para que lado as inclinações de um prisma se voltam.
- `isoAutoShade` (boolean; padrão true) — Ferramenta Forma isométrica: deriva as cinco cores da cor de primeiro plano ao longo de `shades` (true), ou usa isoColors (false).
- `isoColors` (list of colors — "#rgb", "#rrggbb[aa]" or { r, g, b, a }; padrão { { r = 34, g = 32, b = 52, a = 255 }, { r = 69, g = 68, b = 79, a = 255 }, { r = 203, g = 219, b = 252, a = 255 }, { r = 139, g = 155, b = 180, a = 255 }, { r = 90, g = 105, b = 136, a = 255 } }) — Ferramenta Forma isométrica: as cores usadas quando isoAutoShade está desativado, em ordem: contorno, borda interna, topo, esquerda, direita.