# pxstud.io Lua scripting API — Cels

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

### Cels
A cel is one layer's image on one frame. Move, clear and link them in blocks.

#### `app.clearCels(cels)` — changes, undoable, refused on a locked layer
Deletes several cels at once as a single undo step: images on image layers, tile placements on tilemap layers, placements on reference layers. Cels that don't exist are ignored.

- `cels` (table) — Array of { layerId = ..., frameId = ... } tables naming the cels to delete.

Returns nothing.

#### `app.getCel(layerId, frameId)` — reads
The cel at layerId/frameId in the app.getCels shape, or nil if that layer has no image (or tile placements) on that frame.

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

Returns (table): Cel table or nil.

#### `app.getCelLink(layerId, frameId)` — reads
If the cel at layerId/frameId is linked, the frame id of the source cel whose image it shares; otherwise nil.

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

Returns (string): Source frame id or nil.

#### `app.getCels()` — reads
Every cel (a layer's image on one frame) as { layerId, frameId, x, y, width, height, opacity, zIndex (draw-order shift, only when not 0), linkedTo (frame id of the shared image, linked cels only) }, layer by layer bottom-first then frame order. A tilemap frame with placements (or a link) is a cel too: x/y/width/height are its placements' pixel bounds. Pixel data is read with app.getImage, placements with app.getTilemap.

Returns (table): Array of cel tables.

#### `app.getLinkedFrames()` — reads
Every linked frame on tilemap and reference layers as { layerId, frameId, linkedTo (the frame whose tile placements or placement it shares) }, layer by layer bottom-first then frame order. Image layers report their links through app.getCels' linkedTo.

Returns (table): Array of link tables.

#### `app.linkCels(layerId, frameIds)` — changes, undoable, refused on a locked layer
Links the cels of a layer on the given frames so they share one image (editing one edits all); on a tilemap layer they share tile placements, on a reference layer the placement. Throws if the first frame has no cel.

- `layerId` (string)
- `frameIds` (table) — Array of frame ids. The first frame's cel image is shared by all of them; their own cels are replaced by links.

Returns nothing.

#### `app.moveCels(cels, dLayer, dFrame)` — changes, undoable, refused on a locked layer
Moves a block of cels by (dLayer, dFrame), overwriting the destination cells, as a single undo step. Image cels move between image layers, tile placements between tilemap layers sharing a tileset, reference placements only along their own layer. Throws if the move leaves the grid or breaks that rule.

- `cels` (table) — Array of { layerId = ..., frameId = ... } tables naming the block of cels to move.
- `dLayer` (number) — Layer-index delta; positive moves up the stack.
- `dFrame` (number) — Frame-order delta; positive moves to later frames.

Returns nothing.

#### `app.setCelProps(layerId, frameId, props)` — changes, undoable, refused on a locked layer
Updates properties of the cel at a layer and frame (an image cel or a tilemap frame): its opacity and z-index.

- `layerId` (string)
- `frameId` (string)
- `props` (table) — Omitted keys are left unchanged.
  - `opacity` (number 0–1) — Cel opacity, combined with the layer's. A linked cel shares its source's (setting it on any cel of the link sets it for all). The Background layer's cels stay at 1.
  - `zIndex` (integer -32767–32767) — Aseprite's cel z-index: shifts this cel's drawing order among the layers of its group on this frame (draw order = layer position + zIndex). 0 = the layer's own position.

Returns nothing.

#### `app.unlinkCels(layerId, frameIds)` — changes, undoable, refused on a locked layer
Turns linked cels back into independent copies of the shared image (tile placements, reference placement). Listing the frame the others link to unlinks it too; the rest stay linked together. Unlinked cels are left alone.

- `layerId` (string)
- `frameIds` (table) — Array of frame ids whose linked cels become independent copies.

Returns nothing.