# Lua-Skript-API von pxstud.io — Cels

> Teil der Lua-Skript-Referenz von pxstud.io, deren Übersicht (https://pxstud.io/de/docs/scripting.md) die Konventionen erklärt. Die Optionsgruppen und Typen, auf die sie verweist, stehen in https://pxstud.io/de/docs/scripting/option-groups.md und https://pxstud.io/de/docs/scripting/types.md. Alles in einer Datei (auf Englisch): https://pxstud.io/llms-full.txt. Das Verzeichnis der ganzen Website (auf Englisch): https://pxstud.io/llms.txt.

### Cels
Ein Cel ist das Bild einer Ebene in einem Frame. Verschiebe, leere und verknüpfe sie blockweise.

#### `app.clearCels(cels)` — ändert, rückgängig machbar, wird auf einer gesperrten Ebene abgelehnt
Löscht mehrere Cels auf einmal als einen einzigen Rückgängig-Schritt: Bilder auf Bildebenen, Tile-Platzierungen auf Tilemap-Ebenen, Platzierungen auf Referenzebenen. Cels, die nicht existieren, werden ignoriert.

- `cels` (table) — Array von Tabellen { layerId = ..., frameId = ... }, die die zu löschenden Cels benennen.

Gibt nichts zurück.

#### `app.getCel(layerId, frameId)` — liest
Das Cel bei layerId/frameId in der Form von app.getCels, oder nil, wenn diese Ebene in diesem Frame kein Bild (oder keine Tile-Platzierungen) hat.

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

Gibt zurück (table): Cel-Tabelle oder nil.

#### `app.getCelLink(layerId, frameId)` — liest
Wenn das Cel bei layerId/frameId verknüpft ist, die Frame-ID des Quell-Cels, dessen Bild es teilt; sonst nil.

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

Gibt zurück (string): Quell-Frame-ID oder nil.

#### `app.getCels()` — liest
Jedes Cel (das Bild einer Ebene in einem Frame) als { layerId, frameId, x, y, width, height, opacity, zIndex (Verschiebung der Zeichenreihenfolge, nur wenn nicht 0), linkedTo (Frame-ID des geteilten Bildes, nur verknüpfte Cels) }, Ebene für Ebene von unten nach oben, dann in Frame-Reihenfolge. Ein Tilemap-Frame mit Platzierungen (oder einer Verknüpfung) ist ebenfalls ein Cel: x/y/width/height sind die Pixelgrenzen seiner Platzierungen. Pixeldaten liest du mit app.getImage, Platzierungen mit app.getTilemap.

Gibt zurück (table): Array von Cel-Tabellen.

#### `app.getLinkedFrames()` — liest
Jeder verknüpfte Frame auf Tilemap- und Referenzebenen als { layerId, frameId, linkedTo (der Frame, dessen Tile-Platzierungen oder Platzierung er teilt) }, Ebene für Ebene von unten nach oben, dann in Frame-Reihenfolge. Bildebenen melden ihre Verknüpfungen über linkedTo von app.getCels.

Gibt zurück (table): Array von Verknüpfungstabellen.

#### `app.linkCels(layerId, frameIds)` — ändert, rückgängig machbar, wird auf einer gesperrten Ebene abgelehnt
Verknüpft die Cels einer Ebene in den angegebenen Frames, sodass sie ein Bild teilen (wer eins bearbeitet, bearbeitet alle); auf einer Tilemap-Ebene teilen sie Tile-Platzierungen, auf einer Referenzebene die Platzierung. Wirft einen Fehler, wenn der erste Frame kein Cel hat.

- `layerId` (string)
- `frameIds` (table) — Array von Frame-IDs. Das Cel-Bild des ersten Frames wird von allen geteilt; ihre eigenen Cels werden durch Verknüpfungen ersetzt.

Gibt nichts zurück.

#### `app.moveCels(cels, dLayer, dFrame)` — ändert, rückgängig machbar, wird auf einer gesperrten Ebene abgelehnt
Verschiebt einen Block von Cels um (dLayer, dFrame) und überschreibt dabei die Zielzellen, als einen einzigen Rückgängig-Schritt. Bild-Cels wandern zwischen Bildebenen, Tile-Platzierungen zwischen Tilemap-Ebenen, die ein Tileset teilen, Referenzplatzierungen nur entlang ihrer eigenen Ebene. Wirft einen Fehler, wenn die Verschiebung das Raster verlässt oder diese Regel verletzt.

- `cels` (table) — Array von Tabellen { layerId = ..., frameId = ... }, die den zu verschiebenden Block von Cels benennen.
- `dLayer` (number) — Differenz des Ebenenindex; positiv verschiebt nach oben im Stapel.
- `dFrame` (number) — Differenz der Frame-Reihenfolge; positiv verschiebt zu späteren Frames.

Gibt nichts zurück.

#### `app.setCelProps(layerId, frameId, props)` — ändert, rückgängig machbar, wird auf einer gesperrten Ebene abgelehnt
Aktualisiert Eigenschaften des Cels bei einer Ebene und einem Frame (ein Bild-Cel oder ein Tilemap-Frame): seine Deckkraft und seinen Z-Index.

- `layerId` (string)
- `frameId` (string)
- `props` (table) — Weggelassene Schlüssel bleiben unverändert.
  - `opacity` (number 0–1) — Deckkraft des Cels, kombiniert mit der der Ebene. Ein verknüpftes Cel teilt die Deckkraft seiner Quelle (setzt du sie an einem Cel der Verknüpfung, gilt sie für alle). Die Cels der Hintergrundebene bleiben bei 1.
  - `zIndex` (integer -32767–32767) — Der Cel-Z-Index von Aseprite: verschiebt die Zeichenreihenfolge dieses Cels unter den Ebenen seiner Gruppe in diesem Frame (Zeichenreihenfolge = Ebenenposition + zIndex). 0 = die eigene Position der Ebene.

Gibt nichts zurück.

#### `app.unlinkCels(layerId, frameIds)` — ändert, rückgängig machbar, wird auf einer gesperrten Ebene abgelehnt
Macht verknüpfte Cels wieder zu unabhängigen Kopien des geteilten Bilds (Tile-Platzierungen, Referenzplatzierung). Nennst du den Frame, auf den die anderen verweisen, wird auch er gelöst; die übrigen bleiben miteinander verknüpft. Nicht verknüpfte Cels bleiben unberührt.

- `layerId` (string)
- `frameIds` (table) — Array von Frame-IDs, deren verknüpfte Cels zu unabhängigen Kopien werden.

Gibt nichts zurück.