# pxstud.io Lua scripting API — Brushes

> Part of the pxstud.io Lua scripting reference, whose overview (https://pxstud.io/docs/scripting.md) explains its conventions. The option groups and types it refers to are in https://pxstud.io/docs/scripting/option-groups.md and https://pxstud.io/docs/scripting/types.md. Everything in one file: https://pxstud.io/llms-full.txt. The whole site's index: https://pxstud.io/llms.txt.

### Brushes
Define your own brushes by name, then paint with them. They live only in the engine for the session: not in the document, not undoable, not saved, and separate from the editor's brush library.

#### `app.brushFromSelection(name)` — changes
Defines a custom brush from the shape of the current selection (selected pixels paint). Throws if nothing is selected or the selection is larger than 64 x 64.

- `name` (string) — The name to give the brush.

Returns (table): { width, height } of the brush.

#### `app.defineBrush(name, brush)` — changes
Defines a custom brush by name, for use as `brush = "name"` in the drawing commands or with app.useBrush. Brushes live only in the engine for the session: they aren't part of the document, aren't undoable, and aren't saved or added to the editor's brush library.

- `name` (string) — 1-64 characters. Defining an existing name replaces it.
- `brush` (table) — Give `rows` (readable) or `width`, `height` and `mask`. Example: { rows = { ".#.", "###", ".#." } } is a plus sign.
  - `name` (string) — Ignored — present so a brush from a config form field (app.config.<id>) can be passed as is.
  - `rows` (list of strings, one per row; ".", " " and "0" are empty, anything else paints) — The brush as text, up to 64 x 64. Short rows are padded with empty pixels.
  - `width` (integer 1–64) — Width in pixels (with `mask`).
  - `height` (integer 1–64) — Height in pixels (with `mask`).
  - `mask` (flat row-major list of width*height 0/1 values) — The brush as numbers (with `width` and `height`).

Returns (table): { width, height } of the brush.

#### `app.getBrush(name)` — reads
A custom brush by name as { name, width, height, mask (flat 0/1 list), rows (the same as strings of # and .) }, or nil if there's no such brush.

- `name` (string)

Returns (table): Brush table or nil.

#### `app.getBrushes()` — reads
The custom brushes defined with app.defineBrush, in definition order, as { name, width, height }. Built-in brushes (circle, square, horizontal) aren't listed.

Returns (table): Array of { name, width, height }.

#### `app.removeBrush(name)` — changes
Deletes a custom brush defined with app.defineBrush. Draw commands already run keep the brush they used.

- `name` (string)

Returns (boolean): true if there was such a brush.

#### `app.useBrush(name)` — changes
Makes a custom brush the current brush (the editing context's brushShape = "custom" and customBrush), so draw commands without a `brush` option use it — the editor's toolbar shows it too. Throws if the name is unknown.

- `name` (string) — A brush defined with app.defineBrush.

Returns nothing.