# API de scripting Lua de pxstud.io — Pinceles

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

### Pinceles
Define tus propios pinceles por nombre y pinta con ellos. Viven solo en el motor durante la sesión: no están en el documento, no se pueden deshacer, no se guardan y son independientes de la biblioteca de pinceles del editor.

#### `app.brushFromSelection(name)` — modifica
Define un pincel personalizado a partir de la forma de la selección actual (los píxeles seleccionados pintan). Lanza un error si no hay nada seleccionado o si la selección es mayor que 64 x 64.

- `name` (string) — El nombre que se le da al pincel.

Devuelve (table): { width, height } del pincel.

#### `app.defineBrush(name, brush)` — modifica
Define un pincel personalizado por nombre, para usarlo como `brush = "name"` en los comandos de dibujo o con app.useBrush. Los pinceles viven solo en el motor durante la sesión: no forman parte del documento, no se pueden deshacer y no se guardan ni se añaden a la biblioteca de pinceles del editor.

- `name` (string) — De 1 a 64 caracteres. Si defines un nombre que ya existe, lo reemplaza.
- `brush` (table) — Indica `rows` (legible) o `width`, `height` y `mask`. Ejemplo: { rows = { ".#.", "###", ".#." } } es un signo más.
  - `name` (string) — Se ignora; está para poder pasar tal cual un pincel de un campo de formulario de configuración (app.config.<id>).
  - `rows` (list of strings, one per row; ".", " " and "0" are empty, anything else paints) — El pincel como texto, de hasta 64 x 64. Las filas cortas se rellenan con píxeles vacíos.
  - `width` (integer 1–64) — Ancho en píxeles (con `mask`).
  - `height` (integer 1–64) — Alto en píxeles (con `mask`).
  - `mask` (flat row-major list of width*height 0/1 values) — El pincel como números (con `width` y `height`).

Devuelve (table): { width, height } del pincel.

#### `app.getBrush(name)` — lee
Un pincel personalizado por nombre, como { name, width, height, mask (lista plana de 0/1), rows (lo mismo como cadenas de # y .) }, o nil si no existe ese pincel.

- `name` (string)

Devuelve (table): Tabla del pincel o nil.

#### `app.getBrushes()` — lee
Los pinceles personalizados definidos con app.defineBrush, en el orden de definición, como { name, width, height }. Los pinceles integrados (circle, square, horizontal) no aparecen.

Devuelve (table): Array de { name, width, height }.

#### `app.removeBrush(name)` — modifica
Elimina un pincel personalizado definido con app.defineBrush. Los comandos de dibujo que ya se ejecutaron conservan el pincel que usaron.

- `name` (string)

Devuelve (boolean): true si existía ese pincel.

#### `app.useBrush(name)` — modifica
Convierte un pincel personalizado en el pincel actual (en el contexto de edición, brushShape = "custom" y customBrush), de modo que los comandos de dibujo sin la opción `brush` lo usen; la barra de herramientas del editor también lo muestra. Lanza un error si el nombre es desconocido.

- `name` (string) — Un pincel definido con app.defineBrush.

No devuelve nada.