# API de scripts Lua de pxstud.io — Cels

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

### Cels
Un cel est l'image d'un calque sur une image d'animation. Déplace, efface et lie-les par blocs.

#### `app.clearCels(cels)` — modifie, annulable, refusée sur un calque verrouillé
Supprime plusieurs cels d'un coup en une seule étape d'annulation : images sur les calques d'image, placements de tuiles sur les calques de tilemap, placements sur les calques de référence. Les cels qui n'existent pas sont ignorés.

- `cels` (table) — Tableau de tables { layerId = ..., frameId = ... } désignant les cels à supprimer.

Ne renvoie rien.

#### `app.getCel(layerId, frameId)` — lit
Le cel à layerId/frameId, dans la forme de app.getCels, ou nil si ce calque n'a ni image (ni placements de tuiles) sur cette image d'animation.

- `layerId` (string)
- `frameId` (string)

Renvoie (table) : Table de cel ou nil.

#### `app.getCelLink(layerId, frameId)` — lit
Si le cel à layerId/frameId est lié, l'id de l'image d'animation du cel source dont il partage l'image ; sinon nil.

- `layerId` (string)
- `frameId` (string)

Renvoie (string) : Id de l'image source ou nil.

#### `app.getCels()` — lit
Tous les cels (l'image d'un calque sur une image d'animation) sous la forme { layerId, frameId, x, y, width, height, opacity, zIndex (décalage de l'ordre de dessin, seulement si différent de 0), linkedTo (id de l'image partagée, cels liés uniquement) }, calque par calque du bas vers le haut, puis dans l'ordre des images. Une image de tilemap avec des placements (ou un lien) est aussi un cel : x/y/width/height sont les limites en pixels de ses placements. Les données de pixels se lisent avec app.getImage, les placements avec app.getTilemap.

Renvoie (table) : Tableau de tables de cel.

#### `app.getLinkedFrames()` — lit
Toutes les images liées sur les calques de tilemap et de référence sous la forme { layerId, frameId, linkedTo (l'image dont il partage les placements de tuiles ou le placement) }, calque par calque du bas vers le haut, puis dans l'ordre des images. Les calques d'image signalent leurs liens via le linkedTo de app.getCels.

Renvoie (table) : Tableau de tables de lien.

#### `app.linkCels(layerId, frameIds)` — modifie, annulable, refusée sur un calque verrouillé
Lie les cels d'un calque sur les images données pour qu'ils partagent une même image (modifier l'un modifie tous les autres) ; sur un calque de tilemap ils partagent les placements de tuiles, sur un calque de référence le placement. Lève une erreur si la première image n'a pas de cel.

- `layerId` (string)
- `frameIds` (table) — Tableau d'ids d'images. L'image du cel de la première image est partagée par toutes ; leurs propres cels sont remplacés par des liens.

Ne renvoie rien.

#### `app.moveCels(cels, dLayer, dFrame)` — modifie, annulable, refusée sur un calque verrouillé
Déplace un bloc de cels de (dLayer, dFrame), en écrasant les cases de destination, en une seule étape d'annulation. Les cels d'image se déplacent entre calques d'image, les placements de tuiles entre calques de tilemap partageant un tileset, les placements de référence uniquement le long de leur propre calque. Lève une erreur si le déplacement sort de la grille ou enfreint cette règle.

- `cels` (table) — Tableau de tables { layerId = ..., frameId = ... } désignant le bloc de cels à déplacer.
- `dLayer` (number) — Décalage d'index de calque ; une valeur positive monte dans la pile.
- `dFrame` (number) — Décalage dans l'ordre des images ; une valeur positive va vers les images suivantes.

Ne renvoie rien.

#### `app.setCelProps(layerId, frameId, props)` — modifie, annulable, refusée sur un calque verrouillé
Met à jour les propriétés du cel à un calque et une image d'animation donnés (un cel d'image ou une image de tilemap) : son opacité et son z-index.

- `layerId` (string)
- `frameId` (string)
- `props` (table) — Les clés omises restent inchangées.
  - `opacity` (number 0–1) — Opacité du cel, combinée avec celle du calque. Un cel lié partage celle de sa source (la définir sur n'importe quel cel du lien la définit pour tous). Les cels du calque Arrière-plan restent à 1.
  - `zIndex` (integer -32767–32767) — Le z-index de cel d'Aseprite : décale l'ordre de dessin de ce cel parmi les calques de son groupe sur cette image (ordre de dessin = position du calque + zIndex). 0 = la position propre du calque.

Ne renvoie rien.

#### `app.unlinkCels(layerId, frameIds)` — modifie, annulable, refusée sur un calque verrouillé
Redonne aux cels liés des copies indépendantes de l'image partagée (placements de tuiles, placement de référence). Lister l'image vers laquelle les autres pointent la délie aussi ; les autres restent liées entre elles. Les cels non liés sont laissés tels quels.

- `layerId` (string)
- `frameIds` (table) — Tableau d'ids d'images dont les cels liés deviennent des copies indépendantes.

Ne renvoie rien.