Cels

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.

As Markdown: cels.md.