# API de scripts Lua de pxstud.io — Contexte d'édition

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

### Contexte d'édition
Les couleurs, le pinceau, la symétrie et les options d'outils actuels, partagés avec la barre d'outils de l'éditeur. Les commandes de dessin s'en servent pour les couleurs, le pinceau et les options d'outils qu'on ne leur donne pas ; la symétrie est une simple information et n'est appliquée que si tu la passes.

#### `app.getContext()` — lit
Le contexte d'édition : les réglages que les commandes de dessin utilisent pour les couleurs, le pinceau et les options d'outils que tu ne passes pas, partagés avec la barre d'outils de l'interface. symmetry est l'interrupteur de symétrie de la barre d'outils, lisible ici mais PAS appliqué implicitement aux commandes : passe symmetry = app.getContext().symmetry à une commande de dessin pour la suivre. Champs : { foregroundColor, backgroundColor, brushSize, brushShape, brushAngle, customBrush, pixelPerfect, eraserRightClick, ink, shades, stabilizer, pressureSize, pressureAngle, pressureGradient, pressureMin, pressureMax, velocitySize, velocityAngle, velocityGradient, velocityMin, velocityMax, dynamicsMinSize, dynamicsMinAngle, dynamicsMaxAngle, dynamicsDither, dynamicsCurve, symmetry, symmetryX, symmetryY, tilemapMode, shapeFillMode, cornerRadius, selectionCornerRadius, cornerRadiusLinked, lineWidth, curvePixelPerfect, bucketFillMode, bucketTolerance, bucketCloseGap, bucketDiagonal, bucketStopAtGrid, bucketPattern, wandFillMode, wandTolerance, wandDiagonal, wandStopAtGrid, sprayRate, scatterX, scatterY, scatterCount, blurStrength, jumbleStrength, dodgeBurnStrength, dodgeBurnHueShift, ditherPattern, ditherDensity, gradientType, gradientDithering, gradientSnap, gradientColors, gradientStops, eyedropperSource, tileIndex, tileFlipH, tileFlipV, tileRotate90, tilePlace, isoShape, isoWidth, isoDepth, isoHeight, isoBevel, isoCap, isoStyle, isoHiddenEdges, isoDirection, isoAutoShade, isoColors }. Les couleurs sont des tables { r, g, b, a } ; symmetry est un tableau d'axes ; customBrush est { width, height, mask (liste plate de 0/1) } ou nil. Modifie-le avec app.setContext.

Renvoie (table) : Table du contexte.

#### `app.setContext(props)` — modifie
Modifie le contexte d'édition : les couleurs, le pinceau, la symétrie, le mode tilemap et les options d'outils actuels. Les commandes de dessin s'en servent pour les options qu'on ne leur donne pas, sauf symmetry, qui est seulement stockée pour l'interface (et lisible via app.getContext) et n'est jamais appliquée à une commande à moins que tu ne la passes. Partagé avec l'interface : la barre d'outils reflète le changement, qui persiste après la fin du script. Ce n'est pas une modification annulable.

- `props` (table) — Les clés omises ne changent pas.
  - `foregroundColor` (color ("#rgb", "#rrggbb[aa]" or { r, g, b, a })) — La couleur de peinture : le `color` de chaque commande de dessin, et la couleur de départ du dégradé.
  - `backgroundColor` (color ("#rgb", "#rrggbb[aa]" or { r, g, b, a })) — La couleur secondaire : la couleur de fin du dégradé, et ce qu'échange swapColors.
  - `brushSize` (integer 1–64) — Taille du pinceau en pixels pour les formes intégrées (ignorée par un pinceau personnalisé). Définit aussi le rayon de l'aérosol (2 fois la taille).
  - `brushShape` (BrushShape: "circle" | "square" | "line" | "diamond" | "cross" | "x" | "star" | "horizontal" | "custom") — "line" est une ligne de 1 px inclinée selon `brushAngle` ; "square" pivote selon lui ; "circle", "diamond", "cross", "x" et "star" l'ignorent ; "horizontal" est une ligne à l'angle 0 qui l'ignore ; "custom" peint `customBrush`.
  - `brushAngle` (integer 0–180) — Angle du pinceau en degrés (0-180) : incline le pinceau "line" et fait pivoter le pinceau "square". Ignoré par les autres formes.
  - `customBrush` ({ width, height, mask } with mask a flat list of 0/1, or false to clear) — Le masque que peint un pinceau personnalisé : { rows = { ".#.", "###", ".#." } } ou { width, height, mask } avec mask une liste plate de 0/1. Normalement défini avec app.useBrush(name) à partir d'un pinceau défini avec app.defineBrush. Sans masque, un pinceau personnalisé peint un point de 1 px.
  - `pixelPerfect` (boolean) — Supprime les marches d'angle en double des tracés à main levée (quelle que soit la taille du pinceau) ; le pinceau est estampé le long du chemin corrigé.
  - `eraserRightClick` (EraserRightClick: "background" | "replace") — Bouton droit de la gomme : "background" peint la couleur d'arrière-plan partout où elle passe, "replace" transforme uniquement les pixels de la couleur de premier plan en couleur d'arrière-plan (Aseprite).
  - `ink` (Ink: "copy" | "simple" | "lock-alpha" | "shading") — Comment la peinture (strokes, spray, shapes, lines, polygon, contour, bucket, gradient, fillSelection) se combine avec les pixels existants : "copy" les remplace (par défaut), "simple" fait une composition alpha, "lock-alpha" ne recolore que les pixels visibles, "shading" fait avancer les pixels dans `shades`.
  - `shades` (a list of colors ("#rrggbb[aa]" or { r, g, b, a }), in order) — La rampe que parcourt l'encre shading, dans l'ordre : la boîte Nuances de l'éditeur (ou la plage de palette sélectionnée). Les commandes de dessin l'utilisent quand ink vaut shading.
  - `stabilizer` (integer 0–64) — Force du stabilisateur pour les tracés à main levée : chaque point est moyenné avec les N points précédents, ce qui lisse les tremblements (le tracé suit le curseur avec un retard). 0 = désactivé.
  - `pressureSize` (boolean) — Laisse la pression du stylet (une souris compte comme une pression maximale) piloter la taille du pinceau, de dynamicsMinSize jusqu'à brushSize.
  - `pressureAngle` (boolean) — Laisse la pression du stylet (une souris compte comme une pression maximale) piloter l'angle du pinceau, de dynamicsMinAngle à dynamicsMaxAngle.
  - `pressureGradient` (boolean) — Laisse la pression du stylet (une souris compte comme une pression maximale) mélanger la couleur de foregroundColor à backgroundColor le long du tracé.
  - `pressureMin` (integer 0–100) — Valeur lue (en pourcentage) du capteur de pression qui correspond à la borne basse. Supérieure à pressureMax, elle inverse la correspondance.
  - `pressureMax` (integer 0–100) — Valeur lue (en pourcentage) du capteur de pression qui correspond à la borne haute.
  - `velocitySize` (boolean) — Laisse la vitesse du pointeur piloter la taille du pinceau, de dynamicsMinSize jusqu'à brushSize.
  - `velocityAngle` (boolean) — Laisse la vitesse du pointeur piloter l'angle du pinceau, de dynamicsMinAngle à dynamicsMaxAngle.
  - `velocityGradient` (boolean) — Laisse la vitesse du pointeur mélanger la couleur de foregroundColor à backgroundColor le long du tracé.
  - `velocityMin` (integer 0–100) — Valeur lue (en pourcentage) du capteur de vitesse qui correspond à la borne basse. Supérieure à velocityMax, elle inverse la correspondance.
  - `velocityMax` (integer 0–100) — Valeur lue (en pourcentage) du capteur de vitesse qui correspond à la borne haute.
  - `dynamicsMinSize` (integer 1–64) — Taille du pinceau à la borne basse d'un capteur associé à la taille (la borne haute est brushSize).
  - `dynamicsMinAngle` (integer 0–180) — Angle du pinceau à la borne basse d'un capteur associé à l'angle.
  - `dynamicsMaxAngle` (integer 0–180) — Angle du pinceau à la borne haute d'un capteur associé à l'angle.
  - `dynamicsDither` (boolean) — Les dynamiques de dégradé choisissent foregroundColor ou backgroundColor pixel par pixel (tramage ordonné) au lieu de mélanger. Dans les sprites indexés, les mélanges sont ramenés à la couleur de palette la plus proche.
  - `dynamicsCurve` (integer 25–400) — Courbe de sensibilité en pourcentage : la valeur du capteur est élevée à la puissance curve/100 (100 = linéaire ; au-dessus de 100, il faut plus de pression/vitesse pour qu'elle agisse).
  - `symmetry` (liste de SymmetryAxis: "horizontal" | "vertical" | "diagonal" | "antidiagonal") — Le réglage de symétrie du sprite actif (chaque sprite garde le sien, comme la position de son axe) : axes de symétrie passant par le centre de symétrie. Simple information lisible : les commandes de dessin ne l'appliquent pas à moins que tu ne passes symmetry = app.getContext().symmetry. Vide = désactivée ; plusieurs axes se combinent (horizontal + vertical = 4 axes).
  - `symmetryX` (a number (multiple of 0.5), or false to re-center) — Position de l'axe de symétrie vertical (et du point où se croisent les deux diagonales) : en pixels depuis le bord gauche du canevas, un multiple de 0.5 (entier = entre deux pixels, x.5 = au milieu d'un pixel). nil = centré. Comme symmetry, simple information lisible : passe symmetryX = app.getContext().symmetryX à une commande de dessin pour la suivre. Mets false pour recentrer.
  - `symmetryY` (a number (multiple of 0.5), or false to re-center) — Position de l'axe de symétrie horizontal (et du croisement des diagonales) : en pixels depuis le bord supérieur du canevas, un multiple de 0.5. nil = centré. Mets false pour recentrer.
  - `tilemapMode` (TilemapEditMode: "tiles" | "pixels-edit" | "pixels-auto") — Façon dont la peinture de pixels traite un calque tilemap : "pixels-auto" donne à chaque cellule peinte sa propre tuile, "pixels-edit" modifie sur place la tuile partagée (chaque placement est mis à jour), "tiles" n'autorise que l'estampage de tuiles entières.
  - `shapeFillMode` (FillMode: "outline" | "filled") — Rectangles, ellipses, polygones et courbes fermées : contour ou remplissage.
  - `cornerRadius` (an integer 0–1024 for every corner, or a list of four { topLeft, topRight, bottomRight, bottomLeft }) — Rectangle : rayons des coins en pixels, dans le sens horaire à partir du coin supérieur gauche (0 = coin droit), chacun limité à la moitié du plus petit côté.
  - `selectionCornerRadius` (an integer 0–1024 for every corner, or a list of four { topLeft, topRight, bottomRight, bottomLeft }) — Sélection de zone rectangulaire : rayons des coins en pixels, dans le sens horaire à partir du coin supérieur gauche (0 = coin droit).
  - `cornerRadiusLinked` (boolean) — La barre d'options de l'outil modifie les quatre rayons de coin ensemble (un seul champ Rayon) au lieu d'un champ par coin.
  - `lineWidth` (integer 1–64) — Outils Ligne et Courbe : épaisseur en pixels (1 = une ligne nette de 1 px) ; les lignes plus larges ont des extrémités arrondies.
  - `curvePixelPerfect` (boolean) — Outil Courbe : supprime les coins en L que prend une courbe de 1 px, pour des lignes de pixel art nettes.
  - `bucketFillMode` (BucketFillMode: "contiguous" | "global") — Pot de peinture : seulement la région connectée, ou tous les pixels correspondants.
  - `bucketTolerance` (integer 0–255) — Pot de peinture : la plus grande différence par canal qui compte encore comme la même couleur.
  - `bucketCloseGap` (integer 0–5) — Remplissage (contigu) : considère comme fermées les brèches du contour jusqu'à cette largeur en pixels, pour que le remplissage ne déborde pas. 0 = désactivé.
  - `bucketDiagonal` (boolean) — Pot de peinture (contigu) : se propage aussi aux voisins en diagonale (8-connexe), si bien que la région fuit à travers les lignes diagonales de 1 px.
  - `bucketStopAtGrid` (boolean) — Pot de peinture : confine la région à la cellule de la grille où tombe le clic.
  - `bucketPattern` (FillPattern: "solid" | "checker" | "dither25" | "dither75" | "hstripes" | "vstripes" | "diagonal" | "grid" | "dots" | "bricks") — Remplissage : peint un motif répétitif de deux couleurs (la couleur de remplissage et l'autre entre premier plan et arrière-plan) au lieu d'une couleur unie. "solid" = aucun motif.
  - `wandFillMode` (BucketFillMode: "contiguous" | "global") — Baguette magique : seulement la région connectée, ou tous les pixels correspondants. Distinct de bucketFillMode du pot de peinture.
  - `wandTolerance` (integer 0–255) — Baguette magique : la plus grande différence par canal qui compte encore comme la même couleur. Distincte de bucketTolerance du pot de peinture.
  - `wandDiagonal` (boolean) — Baguette magique (contigu) : se propage aussi aux voisins en diagonale (8-connexe), si bien que la région fuit à travers les lignes diagonales de 1 px.
  - `wandStopAtGrid` (boolean) — Baguette magique : confine la région à la cellule de la grille où tombe le clic.
  - `sprayRate` (integer 1–64) — Aérosol : points par position.
  - `scatterX` (integer 0–64) — Dispersion : distance maximale, en pixels, à gauche ou à droite du chemin où chaque estampage peut tomber.
  - `scatterY` (integer 0–64) — Dispersion : distance maximale, en pixels, au-dessus ou au-dessous du chemin où chaque estampage peut tomber.
  - `scatterCount` (integer 1–16) — Dispersion : estampages posés à chaque pas le long du chemin.
  - `blurStrength` (integer 1–4) — Flou : rayon du voisinage en pixels.
  - `jumbleStrength` (integer 0–100) — Brouillage : probabilité en pourcentage que chaque pixel touché soit brouillé.
  - `dodgeBurnStrength` (integer 1–100) — Éclaircir/Assombrir : de combien la luminosité OKLCH de chaque pixel touché se déplace (100 = la moitié du chemin du noir au blanc).
  - `dodgeBurnHueShift` (integer 0–60) — Éclaircir/Assombrir : degrés dont la teinte OKLCH de chaque pixel touché tourne vers le jaune chaud (éclaircir) ou le bleu froid (assombrir), sans jamais le dépasser ; 0 garde la teinte.
  - `ditherPattern` (DitherPattern: "bayer2" | "bayer4" | "bayer8" | "dots" | "lines-h" | "lines-v" | "diagonal" | "noise") — Pinceau de tramage : le motif ordonné à travers lequel il peint. Les motifs se répètent depuis le coin supérieur gauche du sprite, donc les tracés s'alignent.
  - `ditherDensity` (integer 0–100) — Pinceau de tramage : la part des pixels du motif qu'il peint, en pourcentage (50 avec bayer2 donne un damier).
  - `gradientType` (GradientType: "linear" | "radial") — Dégradé : une rampe droite entre les points, ou rayonnant depuis le point de départ.
  - `gradientDithering` (GradientDithering: "none" | "bayer2" | "bayer4" | "bayer8" | "dots" | "lines-h" | "lines-v" | "diagonal" | "noise") — Dégradé : le motif de tramage ordonné (none = une rampe lisse).
  - `gradientSnap` (GradientSnap: "free" | "palette") — Dégradé : mélanges libres, ou uniquement des couleurs de la palette (chaque pixel prend la couleur de palette la plus proche ; le tramage alterne entre couleurs de palette voisines).
  - `gradientColors` (GradientColors: "fg-bg" | "stops") — Dégradé : va de la couleur de premier plan à celle d'arrière-plan, ou suit gradientStops ("stops" ; moins de deux points revient à premier plan vers arrière-plan).
  - `gradientStops` (a list of { color, position } (position 0-1, in order), or a list of colors spread evenly) — Dégradé : la rampe à plusieurs points depuis le point de départ, sous forme d'entrées { color, position } (position 0-1, dans l'ordre ; deux à la même position font un bord net). Une simple liste de couleurs est répartie uniformément. Utilisée quand gradientColors vaut "stops" ; la barre Points de l'éditeur la modifie.
  - `eyedropperSource` (EyedropperSource: "composite" | "layer") — Pipette : échantillonne ce que montre le canevas, ou seulement le calque actif.
  - `tileIndex` (integer ≥ 0) — Tampon de tuiles : la tuile à placer, numérotée à partir de 1 (0 = la tuile vide).
  - `tileFlipH` (boolean) — Tampon de tuiles : retourne horizontalement les tuiles placées.
  - `tileFlipV` (boolean) — Tampon de tuiles : retourne verticalement les tuiles placées.
  - `tileRotate90` (boolean) — Tampon de tuiles : fait pivoter les tuiles placées de 90° dans le sens horaire.
  - `tilePlace` (boolean) — Placer des tuiles : sur un calque tilemap, le crayon, la gomme, la ligne, les outils de formes et le pot de peinture placent la tuile du tampon de tuiles (l'effacent, pour la gomme) sur les cellules qu'ils couvrent au lieu de peindre des pixels.
  - `isoShape` (IsoShape: "box" | "ramp" | "stairs" | "pyramid" | "prism" | "cylinder" | "cone" | "sphere" | "dome") — Outil Forme isométrique : le solide qu'il dessine.
  - `isoWidth` (integer 1–1024) — Outil Forme isométrique : emprise le long de x (vers le bas à droite), en unités iso (une rangée de l'escalier du bord chacune).
  - `isoDepth` (integer 1–1024) — Outil Forme isométrique : emprise le long de y (vers le bas à gauche), en unités iso.
  - `isoHeight` (integer 0–1024) — Outil Forme isométrique : hauteur en pixels (0 = à plat).
  - `isoBevel` (integer 0–1024) — Outil Forme isométrique : pour les boîtes uniquement, de combien de pixels les arêtes du dessus sont chanfreinées (0 = angle droit).
  - `isoCap` (integer 2–4) — Outil Forme isométrique : le tronçon plat aux sommets du haut et du bas, 2 (pair), 3 (impair) ou 4 (multiples de quatre). C'est aussi le pas de glissement de W / D (2 unités avec 4).
  - `isoStyle` (IsoShapeStyle: "filled" | "outline" | "filled-outline") — Outil Forme isométrique : faces, contour, ou les deux.
  - `isoHiddenEdges` (boolean) — Outil Forme isométrique : dessine aussi les arêtes derrière le solide.
  - `isoDirection` (IsoDirection: "+x" | "-x" | "+y" | "-y") — Outil Forme isométrique : dans quel sens descendent une rampe ou des escaliers, ou vers où sont tournées les pentes d'un prisme.
  - `isoAutoShade` (boolean) — Outil Forme isométrique : déduit les cinq couleurs de la couleur de premier plan le long de `shades` (true), ou utilise isoColors (false).
  - `isoColors` (a list of colors ("#rrggbb[aa]" or { r, g, b, a }), in order) — Outil Forme isométrique : les couleurs utilisées quand isoAutoShade est désactivé, dans l'ordre contour, arête intérieure, dessus, gauche, droite.

Ne renvoie rien.

#### `app.swapColors()` — modifie
Échange les couleurs de premier plan et d'arrière-plan (le X de l'interface).

Ne renvoie rien.