Selection

app.canReselect() — reads

Whether app.reselect() has a previous selection to restore.

Returns (boolean): true if there is one.

app.deselect() — changes

Clears the selection (Select ▸ Deselect) — draw commands then paint anywhere. app.reselect() brings it back.

Returns nothing.

app.enterQuickMask() — changes, undoable

Turns Quick Mask on: the selection becomes a mask you paint, and nothing is selected. While it is on, the draw functions paint the mask when you pass "quickMask" as their layerId and frameId (any colour adds, transparent paint removes); everything else that would change the sprite is refused until app.exitQuickMask().

Returns nothing.

app.exitQuickMask() — changes, undoable

Turns Quick Mask off: every mask pixel at or above half opacity becomes the selection.

Returns nothing.

app.getSelection() — reads

The current selection as { x, y, width, height, mask }, or nil if nothing is selected. mask is a flat 0/1 list over the bounds (row-major: (px, py) at index py*width + px + 1) — included when the bounds hold at most 262144 pixels; for larger selections read it in pieces with app.getSelectionMask.

Returns (table): Selection table or nil.

app.getSelectionBounds() — reads

The current selection's { x, y, width, height }, or nil if nothing is selected.

Returns (table): { x, y, width, height } or nil.

app.getSelectionMask(x, y, width, height) — reads

Which pixels of a sprite-space rectangle are selected, as a flat 0/1 list (row-major: (px, py) at index py*width + px + 1). All 0 when nothing is selected. At most 262144 pixels per call.

• x (number)
• y (number)
• width (number)
• height (number)

Returns (table): Flat 0/1 list.

app.isSelected(x, y) — reads

Whether sprite pixel (x, y) is inside the current selection (false when nothing is selected).

• x (number)
• y (number)

Returns (boolean): true if selected.

app.magicWand(layerId, frameId, points, opts?) — changes, undoable

Selects the pixels matching the color under each point on a layer, all the regions as one selection — exactly the GUI magic wand (a click or a drag).

• layerId (string)
• frameId (string)
• points (table) — List of { x = n, y = n } (or { n, n }) points, 1 to 1024: { { x = 3, y = 4 } } wands one region, like a click; with several, every point's region goes into one selection, like a drag.
• opts (table, optional)
  • mode (SelectionCombineMode: "replace" | "add" | "subtract" | "intersect"; default "replace") — How the new shape combines with the current selection.
  • tolerance (integer 0–255; default context.wandTolerance) — The largest per-channel color difference that still counts as a match.
  • contiguous (boolean; default context.wandFillMode (true for the context's contiguous mode, false for global)) — Only the connected region (true), or every matching pixel on the canvas (false).
  • diagonal (boolean; default context.wandDiagonal) — Contiguous only: also spread to diagonal neighbours (8-connected), so the region leaks through 1px diagonal lines.
  • stopAtGrid (boolean; default context.wandStopAtGrid) — Confine the region to the grid cell the click lands in (an isometric grid's cell is the diamond it draws, with the line pixels of its two upper edges).

Returns nothing.

app.modifySelection(op, amount, opts?) — changes, undoable

Grows, shrinks or rings the selection, clipped to the canvas — exactly Select > Modify. The canvas edge counts as the selection's edge.

• op (SelectionModifyOp: "expand" | "contract" | "border")
• amount (number) — Pixels, 1 to 256.
• opts (table, optional)
  • shape (SelectionModifyShape: "circle" | "square"; default "circle") — How distance from the edge is measured.

Returns nothing.

app.reselect() — changes

Restores the most recent non-empty selection (Select ▸ Reselect). Throws if there is none — check app.canReselect().

Returns nothing.

app.selectAll() — changes, undoable

Selects the entire canvas.

Returns nothing.

app.selectEllipse(x0, y0, x1, y1, opts?) — changes, undoable

Selects the ellipse inscribed in the box spanning the two corners — exactly the GUI elliptical selection tool.

• x0 (number) — First corner.
• y0 (number)
• x1 (number) — Opposite corner (inclusive).
• y1 (number)
• opts (table, optional)
  • mode (SelectionCombineMode: "replace" | "add" | "subtract" | "intersect"; default "replace") — How the new shape combines with the current selection.

Returns nothing.

app.selectGridCells(x0, y0, x1, y1, opts?) — changes, undoable

Selects whole cells of the sprite's grid (rectangular, isometric or hexagonal): every cell holding a pixel of the box between the two points — exactly a double-click (and drag) with a GUI selection tool.

• x0 (number) — A pixel in the first cell.
• y0 (number)
• x1 (number) — A pixel in the last cell (the same point again selects one cell).
• y1 (number)
• opts (table, optional)
  • mode (SelectionCombineMode: "replace" | "add" | "subtract" | "intersect"; default "replace") — How the new shape combines with the current selection.

Returns nothing.

app.selectInverse() — changes, undoable

Inverts the current selection within canvas bounds.

Returns nothing.

app.selectLayerPixels(layerId, frameId, opts?) — changes, undoable

Selects a layer's painted (or, with transparent = true, unpainted) pixels at a frame — exactly Select > Select Opaque / Select Transparent and Alt+click on a timeline layer.

• layerId (string) — A group selects the pixels of every layer in it.
• frameId (string)
• opts (table, optional)
  • mode (SelectionCombineMode: "replace" | "add" | "subtract" | "intersect"; default "replace") — How the new shape combines with the current selection.
  • transparent (boolean; default false) — Select the pixels with no paint instead of the painted ones.

Returns nothing.

app.selectPolygon(vertices, opts?) — changes, undoable

Selects the interior (and outline) of the closed polygon through the vertices — exactly the GUI lasso / polygonal lasso.

• vertices (table) — List of { x = n, y = n } (or { n, n }) vertices; the polygon closes back to the first automatically. Covers both the lasso and the polygonal lasso.
• opts (table, optional)
  • mode (SelectionCombineMode: "replace" | "add" | "subtract" | "intersect"; default "replace") — How the new shape combines with the current selection.

Returns nothing.

app.selectRectangle(x0, y0, x1, y1, opts?) — changes, undoable

Selects the rectangle spanning the two corners — exactly the GUI rectangular selection tool (radius rounds its corners).

• x0 (number) — First corner.
• y0 (number)
• x1 (number) — Opposite corner (inclusive).
• y1 (number)
• opts (table, optional)
  • mode (SelectionCombineMode: "replace" | "add" | "subtract" | "intersect"; default "replace") — How the new shape combines with the current selection.
  • radius (an integer 0–1024 for every corner, or a list of four { topLeft, topRight, bottomRight, bottomLeft }; default context.selectionCornerRadius) — Rounds the corners, in pixels (0 = square): one radius for all four, or one per corner going clockwise from the top-left. Each is clamped to half the smaller side.

Returns nothing.

app.setSelection(x, y, width, height, mask?) — changes, undoable

Replaces the selection with a rectangle, or with any shape via mask.

• x (number)
• y (number)
• width (number)
• height (number)
• mask (table, optional) — Flat 0/1 list (width*height, row-major — the shape app.getSelection returns) selecting only those pixels of the rectangle; omitted = the whole rectangle.

Returns nothing.

As Markdown: selection.md.