# API di scripting Lua di pxstud.io — Gruppi di opzioni

> Parte del riferimento di scripting Lua di pxstud.io, la cui panoramica (https://pxstud.io/it/docs/scripting.md) ne spiega le convenzioni. I gruppi di opzioni e i tipi a cui rimanda sono in https://pxstud.io/it/docs/scripting/option-groups.md e https://pxstud.io/it/docs/scripting/types.md. Tutto in un unico file (in inglese): https://pxstud.io/llms-full.txt. L'indice dell'intero sito (in inglese): https://pxstud.io/llms.txt.

## Gruppi di opzioni
Insiemi di opzioni condivisi da più funzioni, definiti una sola volta qui. La tabella `opts` di una funzione indica quali gruppi accetta in più: "accetta anche Opzioni di pittura" significa che ogni opzione qui sotto è accettata, con lo stesso significato e gli stessi valori predefiniti, oltre a quelle proprie della funzione.

### Opzioni di pittura (`paint`)
Accettate da ogni comando che dipinge pixel (le funzioni di disegno e gli strumenti a tratto). Ognuna è opzionale. Di default un comando di disegno ignora la selezione e non specchia, qualunque cosa mostri l'editor in quel momento; attivali con respectSelection = true e symmetry = app.getContext().symmetry (o un elenco di assi). tilemapMode viene preso dal contesto di modifica.
Accettato da: `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; predefinito false) — Passa true per dipingere solo dentro la selezione corrente (leggila con app.getSelection / app.isSelected). Di default la selezione viene ignorata.
  - `symmetry` (elenco di SymmetryAxis: "horizontal" | "vertical" | "diagonal" | "antidiagonal"; predefinito none) — Assi di specchio passanti per il centro della tela (o per symmetryX / symmetryY); le combinazioni (orizzontale + verticale) danno una simmetria a 4 vie. Di default nessuno: passa symmetry = app.getContext().symmetry per seguire l'interruttore di simmetria dell'editor, oppure un elenco di assi come { "vertical" }.
  - `symmetryX` (number ≥ 0; predefinito the canvas center (width / 2)) — Dove si trova l'asse verticale (e il punto in cui si incrociano le due diagonali): pixel dal bordo sinistro della tela, multiplo di 0.5 (intero = tra due pixel, x.5 = al centro di un pixel). Limitato alla tela. Passa app.getContext().symmetryX per seguire la guida dell'editor (nil significa centrato).
  - `symmetryY` (number ≥ 0; predefinito the canvas center (height / 2)) — Dove si trova l'asse orizzontale (e l'incrocio delle diagonali): pixel dal bordo superiore della tela, multiplo di 0.5. Limitato alla tela.
  - `tilemapMode` (TilemapEditMode: "pixels-edit" | "pixels-auto"; predefinito context.tilemapMode) — Come un livello tilemap accetta la pittura a pixel: auto dà a ogni cella dipinta il suo tile, edit modifica sul posto il tile condiviso. Ignorato sui livelli immagine.

### Opzioni di posizionamento (`tilePlace`)
Ognuna è opzionale. Di default i tile vanno su ogni cella indicata, qualunque cosa mostri l'editor. Le celle specchiate ricevono il tile specchiato: un asse verticale alterna flipH, uno orizzontale flipV, uno diagonale lo traspone (rotate90 più un capovolgimento). Una cella su un asse mantiene il tile così com'è stato posizionato.
Accettato da: `app.fillTiles`, `app.stampTiles`.

  - `respectSelection` (boolean; predefinito false) — Passa true per saltare le celle senza pixel selezionati (anche un riempimento si ferma lì).
  - `symmetry` (elenco di SymmetryAxis: "horizontal" | "vertical" | "diagonal" | "antidiagonal"; predefinito none) — Posiziona anche sulle celle specchiate rispetto a questi assi (e alle loro combinazioni). Passa app.getContext().symmetry per seguire l'interruttore dell'editor.
  - `symmetryX` (number ≥ 0; predefinito the canvas center (width / 2)) — Dove si trova l'asse verticale, in pixel dal bordo sinistro della tela (multiplo di 0.5).
  - `symmetryY` (number ≥ 0; predefinito the canvas center (height / 2)) — Dove si trova l'asse orizzontale, in pixel dal bordo superiore della tela (multiplo di 0.5).

### Opzioni del pennello (`brush`)
Accettate dagli strumenti a tratto (drawStroke, blur, jumble). Passa un pennello integrato con dimensione e forma, oppure un pennello personalizzato per nome o inline.
Accettato da: `app.blur`, `app.dodgeBurn`, `app.drawStroke`, `app.jumble`, `app.scatter`.

  - `brushSize` (integer 1–64; predefinito context.brushSize) — Dimensione del pennello in pixel.
  - `brushShape` (BrushShape: "circle" | "square" | "line" | "diamond" | "cross" | "x" | "star" | "horizontal"; predefinito context.brushShape) — Forma del pennello. Per un pennello personalizzato usa `brush`.
  - `brushAngle` (integer 0–180; predefinito context.brushAngle) — Angolo del pennello in gradi: inclina la forma "line" (0 = orizzontale, 90 = verticale) e ruota "square".
  - `brush` (brush name, or an inline { rows } / { width, height, mask }) — Un pennello personalizzato: il nome di uno che hai definito con app.defineBrush, oppure una definizione inline. Sostituisce brushSize, brushShape e brushAngle.

### Opzioni dell'inchiostro (`ink`)
Accettate da ogni comando di pittura tranne erase: come il colore di pittura si combina con i pixel già presenti. Le opzioni omesse vengono dal contesto di modifica (ink, shades). Con ink = "shading" il colore viene ignorato e ogni pixel toccato il cui colore è in `shades` avanza di un passo lungo quell'elenco (una volta per comando, per quante volte la forma lo copra).
Accettato da: `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"; predefinito context.ink) — copy sostituisce i pixel, simple fa l'alpha-compositing, lock-alpha ricolora solo i pixel visibili, shading fa avanzare i colori lungo `shades`. Ignorato da erase.
  - `shades` (a list of colors ("#rrggbb[aa]" or { r, g, b, a }), in ramp order; predefinito context.shades) — La rampa lungo cui avanza shading. Un pixel il cui colore non è nell'elenco resta intatto; un pixel in fondo all'elenco resta lì.
  - `shadeReverse` (boolean; predefinito false) — Shading avanza all'indietro in `shades` (il tasto destro del mouse nell'interfaccia) invece che in avanti.