# API de scripts Lua do pxstud.io — Pincéis

> Parte da referência de scripts Lua do pxstud.io, cuja visão geral (https://pxstud.io/pt-br/docs/scripting.md) explica as convenções. Os grupos de opções e os tipos a que ela remete estão em https://pxstud.io/pt-br/docs/scripting/option-groups.md e https://pxstud.io/pt-br/docs/scripting/types.md. Tudo em um único arquivo (em inglês): https://pxstud.io/llms-full.txt. O índice de todo o site (em inglês): https://pxstud.io/llms.txt.

### Pincéis
Defina seus próprios pincéis por nome e pinte com eles. Eles existem apenas no engine durante a sessão: não ficam no documento, não podem ser desfeitos, não são salvos e são separados da biblioteca de pincéis do editor.

#### `app.brushFromSelection(name)` — altera
Define um pincel personalizado a partir da forma da seleção atual (os pixels selecionados pintam). Gera um erro se nada estiver selecionado ou se a seleção for maior que 64 x 64.

- `name` (string) — O nome a dar ao pincel.

Retorna (table): { width, height } do pincel.

#### `app.defineBrush(name, brush)` — altera
Define um pincel personalizado por nome, para usar como `brush = "name"` nos comandos de desenho ou com app.useBrush. Os pincéis existem apenas no engine durante a sessão: não fazem parte do documento, não podem ser desfeitos e não são salvos nem adicionados à biblioteca de pincéis do editor.

- `name` (string) — De 1 a 64 caracteres. Definir um nome existente o substitui.
- `brush` (table) — Informe `rows` (legível) ou `width`, `height` e `mask`. Exemplo: { rows = { ".#.", "###", ".#." } } é um sinal de mais.
  - `name` (string) — Ignorado: existe para que um pincel vindo de um campo de formulário de configuração (app.config.<id>) possa ser passado como está.
  - `rows` (list of strings, one per row; ".", " " and "0" are empty, anything else paints) — O pincel como texto, de até 64 x 64. Linhas curtas são completadas com pixels vazios.
  - `width` (integer 1–64) — Largura em pixels (com `mask`).
  - `height` (integer 1–64) — Altura em pixels (com `mask`).
  - `mask` (flat row-major list of width*height 0/1 values) — O pincel como números (com `width` e `height`).

Retorna (table): { width, height } do pincel.

#### `app.getBrush(name)` — lê
Um pincel personalizado por nome, como { name, width, height, mask (lista plana de 0/1), rows (o mesmo como strings de # e .) }, ou nil se não existir esse pincel.

- `name` (string)

Retorna (table): Tabela do pincel ou nil.

#### `app.getBrushes()` — lê
Os pincéis personalizados definidos com app.defineBrush, na ordem de definição, como { name, width, height }. Os pincéis integrados (circle, square, horizontal) não são listados.

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

#### `app.removeBrush(name)` — altera
Exclui um pincel personalizado definido com app.defineBrush. Os comandos de desenho já executados mantêm o pincel que usaram.

- `name` (string)

Retorna (boolean): true se esse pincel existia.

#### `app.useBrush(name)` — altera
Torna um pincel personalizado o pincel atual (o brushShape = "custom" e o customBrush do contexto de edição), para que os comandos de desenho sem a opção `brush` o usem; a barra de ferramentas do editor também o mostra. Gera um erro se o nome for desconhecido.

- `name` (string) — Um pincel definido com app.defineBrush.

Não retorna nada.