# API de scripts Lua de pxstud.io — Palette > Fait partie de la référence de scripts Lua de pxstud.io, dont la vue d'ensemble (https://pxstud.io/fr/docs/scripting.md) explique les conventions. Les groupes d'options et les types auxquels elle renvoie se trouvent dans https://pxstud.io/fr/docs/scripting/option-groups.md et https://pxstud.io/fr/docs/scripting/types.md. Tout dans un seul fichier (en anglais) : https://pxstud.io/llms-full.txt. L'index de tout le site (en anglais) : https://pxstud.io/llms.txt. ### Palette La palette du sprite. #### `app.addColorCycle(fromIndex, toIndex, opts?)` — modifie, annulable Ajoute une plage de cycle de couleurs (sprites indexés) : pendant la lecture, les couleurs de cette plage de la palette tournent. Les pixels ne changent pas ; utilise app.bakeColorCycles pour transformer le cycle en palettes par image. - `fromIndex` (number) — Premier index de palette de la plage en cycle. - `toIndex` (number) — Dernier index de palette de la plage (inclus). - `opts` (table, facultatif) - `direction` (string; par défaut "forward") — "forward" déplace chaque couleur vers l'index supérieur suivant, "reverse" vers l'index inférieur. - `framesPerStep` (integer 1–1000; par défaut 1) — Images de lecture par rotation d'un cran. Renvoie (string) : L'id du nouveau cycle. #### `app.bakeColorCycles(frames?)` — modifie, annulable Fige les cycles de couleurs en palettes par image (en ajoutant des images si besoin) pour que les exports comme le GIF reproduisent le cycle, puis supprime les cycles. Sprites indexés uniquement. - `frames` (number, facultatif) — Nombre total d'images de l'animation figée (au moins le nombre actuel) ; par défaut : une boucle complète des cycles. Les images sont ajoutées après la dernière. Ne renvoie rien. #### `app.cleanPalette(opts?)` — modifie, annulable Nettoie la palette : fusionne les couleurs en double et les couleurs proches dans leur première occurrence et retire les entrées inutilisées. Sur les sprites indexés, les pixels suivent leurs couleurs. - `opts` (table, facultatif) — { removeDuplicates = bool, removeUnused = bool, mergeDistance = 0-100 (delta E ; ~2 est à peine visible, 10 nettement différent), frameId = palette en vigueur pour cette image }. Chaque option est désactivée par défaut. Ne renvoie rien. #### `app.createPaletteChange(frameId, colors?)` — modifie, annulable Démarre une nouvelle palette à une image : cette image et les suivantes (jusqu'au changement suivant) résolvent les pixels indexés à travers elle. Les index des pixels ne changent pas. - `frameId` (string) — Image à laquelle la nouvelle palette commence (pas la première image). - `colors` (table, facultatif) — La palette à partir de cette image, un tableau de couleurs hexadécimales ; par défaut : une copie de la palette en vigueur à cet endroit. Ne renvoie rien. #### `app.createPaletteRamp(from, to, count?, space?, mode?, frameId?)` — modifie, annulable Génère une rampe de couleurs entre deux entrées de la palette (le Dégradé de palette d'Aseprite) : par défaut elle écrase les entrées entre les deux, ou avec le mode "insert" insère de nouvelles couleurs avant l'entrée la plus tardive. Sur les sprites indexés, une insertion décale les index des pixels pour que l'image ne change pas. Une seule étape annulable. - `from` (number) — Index de palette d'une extrémité de la rampe (à partir de 0). - `to` (number) — Index de palette de l'autre extrémité (à partir de 0). - `count` (number, facultatif) — Combien de couleurs insérer entre elles (1-256). Obligatoire pour le mode "insert" ; "replace" remplit chaque entrée entre les extrémités et l'ignore. - `space` (string, facultatif) — Espace d'interpolation : "oklab" (par défaut, perceptuellement régulier), "oklch", "rgb" ou "hsl". - `mode` (string, facultatif) — "replace" écrase les entrées entre les deux extrémités avec la rampe (le Dégradé de palette d'Aseprite ; les pixels ne sont pas touchés) ; "insert" ajoute `count` nouvelles couleurs avant l'extrémité la plus tardive. Par défaut : "replace" quand des entrées se trouvent entre les extrémités, sinon "insert". - `frameId` (string, facultatif) — Modifie la palette en vigueur à cette image (les palettes peuvent changer par image) ; par défaut : la palette de la première image. Sur les sprites indexés, "insert" ne décale que les pixels des images qui partagent cette palette. Ne renvoie rien. #### `app.getColorCycles()` — lit Les plages de cycle de couleurs d'un sprite indexé : { id, fromIndex, toIndex, direction, framesPerStep } chacune. Renvoie (table) : Tableau de tables de cycle de couleurs. #### `app.getPalette(frameId?)` — lit La palette sous forme de tableau de chaînes de couleur hexadécimales, "#rrggbb" ou, pour les entrées dont l'alpha est inférieur à 255, "#rrggbbaa", par ex. { "#ff0000", "#00ff0080", ... }. Passe un id d'image pour obtenir la palette de cette image. - `frameId` (string, facultatif) — Image dont lire la palette (les palettes peuvent changer par image) ; omets-la pour la palette de la première image. Renvoie (table) : Tableau de chaînes de couleur hexadécimales. #### `app.insertPaletteEntries(index, colors, frameId?)` — modifie, annulable Insère des entrées de palette à un index. Sur les sprites indexés, chaque pixel (et l'index transparent) suit son entrée, donc l'image ne change pas. - `index` (number) — Où va la première nouvelle entrée (à partir de 0 ; la longueur de la palette ajoute à la fin). - `colors` (table) — Tableau de chaînes de couleur hexadécimales, "#rrggbb" ou "#rrggbbaa", par ex. { "#ff0000", "#00ff0080" }. - `frameId` (string, facultatif) — Modifie la palette en vigueur à cette image (les palettes peuvent changer par image) ; par défaut : la palette de la première image. Ne renvoie rien. #### `app.movePaletteEntry(fromIndex, toIndex, frameId?)` — modifie, annulable Déplace une entrée de palette vers une nouvelle position. Sur les sprites indexés, chaque pixel suit sa couleur, donc l'image ne change pas. - `fromIndex` (number) — Index de palette actuel (à partir de 0). - `toIndex` (number) — Index où l'entrée doit se retrouver (à partir de 0). - `frameId` (string, facultatif) — Modifie la palette en vigueur à cette image (les palettes peuvent changer par image) ; par défaut : la palette de la première image. Ne renvoie rien. #### `app.remapColors(mappings, cels)` — modifie, annulable, refusée sur un calque verrouillé Remplace des couleurs exactes par d'autres couleurs sur un ensemble de cels : le remappage de l'Audit de palette. Sprites RGBA et en niveaux de gris. - `mappings` (table) — Tableau de { from = "#rrggbb", to = "#rrggbb" } (l'un ou l'autre peut porter un alpha, "#rrggbbaa") ; tous les remappages s'appliquent en même temps. - `cels` (table) — Tableau de { layerId = ..., frameId = ... } : les cels à recolorer (calques d'image). Ne renvoie rien. #### `app.removeColorCycle(cycleId)` — modifie, annulable Supprime un cycle de couleurs. - `cycleId` (string) Ne renvoie rien. #### `app.removePaletteChange(frameId)` — modifie, annulable Supprime le changement de palette à une image, qui réutilise alors la palette précédente. Les index des pixels ne changent pas. - `frameId` (string) — Image dont supprimer le changement de palette. Ne renvoie rien. #### `app.removePaletteEntries(indices, frameId?)` — modifie, annulable Retire des entrées de palette par index. Sur les sprites indexés, les pixels des entrées retirées deviennent transparents et tous les autres pixels (ainsi que l'index transparent) suivent leur entrée. - `indices` (table) — Tableau des index de palette à retirer (à partir de 0), par ex. { 3 } ou { 4, 5, 6 }. - `frameId` (string, facultatif) — Modifie la palette en vigueur à cette image (les palettes peuvent changer par image) ; par défaut : la palette de la première image. Ne renvoie rien. #### `app.setColorDepth(depth?)` — modifie, annulable Fixe le sprite sur une profondeur de couleur, comme une console qui ne peut afficher que certaines valeurs : les pixels, les tuiles et les palettes y sont ramenés maintenant (une seule étape d'annulation), et tout ce qui est dessiné ensuite y reste. nil la retire (la précision perdue ne revient pas). Relis-la avec app.getSprite().colorDepth. - `depth` (table, facultatif) — La profondeur de couleur en niveaux par canal, ou nil pour la retirer. n bits font 2^n niveaux (3 bits = 8). - `red` (integer 2–256) — Niveaux de rouge (avec green et blue). - `green` (integer 2–256) — Niveaux de vert. - `blue` (integer 2–256) — Niveaux de bleu. - `gray` (integer 2–256) — Niveaux de gris, au lieu du rouge, du vert et du bleu : chaque couleur devient un gris. - `profile` (string) — L'id du profil matériel qu'elle représente (par ex. "mega-drive"), affiché dans l'éditeur. Ne renvoie rien. #### `app.setPalette(colors, frameId?)` — modifie, annulable Remplace toute la palette du sprite emplacement par emplacement. Sur les sprites indexés, chaque pixel garde son index et affiche la nouvelle couleur à cet emplacement (une palette plus courte est complétée avec les anciennes couleurs des emplacements encore utilisés). Pour ajouter ou retirer des couleurs avec des pixels qui les suivent, utilise app.insertPaletteEntries / app.removePaletteEntries. - `colors` (table) — Tableau de chaînes de couleur hexadécimales, "#rrggbb" ou "#rrggbbaa" (alpha), par ex. { "#ff0000", "#00ff0080" }. - `frameId` (string, facultatif) — Modifie la palette en vigueur à cette image (les palettes peuvent changer par image) ; par défaut : la palette de la première image. Ne renvoie rien. #### `app.setPaletteEntry(index, color, frameId?)` — modifie, annulable Recolore une entrée de palette sur place. Sur les sprites indexés, chaque pixel qui utilise cette entrée affiche la nouvelle couleur. - `index` (number) — Entrée de palette à recolorer (à partir de 0). - `color` (string) — Couleur hexadécimale, "#rrggbb" (opaque) ou "#rrggbbaa" (avec alpha), par ex. "#ff0000" ou "#ff000080". - `frameId` (string, facultatif) — Modifie la palette en vigueur à cette image (les palettes peuvent changer par image) ; par défaut : la palette de la première image. Ne renvoie rien. #### `app.setPaletteGroups(groups)` — modifie, annulable Remplace les groupes de palette : des étiquettes nommées sur des plages d'index de palette. Elles étiquettent des emplacements, donc déplacer ou trier les couleurs ne déplace pas un groupe. - `groups` (table) — Tableau de { name = "Skin", from = 0, to = 3 } (index de palette à partir de 0, bornes incluses), triés par from et sans chevauchement. {} supprime tous les groupes. Ne renvoie rien. #### `app.setPaletteLock(locked)` — modifie, annulable Active ou désactive le Verrouillage de palette. Sprites RGBA uniquement (les sprites indexés peignent toujours avec les couleurs de la palette) ; enregistré avec le fichier. - `locked` (boolean) — true : chaque commande de dessin sur un sprite RGBA aligne les pixels qu'elle peint sur la couleur de palette la plus proche. Ne renvoie rien. #### `app.setTransparentIndex(index)` — modifie, annulable Définit l'index de couleur transparente du sprite indexé (Propriétés du sprite > Couleur transparente d'Aseprite). Seule la propriété change, pas les octets des pixels. - `index` (number) — Index de palette (0-255) dont les pixels sont transparents sur les sprites indexés (0 par défaut). Ne renvoie rien. #### `app.sortPalette(by, descending?, from?, to?, frameId?)` — modifie, annulable Trie la palette (ou la plage from..to) selon une propriété de couleur, dans l'ordre du tri de palette d'Aseprite : les entrées totalement transparentes d'abord dans les deux sens ; la teinte place les gris en premier (par valeur) en ordre croissant, en dernier en ordre décroissant ; la teinte, la saturation et la luminosité comparent des degrés et des pourcentages entiers (la saturation départage les égalités par la luminosité et inversement) ; la luminance pondère les canaux élevés au carré. Les égalités restantes gardent leur ordre. Sur les sprites indexés, chaque pixel suit sa couleur, donc l'image ne change pas. - `by` (string) — Clé de tri : "hue", "saturation", "brightness", "luminance", "red", "green", "blue" ou "alpha". - `descending` (boolean, facultatif) — Trie du plus grand au plus petit (false par défaut). - `from` (number, facultatif) — Premier index de palette à trier (à partir de 0, 0 par défaut). - `to` (number, facultatif) — Dernier index de palette à trier (inclus, par défaut : le dernier). - `frameId` (string, facultatif) — Modifie la palette en vigueur à cette image (les palettes peuvent changer par image) ; par défaut : la palette de la première image. Ne renvoie rien. #### `app.updateColorCycle(cycleId, props?)` — modifie, annulable Modifie la plage, la direction ou la vitesse d'un cycle de couleurs. - `cycleId` (string) - `props` (table, facultatif) - `fromIndex` (integer 0–255) — Premier index de palette de la plage. - `toIndex` (integer 0–255) — Dernier index de palette de la plage (inclus). - `direction` (string) — "forward" ou "reverse". - `framesPerStep` (integer 1–1000) — Images de lecture par rotation d'un cran. Ne renvoie rien.