Documentation / generated/aseprite-operations.md
Core 11629ae · View or edit Markdown on GitHub ↗

Aseprite operation reference

Generated from the current declarations. Do not edit this file by hand.

Types, limits and defaults below describe resolved values. Runtime expressions must produce these types. Unknown options are rejected; defaults apply only when omitted. Constructor options must be constant after document composition.

Index#

circle, frame, importImage, layer, palette, pixel, rect, sprite, tag

circle#

Fills a raster disc centred on pixel (x, y): every pixel whose squared distance from the centre is at most radius squared, on a named layer and frame. Radius 0 draws a single pixel. Pixels are replaced, not blended: an opaque colour overwrites the selected layer and frame, and transparent [0, 0, 0, 0] erases. Choose it for round shapes and, with a transparent colour, for round cut-outs.

Common mistakes and assumptions:

• The full square from (x - radius, y - radius) to (x + radius, y + radius) must fit in the canvas, so a disc cannot touch beyond the edge. It must take its sprite input from the immediately preceding node.
• The disc always has an odd diameter (2 x radius + 1 pixels); an even-width circle is not possible.

Native binding: Image:drawPixel. Output kind: ["sprite"].

frame#

Appends one new empty animation frame after the last frame, with its own display duration. Choose it to build an animation; frames are numbered from 1 in the order they are added, and every layer is transparent in the new frame until drawing nodes with that frame number paint it. Each frame becomes one cell of the horizontal sheet.png.

Common mistakes and assumptions:

• Nothing is copied from the previous frame; redraw the background on the new frame (as the animation example does).
• At most 32 frames, and the sheet width (canvas width x frames) may not exceed 8192 pixels. It must take its sprite input from the immediately preceding node.

Native binding: Sprite:newEmptyFrame. Output kind: ["sprite"].

importImage#

Place captured PNG artwork into an existing named layer and frame at integer canvas coordinates. Choose this to turn prepared raster assets into editable cels while retaining procedural drawing and animation tags. The declared image rectangle replaces existing pixels in that cel, including transparent pixels which erase; transparent top-layer pixels reveal lower layers in the flattened preview. Captures, reopened cels and both PNG publications are independently checked sample by sample.

Common mistakes and assumptions:

• Only metadata-free, noninterlaced RGBA8 PNG with alpha 0 or 255 is supported. Strip profiles/metadata; no scaling, clipping, colour conversion, arbitrary paths in Lua or authored scripts.
• Plan checks declared dimensions and placement; execution checks actual captured PNG dimensions and samples. Original source paths are never opened by the native worker.

Native binding: Image{fromFile}; Sprite:newCel; Cel.image. Output kind: ["sprite"].

layer#

Adds a new, empty, visible image layer with normal blending on top of all existing layers. Choose it to keep parts of the artwork separately editable in Aseprite, such as a background and a foreground; in the flattened preview and sheet, opaque pixels on later layers cover those on earlier layers. Drawing nodes select the layer by its name.

Common mistakes and assumptions:

• At most 16 layers in total, including the sprite's initial layer; names must be unique.
• It must take its sprite input from the immediately preceding node.

Native binding: Sprite:newLayer. Output kind: ["sprite"].

palette#

Replaces the sprite's whole palette with the listed RGBA colours, in order. Because Schemaxis sprites use RGB colour mode, the palette is saved in sprite.aseprite as the colour swatches offered when editing in Aseprite; it does not recolour existing pixels and does not restrict which colours drawing nodes may use.

Common mistakes and assumptions:

• Changing a palette entry never changes pixels already drawn; change the colour of the drawing nodes instead.
• It must take its sprite input from the immediately preceding node.

Native binding: Sprite:setPalette. Output kind: ["sprite"].

pixel#

Sets exactly one pixel at zero-based column x and row y (origin at the top-left) on a named layer and frame. Pixels are replaced, not blended: an opaque colour overwrites the selected layer and frame, and transparent [0, 0, 0, 0] erases. Choose it for highlights, outlines and single details; use rect or circle for filled areas.

Common mistakes and assumptions:

• The layer and frame must already exist at this point of the chain; otherwise planning fails with INVALID_DRAW. It must take its sprite input from the immediately preceding node.

Native binding: Image:drawPixel. Output kind: ["sprite"].

rect#

Fills an axis-aligned rectangle of width x height pixels whose top-left pixel is at (x, y), covering columns x to x + width - 1 and rows y to y + height - 1, on a named layer and frame. Pixels are replaced, not blended: an opaque colour overwrites the selected layer and frame, and transparent [0, 0, 0, 0] erases. Choose it for backgrounds, panels and blocks; a full-canvas rect is the usual way to give a frame an opaque background.

Common mistakes and assumptions:

• The whole rectangle must lie inside the canvas (x + width and y + height at most the canvas size); it is rejected, not clipped. It must take its sprite input from the immediately preceding node.

Native binding: Image:drawPixel. Output kind: ["sprite"].

sprite#

Starts every Aseprite document: creates a new RGB sprite canvas of width x height pixels with one transparent frame, one normal image layer and an initial palette. It must be the first node and appear only once; every later operation modifies this same sprite in sequence. The finished sprite is published as editable sprite.aseprite, preview.png (first frame), sheet.png (all frames in a row) and sheet.json (frame rectangles, durations and tags).

Common mistakes and assumptions:

• Choose the canvas size first: drawing nodes are checked against it, and the canvas cannot be resized later in the chain.
• Larger canvases leave less room for layers and frames: width x height x frames x layers may not exceed 262144 (a 256 x 256 canvas allows only four layer-frame cels in total). Native acceptance covers the bundled icon and two-layer, two-frame animation examples with Aseprite 1.3.x in batch mode; it does not review GUI appearance.

Native binding: Sprite. Output kind: ["sprite"].

Inputs: none.

tag#

Names an inclusive range of existing frames and records its playback direction as an Aseprite animation tag. Tags change no pixels; they are saved in sprite.aseprite and listed in sheet.json so that a game engine or an artist in Aseprite can play that sequence. Choose it to label animations such as walk or blink when the sprite has several frames.

Common mistakes and assumptions:

• Add the tag after the frame nodes it covers: toFrame may not exceed the number of frames created so far.
• Schemaxis's FFmpeg sheet encoding keeps tags as metadata only; they do not select or reorder video playback. It must take its sprite input from the immediately preceding node.

Native binding: Sprite:newTag. Output kind: ["sprite"].