# API de scripting Lua de pxstud.io — Píxeles

> Parte de la referencia de scripting Lua de pxstud.io, cuya introducción (https://pxstud.io/es/docs/scripting.md) explica sus convenciones. Los grupos de opciones y los tipos a los que remite están en https://pxstud.io/es/docs/scripting/option-groups.md y https://pxstud.io/es/docs/scripting/types.md. Todo en un solo archivo (en inglés): https://pxstud.io/llms-full.txt. El índice de todo el sitio (en inglés): https://pxstud.io/llms.txt.

### Píxeles
Lectura y escritura de píxeles como listas RGBA planas (construidas sobre Images; nunca recortadas por la selección ni reflejadas), rellenos y volteos de la selección completa, y el cuentagotas.

#### `app.clearSelection(layerId, frameId)` — modifica, deshacible, se rechaza en una capa bloqueada
Deja la selección totalmente transparente y recorta la celda a lo que queda (una celda vaciada se elimina, junto con todos los fotogramas vinculados a ella); sin nada seleccionado, elimina la celda de este fotograma (un fotograma vinculado solo pierde su vínculo). En la capa Background todo se borra al color de fondo.

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

No devuelve nada.

#### `app.fillSelection(layerId, frameId, color, opts?)` — modifica, deshacible, se rechaza en una capa bloqueada
Rellena la selección (o toda la celda, si no hay nada seleccionado) con un color sólido. Es un relleno simple (copy) salvo que se indique `ink`: a diferencia de los comandos de dibujo, nunca toma la tinta del contexto de edición, igual que Edición > Rellenar.

- `layerId` (string)
- `frameId` (string)
- `color` (table) — { r, g, b, a }, cada uno de 0 a 255.
- `opts` (table, opcional)
  - `ink` (Ink: "copy" | "simple" | "lock-alpha" | "shading"; predeterminado "copy") — copy reemplaza los píxeles, simple compone con alfa, lock-alpha solo recolorea los píxeles visibles, shading avanza los colores a lo largo de `shades`. erase lo ignora.
  - `shades` (a list of colors ("#rrggbb[aa]" or { r, g, b, a }), in ramp order) — La rampa a lo largo de la cual avanza shading. Un píxel cuyo color no está en la lista no se toca; un píxel al final de la lista se queda ahí.
  - `shadeReverse` (boolean; predeterminado false) — Shading retrocede en `shades` (el botón derecho del mouse en la interfaz) en lugar de avanzar.

No devuelve nada.

#### `app.flipCelRegion(layerId, frameId, axis)` — modifica, deshacible, se rechaza en una capa bloqueada
Voltea los píxeles seleccionados (o toda la celda, si no hay nada seleccionado) dentro de los límites de la selección: cada píxel seleccionado pasa a su simétrico, los que quedan atrás se borran (al color de fondo en la capa Background) y el marco de selección también se voltea.

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

No devuelve nada.

#### `app.getCompositePixels(frameId, x, y, width, height)` — pura
Los píxeles de app.getCompositeImage como una lista RGBA plana con la forma de app.getPixels. Como máximo 262144 píxeles por llamada.

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

Devuelve (table): Lista RGBA plana.

#### `app.getPixels(layerId, frameId, x, y, width, height)` — pura
Lee un rectángulo de width x height en (x, y) de la celda de una capa/fotograma como una lista RGBA plana (longitud width*height*4, por filas: el píxel (px, py) empieza en el índice (py*width + px)*4 + 1), con la forma que recibe app.setPixels. Los píxeles sin celda se leen como transparentes (0, 0, 0, 0). Construida sobre app.getImage, que es más rápida si no necesitas una lista. Como máximo 262144 píxeles por llamada.

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

Devuelve (table): Lista RGBA plana.

#### `app.sampleColor(frameId, x, y, layerId?)` — lee
El cuentagotas: el color en (x, y) como { r, g, b, a }; por defecto lo que muestra el lienzo ahí (las capas visibles combinadas con su opacidad y sus modos de fusión), o el color de una sola capa si se indica layerId.

- `frameId` (string)
- `x` (number)
- `y` (number)
- `layerId` (string, opcional) — Muestrea solo esta capa. Omitido = todas las capas visibles compuestas, como se ven en pantalla.

Devuelve (table): { r, g, b, a }, cada uno de 0 a 255.

#### `app.setPixels(layerId, frameId, x, y, width, height, pixels)` — pura
Sobrescribe un rectángulo de width x height en (x, y) de la celda de una capa/fotograma con una lista RGBA plana (la forma de app.getPixels), como un único app.putImage. Escritura directa: nunca se recorta a la selección ni se refleja. En sprites indexados y en escala de grises los colores se asignan como los asigna img:setPixel. Como máximo 262144 píxeles por llamada.

- `layerId` (string)
- `frameId` (string)
- `x` (number)
- `y` (number)
- `width` (number)
- `height` (number)
- `pixels` (table) — Lista RGBA plana, de longitud width*height*4, por filas: el píxel (px, py) está en el índice (py*width + px)*4 + 1 (r, luego g, b, a; cada uno de 0 a 255).

No devuelve nada.