# Guida allo scripting

Scrivi script Lua che disegnano e modificano i tuoi sprite, esegui script e generatori della libreria e aggiungi finestre e comandi di menu tuoi.

_Le scorciatoie sono scritte per Windows e Linux. Su Mac, usa ⌘ Cmd dove c'è scritto Ctrl e ⌥ Option per Alt._

Gli script sono programmi Lua che lavorano sullo sprite aperto. Pilotano lo stesso motore
dell'editor: ogni strumento, livello, fotogramma, cel, tag, slice, tile e voce della palette che puoi
cambiare a mano, uno script può cambiarlo con il codice. Usali per generare disegni (alberi, rocce,
texture, campi di stelle), per ripetere una modifica noiosa o per aggiungere ai menu comandi tuoi.

Sei alle prime armi con lo scripting? [Il tuo primo script](https://pxstud.io/it/docs/scripting/first-script.md) ti accompagna nella
scrittura e nell'esecuzione di uno. Questa pagina tratta tutto ciò che sta attorno.

## Il menu Script

| Voce | Cosa fa |
| - | - |
| Script > Nuovo script... | Dà un nome a un nuovo script e lo apre nel pannello Script. |
| Script > Apri il mio script... | Elenca i tuoi script: scegline uno per aprirlo, oppure rinominalo o eliminalo. Gli ultimi cinque che hai aperto sono elencati nel menu sotto di esso. |
| Script > Sfoglia la libreria degli script... | La libreria di script: cerca, esegui, fai un fork e metti il cuore agli script condivisi, compresi i generatori ufficiali. Vedi [La libreria](https://pxstud.io/it/docs/manual/guides/library.md). |
| Script > Comandi degli script... | Installa nei menu i comandi dei tuoi script ([più avanti](https://pxstud.io/it/docs/scripting/guide.md#script-commands)). |
| Script > API di scripting | Apre il riferimento dell'[API di scripting](https://pxstud.io/it/docs/scripting.md) in una nuova scheda. |

Ognuna di queste voci è anche nella palette dei comandi (`Ctrl+K`).

## Il pannello Script

Il pannello **Script** si apre quando crei o apri uno script (nei layout predefiniti, agganciato a
destra della tela, così puoi vedere uno script mentre disegna; su un telefono, davanti ad essa).
Visualizza > Pannelli > Script lo mostra e lo nasconde, e una ricarica riapre lo script che avevi aperto
(la sua ultima bozza salvata). Ha un editor di codice con evidenziazione Lua, suggerimenti per ogni
funzione `app.` mentre scrivi e una descrizione quando ci passi sopra il puntatore. Sotto il codice,
un'area di output mostra ciò che lo script stampa e ogni errore.

![Il pannello Script che mostra il codice di uno script, con la sua barra degli strumenti in alto e il suo output stampato sotto](https://pxstud.io/scripting/images/first-script-panel.light.webp)

_Il pannello Script_

In alto, da sinistra a destra:

- **Il nome dello script.** Fai doppio clic per rinominare lo script. Un `*` significa che ci sono
  modifiche non salvate; accanto, "bozza" per uno script che non hai pubblicato, oppure la versione
  che stai modificando ("v2", "v2 · modificata").
- **Privato** o **Condiviso**: chi può vedere lo script nella libreria. Fai clic per cambiare.
- **Riferimento API di scripting** (il libro) apre il riferimento in una nuova scheda.
- **Esegui** (il pulsante play) esegue lo script sullo sprite attivo; uno script con un [modulo di
  configurazione](https://pxstud.io/it/docs/scripting/guide.md#config-forms) chiede prima i suoi valori. Mentre è in esecuzione, i controlli di
  esecuzione prendono il suo posto ([più avanti](https://pxstud.io/it/docs/scripting/guide.md#running-pausing-and-stopping)).
- **Salva bozza** (il dischetto) salva lo script in questo browser.
- **Pubblica** chiede una nota di rilascio facoltativa, poi salva lo script e lo pubblica come nuova
  versione.
- **Impostazioni script** (i cursori) apre le impostazioni dello script: i suoi tag, chi può
  vederlo, il suo modulo di configurazione e le sue versioni pubblicate.
- **Nascondi pannello** chiude il pannello. Lo script aperto resta elencato nel menu File, con gli
  sprite: scegline lì il nome per mostrare di nuovo il pannello.

Lo script di qualcun altro (aperto con **Visualizza codice** nella libreria) è di sola lettura. La
sua barra degli strumenti ha **Fai un fork** al posto di Salva bozza e Pubblica: copia lo script in
un nuovo script tuo da modificare.

## Eseguire, mettere in pausa e fermare

Uno script viene eseguito sullo sprite che stai guardando, e lo vedi disegnare mentre procede.
Per quanto cambi, un'esecuzione è **un solo passo di annullamento**: `Ctrl+Z` annulla l'intera
esecuzione.

Gli script **non hanno limiti di tempo**. Mentre uno è in esecuzione, i suoi controlli di esecuzione
ti permettono di interromperlo prima:

| Controllo | Cosa fa |
| - | - |
| **Pausa** / **Riprendi** | Ferma lo script dov'è, anche a metà di un ciclo, e prosegue più tardi. |
| **Ferma** | Termina lo script e mantiene ciò che ha fatto finora. |
| **Ferma e ripristina** | Termina lo script e annulla tutto ciò che ha modificato. |

Nel pannello Script sono piccoli pulsanti nella barra degli strumenti. Uno script eseguito dalla
libreria copre l'editor con una finestra che mostra il suo nome, il suo output e gli stessi tre
controlli, finché non termina.

Quando uno script fallisce, l'output mostra l'errore; nel pannello, la riga in cui è fallito viene
evidenziata. Uno script non può dipingere su un livello bloccato: il comando viene rifiutato e lo
script si ferma con un errore.

## Scrivere script

Ogni funzione è nella tabella `app`. L'[API di scripting](https://pxstud.io/it/docs/scripting.md) documenta ciascuna,
generata dall'editor stesso, in sezioni:

- [Drawing](https://pxstud.io/it/docs/scripting/drawing.md): gli strumenti come comandi (`app.drawLine`, `app.floodFill`,
  `app.drawIsoShape`...), [Images](https://pxstud.io/it/docs/scripting/images.md) per lavorare pixel per pixel e
  [Pixels](https://pxstud.io/it/docs/scripting/pixels.md) per elenchi piatti di pixel, riempimenti e contagocce;
- [Document](https://pxstud.io/it/docs/scripting/document.md), [Layers](https://pxstud.io/it/docs/scripting/layers.md),
  [Frames](https://pxstud.io/it/docs/scripting/frames.md), [Cels](https://pxstud.io/it/docs/scripting/cels.md),
  [Selection](https://pxstud.io/it/docs/scripting/selection.md), [Slices](https://pxstud.io/it/docs/scripting/slices.md) e
  [Tilemaps](https://pxstud.io/it/docs/scripting/tilemaps.md);
- [Palette](https://pxstud.io/it/docs/scripting/palette.md), [Adjustments](https://pxstud.io/it/docs/scripting/adjustments.md) e
  [Brushes](https://pxstud.io/it/docs/scripting/brushes.md);
- aiuti: la matematica dei [Color](https://pxstud.io/it/docs/scripting/color.md), numeri casuali con seme
  ([Random](https://pxstud.io/it/docs/scripting/random.md)) e il [contesto di modifica](https://pxstud.io/it/docs/scripting/context.md) (i colori,
  il pennello e le opzioni degli strumenti attuali).

Alcune cose da sapere:

- **Inizia con `print(app.describe())`.** `app.describe()` restituisce l'intera struttura dello
  sprite: livelli, fotogrammi, cel, tag, slice, la selezione e le impostazioni attuali.
- **Le impostazioni che ometti vengono dall'editor.** Un comando di disegno senza un colore usa il
  colore di primo piano; senza un pennello, il pennello attuale; e così via per ogni opzione degli
  strumenti.
- **La selezione e la simmetria si applicano solo quando le chiedi.** Passa `respectSelection = true`
  per continuare a dipingere dentro la selezione, e `symmetry = app.getContext().symmetry` per
  specchiare.
- **Lavora pixel per pixel in una Image.** `app.getImage(layer, frame)` legge un cel in una Image che
  vive dentro lo script; `img:getPixel` e `img:setPixel` costano poco, quindi cicla su quanti pixel
  vuoi, poi riscrivila una volta sola con `app.putImage(layer, frame, img)`. Ogni chiamata `app.*` è
  un viaggio fino all'editor, mentre i metodi di una Image no. Sugli sprite indicizzati,
  `img:getIndex` e `img:setIndex` lavorano con gli indici della palette.
- **Usa `app.random` per la casualità.** Un generatore creato con `app.random.new(seed)` dà gli
  stessi numeri per lo stesso seme, quindi un'esecuzione si può ripetere esattamente. Anche
  `pairs()` visita le chiavi di una tabella nello stesso ordine a ogni esecuzione.
- **Usa `app.color` per la matematica dei colori.** Miscele, rampe e sfumature sono calcolate in uno
  spazio colore percettivo, che ha un aspetto migliore della media dei valori esadecimali.
- **Stampa per controllare.** `print(...)` scrive nell'area di output; le tabelle vengono stampate
  per intero.

Per esempio, questo sparge delle stelle su un nuovo livello; cambia il seme per un cielo diverso:

```lua
local layer = app.addLayer("Stars")
local frame = app.getActiveFrameId()

local rng = app.random.new(42)                        -- stesso seme, stesse stelle
local colors = app.color.ramp({ "#5a6b9e", "#ffffff" }, 4)

local img = app.getImage(layer, frame)                -- i pixel del livello, dentro lo script
for i = 1, img.width * img.height // 40 do
  img:setPixel(rng:int(0, img.width - 1), rng:int(0, img.height - 1), rng:pick(colors))
end
app.putImage(layer, frame, img)                       -- riscritta come un'unica modifica
```

## Moduli di configurazione

Uno script può chiedere delle impostazioni prima di essere eseguito: quando scegli **Esegui** (nella
libreria, o nel pannello Script), si apre un modulo con i suoi campi (numeri, testo, caselle,
scelte, colori, e un pennello o una palette dalle tue librerie), e lo script legge ciò che hai
inserito come tabella `app.config`. I campi possono comparire o sparire in base alle scelte
precedenti. **Casuale** genera nuovi valori entro gli intervalli scelti dall'autore dello script,
per variazioni rapide. I generatori ufficiali funzionano tutti così.

Per dare un modulo a uno dei tuoi script, scrivilo come JSON in **Modulo di configurazione** nelle
impostazioni dello script, nella forma descritta dal riferimento sui [moduli di
configurazione](https://pxstud.io/it/docs/scripting/config-forms.md); le impostazioni ti dicono cosa non va prima di
salvare. Il modulo fa parte della bozza e di ogni versione pubblicata. Uno script dovrebbe comunque
leggere ogni campo come facoltativo e ripiegare sui propri valori predefiniti. Per l'input mentre
uno script è in esecuzione, apri invece una finestra dello script.

## Finestre degli script

Uno script può aprire una finestra tutta sua con `Dialog{}`, costruita come le costruiscono gli
script di Aseprite: etichette, caselle di testo e di numeri, cursori, caselle di controllo,
pulsanti di opzione, elenchi a discesa, campi colore, righe di campioni di colore, pulsanti e un
selettore di file (solo piccoli file di testo).

```lua
local dlg = Dialog{ title = "Quick Fill" }
dlg:color{ id = "paint", label = "Color", color = "#3a8f4a" }
dlg:button{ id = "fill", text = "Fill layer", onclick = function()
  local layer, frame = app.getActiveLayerId(), app.getActiveFrameId()
  app.floodFill(layer, frame, 0, 0, { color = dlg.data.paint })
end }
dlg:show{ wait = false }
```

- `dlg:show{ wait = false }` apre una **finestra fluttuante** e lo script aspetta, inattivo, mentre
  continui a disegnare; ogni pressione di pulsante o modifica a cui reagisce è un passo di
  annullamento a sé. Senza `wait = false`, la finestra è modale: l'editor è bloccato finché non la
  chiudi.
- La barra del titolo della finestra nomina lo script e la contrassegna come di uno script, e tutto
  al suo interno è testo semplice, quindi uno script non può spacciare la sua finestra per una parte
  dell'editor.
- Chiudere la finestra termina lo script; fermare lo script chiude le sue finestre.

Il riferimento [Dialogs and commands](https://pxstud.io/it/docs/scripting/dialogs.md) ha ogni widget e le sue opzioni.

## Comandi degli script

Uno script può aggiungere **comandi** ai menu dell'editor, nello stesso modo di un plugin di
Aseprite. Definisci una funzione `init(plugin)` che li registra con `plugin:newCommand`:

```lua
local function mirror()
  app.flip("horizontal", app.getActiveLayerId())
end

function init(plugin)
  plugin:newCommand{ id = "mirror", title = "Mirror Layer", group = "layer", onclick = mirror }
end
```

Salva lo script, poi scegli Script > Comandi degli script... e premi **Installa** accanto ad esso. Il comando
ora compare:

- nel menu che il suo `group` indica (`file`, `file_import`, `edit`, `edit_transform`, `edit_fx`,
  `edit_adjustments`, `sprite`, `layer`, `frame`, `select` o `view`), mostrato con il nome dello
  script; senza un gruppo, sotto Script, in un sottomenu con il nome dello script;
- nella palette dei comandi;
- in Impostazioni > Scorciatoie da tastiera..., dove puoi assegnargli una scorciatoia.

Eseguire il comando esegue il tuo script salvato e poi l'`onclick` del comando, come un solo passo di
annullamento. Dopo aver cambiato quali comandi registra uno script, premi **Reinstalla**; **Rimuovi**
li toglie dai menu. Uno script può aggiungere fino a 32 comandi. I comandi installati sono
conservati in questo browser.

Per installare i comandi dallo script di qualcun altro, fanne prima un fork nei tuoi script.

## Salvare e pubblicare

I tuoi script sono salvati in questo browser, come i tuoi sprite, e funzionano offline. Con
[Sync](https://pxstud.io/it/docs/manual/concepts/how-work-is-organized.md#where-things-are-kept), sono conservati anche nel
tuo account e sugli altri tuoi dispositivi.

**Pubblicare** condivide uno script nella libreria di script. Ogni script parte come **Privato**,
quindi solo tu puoi vederlo; scegli **Condiviso nella libreria** nelle sue impostazioni
(**Impostazioni script**, o il badge Privato) per elencarlo. Poi:

- **Salva bozza** mantiene private le tue modifiche. Chi usa la libreria ottiene sempre la tua
  ultima versione pubblicata, mai la bozza.
- **Pubblica** salva la bozza e la trasforma nella versione numerata successiva, con la nota di
  rilascio che scrivi (mostrata nella cronologia delle versioni). Le versioni pubblicate non
  cambiano mai; pubblica di nuovo per crearne una nuova.
- Le impostazioni dello script elencano ogni versione pubblicata. **Visualizza codice** ne apre una
  vecchia in sola lettura, e **Ripristina nella bozza** la copia nella tua bozza.
- Uno script può avere fino a 3 tag, che aiutano le persone a trovarlo nella libreria.

Pubblicare richiede un account con Sync su pxstud.io.
Eseguire, fare un fork e mettere il cuore agli script (con un account gratuito) è trattato in
[La libreria](https://pxstud.io/it/docs/manual/guides/library.md).

## Cosa non possono fare gli script

Gli script sono in una sandbox, quindi eseguire uno script scritto da qualcun altro è sicuro:

- **Niente rete, file né caricamento di codice.** Uno script non può raggiungere internet né i tuoi
  file (a parte un file di testo che scegli nella sua finestra), e non può caricare altro codice. Le
  librerie `io`, `os` e `debug` di Lua non ci sono; `string`, `math`, `table`, `utf8` e `coroutine`
  sì.

- **Solo lo sprite aperto.** Uno script modifica lo sprite su cui l'hai eseguito, come un solo
  passo di annullamento. Non può aprire, salvare, esportare, chiudere né eliminare sprite, usare gli
  appunti, né cambiare la vista e i pannelli.

- **Le tue librerie solo quando scegli da esse.** Uno script vede uno dei tuoi pennelli o delle tue
  palette salvati solo quando il suo modulo di configurazione lo chiede e tu lo scegli.

- **Un budget di memoria.** Un'esecuzione non può usare più di una certa quantità di memoria: per le
  sue Image, i suoi dati Lua, i pixel che aggiunge allo sprite e il passo di annullamento che
  costruisce. Oltre quel limite lo script viene fermato con un errore che dice quale, e ciò che ha
  fatto finora resta come un solo passo di annullamento, quindi uno script fuori controllo non può
  mandare in crash l'editor né spingere i tuoi passi precedenti fuori dalla cronologia modifiche.

Non c'è un limite di tempo; uno script fuori controllo si può sempre mettere in pausa o fermare.

## I generatori ufficiali

La libreria di script di pxstud.io ha un insieme di script ufficiali, contrassegnati come
**Ufficiale**: generatori di gradienti, scacchiere, riempimenti di rumore, muri di mattoni, ciottoli,
assi di legno, texture di erba e acqua, fulmini, tornado, arcobaleni, comete, galassie, pianeti,
stelle, alberi, cespugli e rocce. Accedi con un account gratuito, apri Script > Sfoglia la libreria degli script...,
scegli **Ufficiali** e premi **Esegui** su uno: compila il suo modulo (oppure premi **Casuale**) e
disegna sul tuo sprite. Fanne un fork per leggere come è fatto, o per cambiarlo.