# API di scripting Lua di pxstud.io — Contesto di modifica

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

### Contesto di modifica
I colori, il pennello, la simmetria e le opzioni degli strumenti correnti, condivisi con la barra degli strumenti dell'editor. I comandi di disegno li usano per colori, pennello e opzioni degli strumenti che non vengono passati; la simmetria è solo informativa e viene applicata solo se la passi.

#### `app.getContext()` — legge
Il contesto di modifica: le impostazioni che i comandi di disegno usano per colori, pennello e opzioni degli strumenti che non passi, condivise con la barra degli strumenti dell'interfaccia. symmetry è l'interruttore di simmetria della barra degli strumenti, leggibile qui ma NON applicato implicitamente ai comandi: passa symmetry = app.getContext().symmetry a un comando di disegno per seguirlo. Campi: { 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 }. I colori sono tabelle { r, g, b, a }; symmetry è un array di assi; customBrush è { width, height, mask (elenco piatto di 0/1) } o nil. Modificalo con app.setContext.

Restituisce (table): Tabella del contesto.

#### `app.setContext(props)` — modifica
Cambia il contesto di modifica: i colori, il pennello, la simmetria, la modalità tilemap e le opzioni degli strumenti correnti. I comandi di disegno li usano per le opzioni che non vengono passate, tranne symmetry, che viene solo memorizzata per l'interfaccia (e leggibile tramite app.getContext) e non viene mai applicata a un comando se non la passi. Condiviso con l'interfaccia: la barra degli strumenti mostra la modifica, che resta anche dopo la fine dello script. Non è una modifica annullabile.

- `props` (table) — Le chiavi omesse restano invariate.
  - `foregroundColor` (color ("#rgb", "#rrggbb[aa]" or { r, g, b, a })) — Il colore di pittura: il `color` di ogni comando di disegno e il colore iniziale del gradiente.
  - `backgroundColor` (color ("#rgb", "#rrggbb[aa]" or { r, g, b, a })) — Il colore secondario: il colore finale del gradiente e ciò che scambia swapColors.
  - `brushSize` (integer 1–64) — Dimensione del pennello in pixel per le forme integrate (ignorata da un pennello personalizzato). Imposta anche il raggio dello spray (2x la dimensione).
  - `brushShape` (BrushShape: "circle" | "square" | "line" | "diamond" | "cross" | "x" | "star" | "horizontal" | "custom") — "line" è una linea di 1px inclinata da `brushAngle`; "square" viene ruotato da esso; "circle", "diamond", "cross", "x" e "star" lo ignorano; "horizontal" è una linea ad angolo 0 che lo ignora; "custom" dipinge `customBrush`.
  - `brushAngle` (integer 0–180) — Angolo del pennello in gradi (0-180): inclina il pennello "line" e ruota il pennello "square". Ignorato dalle altre forme.
  - `customBrush` ({ width, height, mask } with mask a flat list of 0/1, or false to clear) — La maschera che dipinge un pennello personalizzato: { rows = { ".#.", "###", ".#." } } oppure { width, height, mask } con mask una lista piatta di 0/1. Di norma si imposta con app.useBrush(name) da un pennello definito con app.defineBrush. Senza maschera, un pennello personalizzato dipinge un punto di 1px.
  - `pixelPerfect` (boolean) — Rimuove i gradini d'angolo doppi dai tratti a mano libera (con qualsiasi dimensione del pennello); il pennello viene stampato lungo il percorso corretto.
  - `eraserRightClick` (EraserRightClick: "background" | "replace") — Tasto destro della gomma: "background" dipinge il colore di sfondo ovunque passi, "replace" trasforma in colore di sfondo solo i pixel del colore di primo piano (Aseprite).
  - `ink` (Ink: "copy" | "simple" | "lock-alpha" | "shading") — Come la pittura (tratti, spray, forme, linee, poligono, contorno, secchiello, gradiente, fillSelection) si combina con i pixel esistenti: "copy" li sostituisce (predefinito), "simple" fa l'alpha-compositing, "lock-alpha" ricolora solo i pixel visibili, "shading" fa avanzare i pixel lungo `shades`.
  - `shades` (a list of colors ("#rrggbb[aa]" or { r, g, b, a }), in order) — La rampa lungo cui avanza l'inchiostro shading, in ordine: il riquadro Sfumature dell'editor (o l'intervallo di palette selezionato). I comandi di disegno la usano quando l'inchiostro è shading.
  - `stabilizer` (integer 0–64) — Forza dello stabilizzatore per i tratti a mano libera: ogni punto viene mediato con i N precedenti, attenuando il tremolio (il tratto resta indietro rispetto al cursore). 0 = disattivato.
  - `pressureSize` (boolean) — Lascia che la pressione della penna (il mouse conta come pressione piena) controlli la dimensione del pennello, da dynamicsMinSize fino a brushSize.
  - `pressureAngle` (boolean) — Lascia che la pressione della penna (il mouse conta come pressione piena) controlli l'angolo del pennello, da dynamicsMinAngle a dynamicsMaxAngle.
  - `pressureGradient` (boolean) — Lascia che la pressione della penna (il mouse conta come pressione piena) sfumi il colore da foregroundColor a backgroundColor lungo il tratto.
  - `pressureMin` (integer 0–100) — Lettura (in percentuale) del sensore di pressione che corrisponde all'estremo basso. Se maggiore di pressureMax inverte la corrispondenza.
  - `pressureMax` (integer 0–100) — Lettura (in percentuale) del sensore di pressione che corrisponde all'estremo alto.
  - `velocitySize` (boolean) — Lascia che la velocità del puntatore controlli la dimensione del pennello, da dynamicsMinSize fino a brushSize.
  - `velocityAngle` (boolean) — Lascia che la velocità del puntatore controlli l'angolo del pennello, da dynamicsMinAngle a dynamicsMaxAngle.
  - `velocityGradient` (boolean) — Lascia che la velocità del puntatore sfumi il colore da foregroundColor a backgroundColor lungo il tratto.
  - `velocityMin` (integer 0–100) — Lettura (in percentuale) del sensore di velocità che corrisponde all'estremo basso. Se maggiore di velocityMax inverte la corrispondenza.
  - `velocityMax` (integer 0–100) — Lettura (in percentuale) del sensore di velocità che corrisponde all'estremo alto.
  - `dynamicsMinSize` (integer 1–64) — Dimensione del pennello all'estremo basso di un sensore associato alla dimensione (l'estremo alto è brushSize).
  - `dynamicsMinAngle` (integer 0–180) — Angolo del pennello all'estremo basso di un sensore associato all'angolo.
  - `dynamicsMaxAngle` (integer 0–180) — Angolo del pennello all'estremo alto di un sensore associato all'angolo.
  - `dynamicsDither` (boolean) — Le dinamiche del gradiente scelgono foregroundColor o backgroundColor per ogni pixel (dithering ordinato) invece di sfumare. Negli sprite indexed le sfumature vengono agganciate al colore di palette più vicino.
  - `dynamicsCurve` (integer 25–400) — Curva di sensibilità in percentuale: il valore del sensore viene elevato a curve/100 (100 = lineare, sopra 100 servono più pressione/velocità per fare effetto).
  - `symmetry` (elenco di SymmetryAxis: "horizontal" | "vertical" | "diagonal" | "antidiagonal") — L'impostazione di simmetria dello sprite attivo (ogni sprite mantiene la sua, come la posizione dell'asse): assi di specchio passanti per il centro di simmetria. Solo informazione leggibile: i comandi di disegno non la applicano a meno che tu non passi symmetry = app.getContext().symmetry. Vuoto = disattivata; più assi si combinano (orizzontale + verticale = 4 vie).
  - `symmetryX` (a number (multiple of 0.5), or false to re-center) — Dove si trova l'asse di simmetria 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). nil = centrato. Come symmetry, solo informazione leggibile: passa symmetryX = app.getContext().symmetryX a un comando di disegno per seguirla. Imposta false per ricentrare.
  - `symmetryY` (a number (multiple of 0.5), or false to re-center) — Dove si trova l'asse di simmetria orizzontale (e l'incrocio delle diagonali): pixel dal bordo superiore della tela, multiplo di 0.5. nil = centrato. Imposta false per ricentrare.
  - `tilemapMode` (TilemapEditMode: "tiles" | "pixels-edit" | "pixels-auto") — Come la pittura a pixel tratta un livello tilemap: "pixels-auto" dà a ogni cella dipinta il suo tile, "pixels-edit" modifica sul posto il tile condiviso (ogni posizionamento si aggiorna), "tiles" consente solo di timbrare tile interi.
  - `shapeFillMode` (FillMode: "outline" | "filled") — Rettangoli, ellissi, poligoni e curve chiuse: contorno o riempiti.
  - `cornerRadius` (an integer 0–1024 for every corner, or a list of four { topLeft, topRight, bottomRight, bottomLeft }) — Rettangolo: raggi degli angoli in pixel, in senso orario dall'alto a sinistra (0 = angolo vivo), ciascuno limitato alla metà del lato più corto.
  - `selectionCornerRadius` (an integer 0–1024 for every corner, or a list of four { topLeft, topRight, bottomRight, bottomLeft }) — Selezione rettangolare: raggi degli angoli in pixel, in senso orario dall'alto a sinistra (0 = angolo vivo).
  - `cornerRadiusLinked` (boolean) — La barra delle opzioni dello strumento modifica insieme tutti e quattro i raggi degli angoli (un solo campo Raggio) invece di un campo per angolo.
  - `lineWidth` (integer 1–64) — Strumenti Linea e Curva: spessore in pixel (1 = linea netta di 1px); le linee più larghe hanno estremità arrotondate.
  - `curvePixelPerfect` (boolean) — Strumento Curva: rimuove gli angoli a L che una curva di 1px raccoglie, per linee pixel art pulite.
  - `bucketFillMode` (BucketFillMode: "contiguous" | "global") — Riempimento: solo la regione connessa, o ogni pixel corrispondente.
  - `bucketTolerance` (integer 0–255) — Riempimento: la massima differenza per canale che conta ancora come lo stesso colore.
  - `bucketCloseGap` (integer 0–5) — Riempimento (contiguo): considera chiusi i varchi nel contorno larghi fino a questo numero di pixel, così il riempimento non ci passa attraverso. 0 = disattivato.
  - `bucketDiagonal` (boolean) — Riempimento (contiguo): si estende anche ai vicini diagonali (8-connessi), così la regione trabocca attraverso le linee diagonali di 1px.
  - `bucketStopAtGrid` (boolean) — Riempimento: limita la regione alla cella della griglia in cui cade il clic.
  - `bucketPattern` (FillPattern: "solid" | "checker" | "dither25" | "dither75" | "hstripes" | "vstripes" | "diagonal" | "grid" | "dots" | "bricks") — Riempimento: dipinge un motivo ripetuto a due colori (il colore di riempimento e l'altro tra primo piano/sfondo) invece di un colore pieno. "solid" = nessun motivo.
  - `wandFillMode` (BucketFillMode: "contiguous" | "global") — Bacchetta magica: solo la regione connessa, o ogni pixel corrispondente. Distinta da bucketFillMode del riempimento.
  - `wandTolerance` (integer 0–255) — Bacchetta magica: la massima differenza per canale che conta ancora come lo stesso colore. Distinta da bucketTolerance del riempimento.
  - `wandDiagonal` (boolean) — Bacchetta magica (contigua): si estende anche ai vicini diagonali (8-connessi), così la regione trabocca attraverso le linee diagonali di 1px.
  - `wandStopAtGrid` (boolean) — Bacchetta magica: limita la regione alla cella della griglia in cui cade il clic.
  - `sprayRate` (integer 1–64) — Spray: punti per ogni punto.
  - `scatterX` (integer 0–64) — Dispersione: quanto lontano ogni stampo può cadere a sinistra o a destra del percorso, in pixel.
  - `scatterY` (integer 0–64) — Dispersione: quanto lontano ogni stampo può cadere sopra o sotto il percorso, in pixel.
  - `scatterCount` (integer 1–16) — Dispersione: stampi posizionati a ogni passo lungo il percorso.
  - `blurStrength` (integer 1–4) — Sfocatura: raggio dell'intorno in pixel.
  - `jumbleStrength` (integer 0–100) — Mescola: probabilità percentuale che ogni pixel toccato venga rimescolato.
  - `dodgeBurnStrength` (integer 1–100) — Scherma/Brucia: di quanto si sposta la luminosità OKLCH di ogni pixel toccato (100 = metà del percorso da nero a bianco).
  - `dodgeBurnHueShift` (integer 0–60) — Scherma/Brucia: gradi di cui la tonalità OKLCH di ogni pixel toccato ruota verso il giallo caldo (scherma) o il blu freddo (brucia), mai oltre; 0 mantiene la tonalità.
  - `ditherPattern` (DitherPattern: "bayer2" | "bayer4" | "bayer8" | "dots" | "lines-h" | "lines-v" | "diagonal" | "noise") — Pennello dithering: il motivo ordinato con cui dipinge. I motivi si ripetono a partire dall'angolo in alto a sinistra dello sprite, quindi i tratti si allineano.
  - `ditherDensity` (integer 0–100) — Pennello dithering: la quota di pixel del motivo che dipinge, in percentuale (50 con bayer2 è una scacchiera).
  - `gradientType` (GradientType: "linear" | "radial") — Gradiente: una rampa dritta tra i punti, oppure che si irradia dal punto iniziale.
  - `gradientDithering` (GradientDithering: "none" | "bayer2" | "bayer4" | "bayer8" | "dots" | "lines-h" | "lines-v" | "diagonal" | "noise") — Gradiente: il motivo di dithering ordinato (none = rampa uniforme).
  - `gradientSnap` (GradientSnap: "free" | "palette") — Gradiente: sfumature libere, oppure solo colori della palette (ogni pixel prende il colore di palette più vicino; il dithering alterna colori di palette vicini).
  - `gradientColors` (GradientColors: "fg-bg" | "stops") — Gradiente: va dal colore di primo piano a quello di sfondo, oppure lungo gradientStops ("stops"; con meno di due punti ripiega su primo piano e sfondo).
  - `gradientStops` (a list of { color, position } (position 0-1, in order), or a list of colors spread evenly) — Gradiente: la rampa a più punti dal punto iniziale, come voci { color, position } (position 0-1, in ordine; due nella stessa posizione fanno un bordo netto). Un semplice elenco di colori viene distribuito in modo uniforme. Usato quando gradientColors è "stops"; la barra Punti dell'editor lo modifica.
  - `eyedropperSource` (EyedropperSource: "composite" | "layer") — Contagocce: campiona ciò che mostra la tela, oppure solo il livello attivo.
  - `tileIndex` (integer ≥ 0) — Timbro tile: il tile da posizionare, a base 1 (0 = il tile vuoto).
  - `tileFlipH` (boolean) — Timbro tile: capovolge orizzontalmente i tile posizionati.
  - `tileFlipV` (boolean) — Timbro tile: capovolge verticalmente i tile posizionati.
  - `tileRotate90` (boolean) — Timbro tile: ruota di 90° in senso orario i tile posizionati.
  - `tilePlace` (boolean) — Posiziona tile: su un livello tilemap, matita, gomma, linea, strumenti forma e secchiello posizionano il tile del timbro (lo cancellano, per la gomma) sulle celle che coprono invece di dipingere pixel.
  - `isoShape` (IsoShape: "box" | "ramp" | "stairs" | "pyramid" | "prism" | "cylinder" | "cone" | "sphere" | "dome") — Strumento Forma iso: il solido che disegna.
  - `isoWidth` (integer 1–1024) — Strumento Forma iso: impronta lungo x (in basso a destra), in unità iso (una riga della scalinata del bordo ciascuna).
  - `isoDepth` (integer 1–1024) — Strumento Forma iso: impronta lungo y (in basso a sinistra), in unità iso.
  - `isoHeight` (integer 0–1024) — Strumento Forma iso: altezza in pixel (0 = piatto).
  - `isoBevel` (integer 0–1024) — Strumento Forma iso: solo per i box, di quanti pixel vengono smussati i bordi superiori (0 = vivo).
  - `isoCap` (integer 2–4) — Strumento Forma iso: il tratto piatto ai vertici superiore e inferiore, 2 (pari), 3 (dispari) o 4 (multipli di quattro). È anche il passo di trascinamento W / D (2 unità con cap 4).
  - `isoStyle` (IsoShapeStyle: "filled" | "outline" | "filled-outline") — Strumento Forma iso: facce, contorno, oppure entrambi.
  - `isoHiddenEdges` (boolean) — Strumento Forma iso: disegna anche i bordi dietro il solido.
  - `isoDirection` (IsoDirection: "+x" | "-x" | "+y" | "-y") — Strumento Forma iso: in che direzione scende una rampa o una scala, oppure verso dove sono rivolte le pendenze di un prisma.
  - `isoAutoShade` (boolean) — Strumento Forma iso: ricava i cinque colori dal colore di primo piano lungo `shades` (true), oppure usa isoColors (false).
  - `isoColors` (a list of colors ("#rrggbb[aa]" or { r, g, b, a }), in order) — Strumento Forma iso: i colori usati quando isoAutoShade è disattivato, in ordine contorno, bordo interno, alto, sinistra, destra.

Non restituisce nulla.

#### `app.swapColors()` — modifica
Scambia i colori di primo piano e di sfondo (la X dell'interfaccia).

Non restituisce nulla.