# API de scripts Lua do pxstud.io — Grupos de opções

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

## Grupos de opções
Conjuntos de opções compartilhados por várias funções, definidos uma única vez aqui. A tabela `opts` de uma função diz quais grupos ela também aceita: "também aceita Opções de pintura" significa que cada opção abaixo é aceita, com o mesmo significado e os mesmos valores padrão, além das próprias da função.

### Opções de pintura (`paint`)
Aceitas por todo comando que pinta pixels (as funções de desenho e as ferramentas de traço). Todas são opcionais. Por padrão, um comando de desenho ignora a seleção e não espelha, seja qual for o estado atual do editor; ative com respectSelection = true e symmetry = app.getContext().symmetry (ou uma lista de eixos). tilemapMode é preenchido a partir do contexto de edição.
Aceito por: `app.blur`, `app.dodgeBurn`, `app.drawContour`, `app.drawCurve`, `app.drawEllipse`, `app.drawGradient`, `app.drawHexagon`, `app.drawIsoShape`, `app.drawLine`, `app.drawPolygon`, `app.drawRectangle`, `app.drawStar`, `app.drawStroke`, `app.drawTriangle`, `app.floodFill`, `app.jumble`, `app.scatter`, `app.spray`.

  - `respectSelection` (boolean; padrão false) — Passe true para pintar apenas dentro da seleção atual (leia-a com app.getSelection / app.isSelected). Por padrão, a seleção é ignorada.
  - `symmetry` (lista de SymmetryAxis: "horizontal" | "vertical" | "diagonal" | "antidiagonal"; padrão none) — Eixos de espelhamento pelo centro da tela (ou por symmetryX / symmetryY); combinações (horizontal + vertical) dão simetria em 4 direções. Padrão nenhum: passe symmetry = app.getContext().symmetry para seguir o botão de simetria do editor, ou uma lista de eixos como { "vertical" }.
  - `symmetryX` (number ≥ 0; padrão the canvas center (width / 2)) — Onde fica o eixo 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). Limitado à tela. Passe app.getContext().symmetryX para seguir a guia do editor (nil ali significa centralizado).
  - `symmetryY` (number ≥ 0; padrão the canvas center (height / 2)) — Onde fica o eixo horizontal (e o cruzamento das diagonais): pixels a partir da borda superior da tela, um múltiplo de 0.5. Limitado à tela.
  - `tilemapMode` (TilemapEditMode: "pixels-edit" | "pixels-auto"; padrão context.tilemapMode) — Como uma camada de tilemap recebe tinta de pixel: auto dá a cada célula pintada o seu próprio tile, edit altera o tile compartilhado no lugar. Ignorado em camadas de imagem.

### Opções de posicionamento (`tilePlace`)
Todas são opcionais. Por padrão, os tiles vão em todas as células informadas, seja qual for o estado do editor. As células espelhadas recebem o tile espelhado: um eixo vertical alterna flipH, um horizontal alterna flipV, um diagonal o transpõe (rotate90 mais um flip). Uma célula sobre um eixo mantém o tile como foi posicionado.
Aceito por: `app.fillTiles`, `app.stampTiles`.

  - `respectSelection` (boolean; padrão false) — Passe true para pular as células sem nenhum pixel selecionado (um preenchimento também para nelas).
  - `symmetry` (lista de SymmetryAxis: "horizontal" | "vertical" | "diagonal" | "antidiagonal"; padrão none) — Posiciona também nas células espelhadas por esses eixos (e suas combinações). Passe app.getContext().symmetry para seguir o botão do editor.
  - `symmetryX` (number ≥ 0; padrão the canvas center (width / 2)) — Onde fica o eixo vertical, em pixels a partir da borda esquerda da tela (um múltiplo de 0.5).
  - `symmetryY` (number ≥ 0; padrão the canvas center (height / 2)) — Onde fica o eixo horizontal, em pixels a partir da borda superior da tela (um múltiplo de 0.5).

### Opções de pincel (`brush`)
Aceitas pelas ferramentas de traço (drawStroke, blur, jumble). Passe um pincel integrado por tamanho e forma, ou um pincel personalizado por nome ou inline.
Aceito por: `app.blur`, `app.dodgeBurn`, `app.drawStroke`, `app.jumble`, `app.scatter`.

  - `brushSize` (integer 1–64; padrão context.brushSize) — Tamanho do pincel em pixels.
  - `brushShape` (BrushShape: "circle" | "square" | "line" | "diamond" | "cross" | "x" | "star" | "horizontal"; padrão context.brushShape) — Forma do pincel. Para um pincel personalizado, use `brush`.
  - `brushAngle` (integer 0–180; padrão context.brushAngle) — Ângulo do pincel em graus: inclina a forma "line" (0 = horizontal, 90 = vertical) e gira "square".
  - `brush` (brush name, or an inline { rows } / { width, height, mask }) — Um pincel personalizado: o nome de um que você definiu com app.defineBrush, ou uma definição inline. Substitui brushSize, brushShape e brushAngle.

### Opções de tinta (`ink`)
Aceitas por todo comando de pintura, exceto erase: como a cor da tinta se combina com os pixels que já estão lá. As opções omitidas vêm do contexto de edição (ink, shades). Com ink = "shading", a cor é ignorada e cada pixel tocado cuja cor esteja em `shades` avança um passo ao longo dessa lista (uma vez por comando, por mais que a forma o cubra).
Aceito por: `app.drawContour`, `app.drawCurve`, `app.drawEllipse`, `app.drawGradient`, `app.drawHexagon`, `app.drawIsoShape`, `app.drawLine`, `app.drawPolygon`, `app.drawRectangle`, `app.drawStar`, `app.drawStroke`, `app.drawTriangle`, `app.floodFill`, `app.scatter`, `app.spray`.

  - `ink` (Ink: "copy" | "simple" | "lock-alpha" | "shading"; padrão context.ink) — copy substitui os pixels, simple faz composição alfa, lock-alpha recolore apenas os pixels visíveis, shading avança as cores ao longo de `shades`. Ignorado por erase.
  - `shades` (a list of colors ("#rrggbb[aa]" or { r, g, b, a }), in ramp order; padrão context.shades) — A rampa ao longo da qual shading avança. Um pixel cuja cor não está na lista não é tocado; um pixel no fim da lista permanece ali.
  - `shadeReverse` (boolean; padrão false) — Shading avança para trás em `shades` (o botão direito do mouse na interface) em vez de para a frente.