API di scripting

Tutte le funzioni stanno nella tabella globale app. Le chiamate sono sincrone dal punto di vista dello script. print(...) scrive nella console dello script, e app.config contiene i valori del modulo di configurazione dello script (sempre definita, vuota se non c'è alcun modulo). I colori sono stringhe "#rgb", "#rrggbb" / "#rrggbbaa" o tabelle { r, g, b, a }. Le coordinate sono pixel interi dello sprite con (0, 0) in alto a sinistra. Gli id di livelli, fotogrammi, tag e slice sono stringhe. Le tabelle Lua partono da 1, e una lista restituita di numeri 0/1 o RGBA è ordinata per righe.

• Inizia con app.describe(). Una sola chiamata restituisce la struttura dell'intero documento: livelli, fotogrammi, cel, tag, slice, selezione e contesto di modifica.
• Creare restituisce un id. app.addLayer, app.addFrame, app.addTag e simili restituiscono ciò che hanno creato, valido attraverso annulla e ripeti.
• Selezione e simmetria sono opzionali. Se ometti un colore o un pennello, lo compila il contesto di modifica. Selezione e simmetria sono opzionali: passa respectSelection = true e symmetry = app.getContext().symmetry.
• Un'esecuzione, un annullamento. Tutto ciò che uno script modifica è un unico passo di annullamento. I livelli bloccati vengono rifiutati.
• Nessun limite di tempo. Qualsiasi esecuzione può essere messa in pausa, anche a metà di un ciclo, ripresa, fermata, oppure fermata e annullata.
• Usa app.random, non math.random. app.random.new(seed) è un generatore con seed: lo stesso seed dà lo stesso risultato a ogni esecuzione (e a ogni ripeti), quindi gli script dovrebbero prendere un seed da app.config e preferirlo a math.random. app.random.hash(x, y, seed) produce rumore per pixel. Anche pairs() visita le chiavi di una tabella nello stesso ordine a ogni esecuzione, quindi iterare una tabella di colori non cambia il disegno.
• I cicli sui pixel passano da un'Image. app.getImage, poi img:getPixel / img:setPixel quante volte vuoi, poi un solo app.putImage. Ogni chiamata app.* è un viaggio verso l'editor; i metodi di un'Image no.
• Usa app.color, non analisi e miscelazione esadecimali fatte a mano. app.color.mix, adjust, ramp, shades, nearest e contrast lavorano in uno spazio percettivo (OKLab) e limitano il risultato a sRGB; analizzare "#rrggbb" con string.sub e fare la media dei canali dà risultati sporchi.
• In sandbox. Niente rete, file o caricamento di codice; uno script può toccare solo lo sprite aperto. Un'esecuzione ha un budget di memoria (le sue Image, i suoi dati Lua, ciò che aggiunge al documento e alla cronologia di annullamento): oltre quel limite lo script viene fermato con un errore e ciò che ha fatto fino a quel momento resta come un unico passo di annullamento. app.apiVersion indica a uno script su quale versione di questa API sta girando.

Sezioni

• Gruppi di opzioni: Le opzioni di pittura e di pennello condivise dalle funzioni di disegno, definite una sola volta.
• Documento: Lo sprite nel suo insieme: parti da app.describe(), poi dimensioni, ritaglio, rotazione e modalità colore. (15 funzioni)
• Disegno: Gli strumenti dell'editor come comandi: gli strumenti dell'interfaccia eseguono esattamente questi. Colore, pennello e opzioni dello strumento che ometti vengono dal contesto di modifica. Il disegno ignora la selezione e la simmetria a meno che tu non passi respectSelection = true e symmetry = app.getContext().symmetry. (24 funzioni)
• Regolazioni: Le regolazioni del colore e gli effetti colore del menu Filtro, ciascuno un unico passo di annullamento sui cel di un livello nei fotogrammi che elenchi. Ignorano la selezione a meno che tu non passi respectSelection = true e non toccano mai i pixel completamente trasparenti. Negli sprite indicizzati indexedMode sceglie tra agganciare i pixel ricolorati alla voce di palette più vicina ("remap") e modificare le voci di palette usate dai cel ("palette"). (16 funzioni)
• Image: Il modo veloce di lavorare pixel per pixel. app.getImage legge un cel (o una sua parte) in un'Image, un buffer di pixel che vive dentro lo script: img:getPixel e img:setPixel non escono mai dallo script, quindi un ciclo su ogni pixel di un cel di 512 x 512 richiede circa un decimo di secondo. app.putImage lo riscrive come un'unica modifica, qualunque sia il numero di pixel impostati. Un pixel è un intero impacchettato (app.pixelColor.rgba(r, g, b, a), come in Aseprite); setPixel accetta anche "#rrggbb[aa]" e { r, g, b, a } (l'alfa è 255 per impostazione predefinita). Negli sprite indicizzati img:getIndex e img:setIndex lavorano con gli indici della palette, così i colori duplicati restano distinti. Lo schema abituale: local img = app.getImage(layer, frame); for y = 0, img.height - 1 do for x = 0, img.width - 1 do img:setPixel(x, y, ...) end end; app.putImage(layer, frame, img). (17 funzioni)
• Pixel: Lettura e scrittura di pixel come liste RGBA piatte (costruite sulle Image; mai ritagliate sulla selezione né specchiate), riempimenti e capovolgimenti dell'intera selezione, e il contagocce. (7 funzioni)
• Selezione: Le forme di selezione si combinano con la selezione attuale (sostituisci, aggiungi, sottrai, interseca). La maschera di selezione è leggibile e scrivibile. (19 funzioni)
• Livelli: Crea, organizza e configura i livelli. I gruppi sono cartelle di livelli: il parentId di un livello indica il suo gruppo (nil al livello superiore) e le posizioni di app.moveLayer contano all'interno di un gruppo (0 = in basso). Nascondere o bloccare un gruppo nasconde o blocca tutto ciò che contiene. Un gruppo con opacità piena e modalità di fusione "normal" è pass-through (i suoi livelli si fondono direttamente con ciò che sta sotto) a meno che il suo flag isolated sia attivo; un gruppo isolato, o con qualsiasi altra opacità o modalità, compone prima i suoi livelli tra loro. (25 funzioni)
• Fotogrammi e tag: La timeline: i fotogrammi, le loro durate e i tag di animazione. (25 funzioni)
• Cel: Un cel è l'immagine di un livello in un fotogramma. Spostali, cancellali e collegali a blocchi. (9 funzioni)
• Tilemap: I livelli tilemap posizionano su una griglia i tile del proprio tileset. I tile sono numerati a partire da 1 (0 è il tile vuoto). (19 funzioni)
• Palette: La palette dello sprite. (21 funzioni)
• Slice: Rettangoli con nome, ad esempio per le regioni di esportazione o gli hitbox. Uno slice può anche essere un 9-slice (un rettangolo centrale) e avere un punto di perno; entrambi sono relativi all'angolo in alto a sinistra dello slice, come in Aseprite, e si spostano con esso quando la tela viene ridimensionata, ritagliata o ruotata. (5 funzioni)
• Pennelli: Definisci i tuoi pennelli con un nome, poi dipingi con loro. Esistono solo nel motore per la durata della sessione: non fanno parte del documento, non si possono annullare, non vengono salvati e sono separati dalla libreria dei pennelli dell'editor. (6 funzioni)
• 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. (3 funzioni)
• Casuale: Numeri casuali con seme, calcolati all'interno dello script (nessun viaggio di andata e ritorno per chiamata). Lo stesso seme dà gli stessi risultati, quindi uno script può essere rieseguito, annullato e ripetuto, o condiviso, e produrre lo stesso aspetto. Preferiscile a math.random, che cambia a ogni esecuzione. I generatori sono oggetti: chiama i loro metodi con i due punti (rng:int(1, 6)). (11 funzioni)
• Colore: Calcoli sui colori senza dover analizzare a mano l'esadecimale né mescolare l'RGB. I colori in ingresso sono stringhe "#rrggbb" / "#rrggbbaa" o tabelle { r, g, b, a } (0-255, a facoltativo); i colori in uscita sono tabelle { r, g, b, a }, a meno che il nome non indichi hex. Miscelazione e regolazione usano OKLab come predefinito, uno spazio percettivo in cui passi uguali appaiono uguali; `space` può essere "oklab", "oklch", "rgb" o "hsl". I risultati vengono limitati a sRGB riducendo la chroma, così tonalità e luminosità restano invariate. Le liste (ramp, shades) si costruiscono con una sola chiamata. (11 funzioni)
• Dialoghi e comandi: UI per gli script, sul modello di Aseprite: Dialog{ title = ... } costruisce una finestra a partire da widget (label, entry, number, slider, check, radio, combobox, color, shades, button, separator, file) e plugin:newCommand aggiunge comandi ai menu, alla palette dei comandi e all'editor delle scorciatoie da tastiera. La finestra è disegnata dall'editor, solo come testo, con una barra del titolo che nomina lo script e la contrassegna come "script". Le callback (onclick, onchange, onclose) girano nello script, una alla volta, ciascuna come un unico passo di annullamento; uno script con un dialogo aperto resta vivo, inattivo, mentre l'utente continua a disegnare, e fermarlo chiude i suoi dialoghi. Non supportati: widget canvas e dlg:repaint. (18 funzioni)
• Moduli di configurazione: Il modulo che uno script dichiara prima dell'esecuzione: campi numero, testo, casella, selezione, colore, pennello e palette.
• Impostazioni del contesto: I colori, il pennello e le opzioni degli strumenti usati per impostazione predefinita dai comandi di disegno, più l'interruttore di simmetria dell'interfaccia (solo informativo).
• Tipi: Ogni insieme di valori con nome (FillMode, BlendMode, SymmetryAxis, ...), con ogni valore spiegato.
• Lettura del documento: Come uno script legge ogni parte del modello del documento.
• Comandi interni: Comandi del motore che gli script non possono chiamare, e perché.
• Resta nell'editor: Ciò che uno script non può raggiungere: zoom, pannelli, riproduzione, salvataggio.

In Markdown: scripting.md; tutta la documentazione in un solo file: llms-full.txt.