# API di scripting Lua di pxstud.io — Documento > 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. ### Documento Lo sprite nel suo insieme: parti da app.describe(), poi dimensioni, ritaglio, rotazione e modalità colore. #### `app.convertColorMode(colorMode, opts?)` — modifica, annullabile Converte lo sprite tra le modalità colore (rgba, grayscale, indexed), con dithering e generazione di una palette facoltativi quando si passa a indexed. - `colorMode` (ColorMode: "rgba" | "grayscale" | "indexed") — Le conversioni da rgba (e verso grayscale) sono con perdita: il colore viene quantizzato sulla voce di palette più vicina o sulla luma Rec. 709 (quella di Aseprite, troncata: il rosso è 54). Verso grayscale la palette diventa di 256 grigi, dal nero al bianco (le palette per fotogramma e i gruppi di palette spariscono, l'indice trasparente diventa 0). Nessun effetto se lo sprite è già in quella modalità. - `opts` (table, facoltativo) - `dithering` (DitherMethod: "none" | "bayer2" | "bayer4" | "bayer8" | "floydSteinberg" | "atkinson"; predefinito "none") — Solo verso indexed: come vengono approssimati i colori tra le voci della palette. - `ditherAmount` (integer 0–100; predefinito 100) — Solo verso indexed: intensità del dithering (0 = solo il colore più vicino). - `paletteColors` (integer 1–256; predefinito keep the current palette) — Solo verso indexed: sostituisce la palette con questo numero di colori generati dallo sprite (più una voce trasparente all'indice 0, a meno che lo Sfondo sia l'unico livello; le palette per fotogramma vengono scartate). Non restituisce nulla. #### `app.cropToSelection()` — modifica, annullabile Ritaglia la tela ai limiti della selezione corrente; una selezione che esce dalla tela la ingrandisce in quel punto. Nessun effetto se non c'è nulla di selezionato. Non restituisce nulla. #### `app.describe()` — legge Tutto sulla struttura del documento in una sola chiamata (senza dati dei pixel): { sprite, activeLayerId, activeFrameId, layers, frames, cels, tags, slices, selection (limiti o nil), context }, ogni parte nella forma della sua query (app.getSprite, app.getLayers, ...). Parti da qui per vedere con cosa stai lavorando. Restituisce (table): Tabella del documento. #### `app.flip(axis, layerId?)` — modifica, annullabile, rifiutata su un livello bloccato Specchia l'intera tela, oppure un livello (anche i discendenti di un gruppo) su ogni fotogramma: pixel e posizioni dei cel, tile dei tilemap, immagini di riferimento. A differenza di app.flipCelRegion ignora la selezione. - `axis` (FlipAxis: "horizontal" | "vertical") - `layerId` (string, facoltativo) — Il livello (o gruppo) da capovolgere su ogni fotogramma. Omettilo per capovolgere l'intera tela: ogni livello, ogni fotogramma, gli slice e la selezione. Non restituisce nulla. #### `app.getCanvasHeight()` — legge L'altezza della tela dello sprite in pixel. Restituisce (number): Altezza in pixel. #### `app.getCanvasWidth()` — legge La larghezza della tela dello sprite in pixel. Restituisce (number): Larghezza in pixel. #### `app.getColorMode()` — legge La modalità colore dello sprite: "rgba", "grayscale" o "indexed". Restituisce (string): "rgba", "grayscale" o "indexed". #### `app.getSprite()` — legge Lo sprite: { id, width, height, colorMode ("rgba" | "grayscale" | "indexed"), palette (stringhe hex), transparentIndex (sprite indicizzati: l'indice della tavolozza i cui pixel sono trasparenti), pixelRatio ({ w, h }; 1:1 = pixel quadrati), colorDepth (livelli per canale: { kind = "rgb", red, green, blue } o { kind = "gray", gray }, con profile; nil per il colore pieno), layerCount, frameCount }. Restituisce (table): Tabella dello sprite. #### `app.newSprite(width, height, background?)` — modifica, annullabile Sostituisce l'intero documento con uno sprite nuovo di zecca (un livello, un fotogramma; un livello Sfondo se viene dato un colore di sfondo). Scarta il contenuto del documento corrente. - `width` (number) — Larghezza della tela in pixel. - `height` (number) — Altezza della tela in pixel. - `background` (color, facoltativo) — Colore di riempimento di un livello Sfondo. Se omesso, si ottiene invece un "Layer 1" trasparente. Restituisce (table): { layerId, frameId } dell'unico livello e dell'unico fotogramma del nuovo sprite. #### `app.rotateCanvas(degrees)` — modifica, annullabile Ruota l'intera tela (ogni livello, ogni fotogramma) in senso orario (90), antiorario (-90) o di 180 gradi. - `degrees` (number) — 90, -90 o 180. Non restituisce nulla. #### `app.setCanvasSize(width, height, anchor)` — modifica, annullabile Ridimensiona la tela, riposizionando (senza ricampionare) il contenuto esistente rispetto ad `anchor`. Il contenuto rimasto oltre il nuovo bordo viene conservato lì (solo il livello Sfondo viene tagliato), quindi riallargando la tela lo si recupera. - `width` (number) - `height` (number) - `anchor` (CanvasAnchor: "top-left" | "top" | "top-right" | "left" | "center" | "right" | "bottom-left" | "bottom" | "bottom-right") Non restituisce nulla. #### `app.setPixelRatio(w, h)` — modifica, annullabile Imposta le proporzioni del pixel dello sprite (Proprietà dello sprite > Proporzioni del pixel di Aseprite), ad es. 2, 1 per pixel larghi il doppio dell'altezza. Cambiano solo la visualizzazione e le esportazioni che ne tengono conto, non i pixel. - `w` (number) — Larghezza del pixel, un intero positivo (1:1 = quadrato). - `h` (number) — Altezza del pixel, un intero positivo. Non restituisce nulla. #### `app.setSpriteSize(width, height)` — modifica, annullabile Ricampiona ogni cel (nearest-neighbor) per adattarlo a una nuova dimensione dello sprite. - `width` (number) - `height` (number) Non restituisce nulla. #### `app.setUserData(target, userData?)` — modifica, annullabile Imposta i dati utente (etichetta colore, testo e proprietà personalizzate, come in Aseprite) di uno sprite, livello, cel, tag, slice o tileset. Un cel di destinazione può essere un fotogramma di tilemap. I cel collegati condividono gli stessi dati utente, come la loro immagine. Cambia solo ciò che indichi, quindi impostare il testo mantiene il colore, e scrivere lo spazio dei nomi properties della tua estensione lascia intatti quelli degli altri (come in Aseprite layer.data, layer.color e layer.properties(ns) sono separati). Rileggili da app.getSprite, getLayers, getCels, getTags, getSlices o getTileset (il campo userData). Consentito sui livelli bloccati. - `target` (table) — Cosa annotare: { kind = "sprite" }, { kind = "layer", layerId }, { kind = "cel", layerId, frameId }, { kind = "tag", tagId }, { kind = "slice", sliceId } o { kind = "tileset", layerId }. - `kind` (UserDataKind: "sprite" | "layer" | "cel" | "tag" | "slice" | "tileset") — Che tipo di elemento. - `layerId` (string) — Per le destinazioni layer, cel e tileset. - `frameId` (string) — Per le destinazioni cel. - `tagId` (string) — Per le destinazioni tag. - `sliceId` (string) — Per le destinazioni slice. - `userData` (table, facoltativo) — Cosa cambiare: solo le parti che indichi. text = "" o color = "" cancella quella parte; in properties, ogni spazio dei nomi che nomini viene sostituito e uno impostato a {} viene rimosso, mentre gli altri restano. nil rimuove tutti i dati utente. - `color` (string) — L'etichetta colore come "#rrggbb" o "#rrggbbaa". Non accettata per i tag (il loro colore è Tag.color). - `text` (string) — Testo libero (il testo dei dati utente di Aseprite). - `properties` (namespaces to properties: { [""] = { score = 3 }, ["my-extension"] = { ... } }. Values are plain JSON: nil-free, finite numbers, strings, booleans, lists and tables. properties[""] is your own namespace (Aseprite's user properties).) — Proprietà personalizzate per spazio dei nomi. I valori tipizzati di Aseprite (uuid, fixed, point, ...) appaiono come tabelle con una chiave $type, ad es. { ["$type"] = "uuid", value = "..." }, e vengono riscritti come il tipo Aseprite. Non restituisce nulla. #### `app.trim()` — modifica, annullabile Ritaglia la tela a ciò che è disegnato su tutti i fotogrammi, come il Trim di Aseprite: i livelli visibili così come appaiono, ridotti rispetto alla trasparenza o a un bordo a tinta unita (come uno Sfondo opaco). Nessun effetto se non resta nulla da tagliare. Non restituisce nulla.