Guida allo scripting

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 ti accompagna nella scrittura e nell'esecuzione di uno. Questa pagina tratta tutto ciò che sta attorno.

Il menu Script

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.

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 chiede prima i suoi valori. Mentre è in esecuzione, i controlli di esecuzione prendono il suo posto (più avanti).
• 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:

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 documenta ciascuna, generata dall'editor stesso, in sezioni:

• Drawing: gli strumenti come comandi (app.drawLine, app.floodFill, app.drawIsoShape...), Images per lavorare pixel per pixel e Pixels per elenchi piatti di pixel, riempimenti e contagocce;
• Document, Layers, Frames, Cels, Selection, Slices e Tilemaps;
• Palette, Adjustments e Brushes;
• aiuti: la matematica dei Color, numeri casuali con seme (Random) e il contesto di modifica (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:

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

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

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

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.