# API de scripts Lua de pxstud.io — Pinceaux

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

### Pinceaux
Définis tes propres pinceaux par leur nom, puis peins avec. Ils n'existent que dans le moteur, le temps de la session : ils ne font pas partie du document, ne sont pas annulables, ne sont pas enregistrés et restent séparés de la bibliothèque de pinceaux de l'éditeur.

#### `app.brushFromSelection(name)` — modifie
Définit un pinceau personnalisé à partir de la forme de la sélection actuelle (les pixels sélectionnés peignent). Lève une erreur si rien n'est sélectionné ou si la sélection dépasse 64 x 64.

- `name` (string) — Le nom à donner au pinceau.

Renvoie (table) : { width, height } du pinceau.

#### `app.defineBrush(name, brush)` — modifie
Définit un pinceau personnalisé par son nom, à utiliser avec `brush = "name"` dans les commandes de dessin ou avec app.useBrush. Les pinceaux n'existent que dans le moteur, le temps de la session : ils ne font pas partie du document, ne sont pas annulables, et ne sont ni enregistrés ni ajoutés à la bibliothèque de pinceaux de l'éditeur.

- `name` (string) — 1 à 64 caractères. Définir un nom existant le remplace.
- `brush` (table) — Donne `rows` (lisible) ou `width`, `height` et `mask`. Exemple : { rows = { ".#.", "###", ".#." } } est un signe plus.
  - `name` (string) — Ignoré : présent pour qu'un pinceau issu d'un champ de formulaire de configuration (app.config.<id>) puisse être passé tel quel.
  - `rows` (list of strings, one per row; ".", " " and "0" are empty, anything else paints) — Le pinceau sous forme de texte, jusqu'à 64 x 64. Les lignes trop courtes sont complétées par des pixels vides.
  - `width` (integer 1–64) — Largeur en pixels (avec `mask`).
  - `height` (integer 1–64) — Hauteur en pixels (avec `mask`).
  - `mask` (flat row-major list of width*height 0/1 values) — Le pinceau sous forme de nombres (avec `width` et `height`).

Renvoie (table) : { width, height } du pinceau.

#### `app.getBrush(name)` — lit
Un pinceau personnalisé par son nom, sous la forme { name, width, height, mask (liste plate de 0/1), rows (la même chose sous forme de chaînes de # et .) }, ou nil s'il n'existe pas de tel pinceau.

- `name` (string)

Renvoie (table) : Table du pinceau ou nil.

#### `app.getBrushes()` — lit
Les pinceaux personnalisés définis avec app.defineBrush, dans l'ordre de définition, sous la forme { name, width, height }. Les pinceaux intégrés (circle, square, horizontal) ne sont pas listés.

Renvoie (table) : Tableau de { name, width, height }.

#### `app.removeBrush(name)` — modifie
Supprime un pinceau personnalisé défini avec app.defineBrush. Les commandes de dessin déjà exécutées gardent le pinceau qu'elles ont utilisé.

- `name` (string)

Renvoie (boolean) : true s'il existait un tel pinceau.

#### `app.useBrush(name)` — modifie
Fait d'un pinceau personnalisé le pinceau actuel (brushShape = "custom" et customBrush du contexte d'édition), de sorte que les commandes de dessin sans option `brush` l'utilisent ; la barre d'outils de l'éditeur l'affiche aussi. Lève une erreur si le nom est inconnu.

- `name` (string) — Un pinceau défini avec app.defineBrush.

Ne renvoie rien.