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

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

### Pixel
Pixel lesen und schreiben als flache RGBA-Listen (auf Images aufgebaut; nie von der Auswahl beschnitten oder gespiegelt), Füllungen und Spiegelungen der ganzen Auswahl und die Pipette.

#### `app.clearSelection(layerId, frameId)` — ändert, rückgängig machbar, wird auf einer gesperrten Ebene abgelehnt
Leert die Auswahl zu vollständig transparent und stutzt das Cel auf den Rest (ein leer gewordenes Cel wird entfernt, samt allen mit ihm verknüpften Frames); ist nichts ausgewählt, entfernt es das Cel dieses Frames (ein verknüpfter Frame verliert nur seine Verknüpfung). Auf der Hintergrundebene wird alles auf die Hintergrundfarbe geleert.

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

Gibt nichts zurück.

#### `app.fillSelection(layerId, frameId, color, opts?)` — ändert, rückgängig machbar, wird auf einer gesperrten Ebene abgelehnt
Füllt die Auswahl (oder das ganze Cel, wenn nichts ausgewählt ist) mit einer einfarbigen Farbe. Eine schlichte Füllung (copy), sofern kein `ink` angegeben ist: Anders als die Zeichenbefehle übernimmt sie nie die Tinte des Bearbeitungskontexts, wie Bearbeiten > Füllen.

- `layerId` (string)
- `frameId` (string)
- `color` (table) — { r, g, b, a } – jeweils 0-255.
- `opts` (table, optional)
  - `ink` (Ink: "copy" | "simple" | "lock-alpha" | "shading"; Standard "copy") — copy ersetzt Pixel, simple setzt per Alpha-Compositing auf, lock-alpha färbt nur sichtbare Pixel um, shading rückt Farben entlang `shades` weiter. Wird von erase ignoriert.
  - `shades` (a list of colors ("#rrggbb[aa]" or { r, g, b, a }), in ramp order) — Die Farbreihe, entlang der das Shading weiterrückt. Ein Pixel, dessen Farbe nicht in der Liste steht, bleibt unberührt; ein Pixel am Ende der Liste bleibt dort.
  - `shadeReverse` (boolean; Standard false) — Das Shading rückt in `shades` rückwärts weiter (wie die rechte Maustaste in der Oberfläche) statt vorwärts.

Gibt nichts zurück.

#### `app.flipCelRegion(layerId, frameId, axis)` — ändert, rückgängig machbar, wird auf einer gesperrten Ebene abgelehnt
Spiegelt die ausgewählten Pixel (oder das ganze Cel, wenn nichts ausgewählt ist) innerhalb der Grenzen der Auswahl: Jedes ausgewählte Pixel wandert an seine Spiegelposition, die zurückgelassenen werden geleert (auf der Hintergrundebene auf die Hintergrundfarbe), und der Auswahlrahmen wird mitgespiegelt.

- `layerId` (string)
- `frameId` (string)
- `axis` (FlipAxis: "horizontal" | "vertical")

Gibt nichts zurück.

#### `app.getCompositePixels(frameId, x, y, width, height)` — rein
Die Pixel von app.getCompositeImage als flache RGBA-Liste in der Form von app.getPixels. Höchstens 262144 Pixel pro Aufruf.

- `frameId` (string)
- `x` (number)
- `y` (number)
- `width` (number)
- `height` (number)

Gibt zurück (table): Flache RGBA-Liste.

#### `app.getPixels(layerId, frameId, x, y, width, height)` — rein
Liest ein Rechteck der Größe width x height bei (x, y) des Cels einer Ebene/eines Frames als flache RGBA-Liste (Länge width*height*4, zeilenweise: Pixel (px, py) beginnt bei Index (py*width + px)*4 + 1), in der Form, die app.setPixels erwartet. Pixel ohne Cel werden als transparent (0, 0, 0, 0) gelesen. Auf app.getImage aufgebaut, das schneller ist, wenn du keine Liste brauchst. Höchstens 262144 Pixel pro Aufruf.

- `layerId` (string)
- `frameId` (string)
- `x` (number)
- `y` (number)
- `width` (number)
- `height` (number)

Gibt zurück (table): Flache RGBA-Liste.

#### `app.sampleColor(frameId, x, y, layerId?)` — liest
Die Pipette: die Farbe bei (x, y) als { r, g, b, a } – standardmäßig das, was die Leinwand dort zeigt (sichtbare Ebenen, mit ihrer Deckkraft und ihren Mischmodi gemischt), oder die Farbe einer einzelnen Ebene, wenn layerId angegeben ist.

- `frameId` (string)
- `x` (number)
- `y` (number)
- `layerId` (string, optional) — Nur diese Ebene abtasten. Weggelassen = alle sichtbaren Ebenen zusammengesetzt, wie auf dem Bildschirm.

Gibt zurück (table): { r, g, b, a }, jeweils 0-255.

#### `app.setPixels(layerId, frameId, x, y, width, height, pixels)` — rein
Überschreibt ein Rechteck der Größe width x height bei (x, y) des Cels einer Ebene/eines Frames mit einer flachen RGBA-Liste (Form von app.getPixels), als ein app.putImage. Roh-Schreiben: nie auf die Auswahl beschnitten oder gespiegelt. Auf indizierten und Graustufen-Sprites werden Farben so abgebildet, wie img:setPixel sie abbildet. Höchstens 262144 Pixel pro Aufruf.

- `layerId` (string)
- `frameId` (string)
- `x` (number)
- `y` (number)
- `width` (number)
- `height` (number)
- `pixels` (table) — Flache RGBA-Liste, Länge width*height*4, zeilenweise: Pixel (px, py) liegt bei Index (py*width + px)*4 + 1 (r, dann g, b, a; jeweils 0-255).

Gibt nichts zurück.