Sprite

A Sprite represents a complete sprite document with layers, frames, and all sprite properties.

Constructor

Sprite(width, height [, colorMode])

width

number

required

Width in pixels.

height

number

required

Height in pixels.

colorMode

ColorMode

Color mode (default: RGB).

local sprite = Sprite(32, 64)
local indexedSprite = Sprite(32, 32, ColorMode.INDEXED)

Sprite(spec)

spec

ImageSpec

Image specification.

local sprite = Sprite(ImageSpec{ width=64, height=64, colorMode=ColorMode.RGB })

Sprite(otherSprite)

otherSprite

Sprite

required

Sprite to duplicate.

Creates a copy of an existing sprite.

local copy = Sprite(originalSprite)

fromFile

string

required

Path to sprite file.

local sprite = Sprite{ fromFile="path/to/sprite.aseprite" }

Properties

number

Unique sprite identifier.

filename

string

File path of the sprite.

isModified

boolean

True if the sprite has unsaved changes.

width

number

Sprite width in pixels.

height

number

Sprite height in pixels.

colorMode

ColorMode

Color mode (RGB, GRAYSCALE, or INDEXED).

colorSpace

ColorSpace

Color space profile.

spec

ImageSpec

Image specification.

selection

Selection

Current selection mask.

frames

Frames

Collection of all frames.

palettes

Palettes

Collection of palettes.

layers

array

Array of root layers.

cels

array

Array of all cels.

Methods

sprite:resize(width, height)

width

number

required

New width.

height

number

required

New height.

Resizes the sprite canvas and all images.

sprite:resize(64, 64)

sprite:crop(rectangle)

rectangle

Rectangle

Crop bounds (uses selection if not specified).

Crops the sprite to the specified rectangle or current selection.

sprite:crop(Rectangle(10, 10, 20, 20))
sprite:crop()  -- Crops to selection

sprite:saveAs(filename)

filename

string

required

File path to save to.

Saves the sprite and sets it as the current filename.

sprite:saveAs("output.aseprite")

sprite:saveCopyAs(filename)

filename

string

required

File path to save to.

Saves a copy without changing the current filename.

sprite:saveCopyAs("backup.aseprite")

sprite:close()

Closes the sprite.

sprite:close()

sprite:loadPalette(filename)

filename

string

required

Palette file path.

Loads a palette from a file.

sprite:loadPalette("palette.gpl")

sprite:setPalette(palette)

palette

Palette

required

Palette to set.

Sets the sprite’s palette.

local pal = Palette(16)
sprite:setPalette(pal)

sprite:assignColorSpace(colorSpace)

colorSpace

ColorSpace

required

Color space to assign.

Assigns a color space without converting colors.

sprite:assignColorSpace(ColorSpace{ sRGB=true })

sprite:convertColorSpace(colorSpace)

colorSpace

ColorSpace

required

Color space to convert to.

Converts colors to a different color space.

sprite:convertColorSpace(ColorSpace{ sRGB=true })

sprite:flatten()

Flattens all layers into one.

sprite:flatten()

sprite:newLayer()

Creates and returns a new layer.

local layer = sprite:newLayer()
layer.name = "New Layer"

sprite:newGroup()

Creates and returns a new layer group.

local group = sprite:newGroup()
group.name = "Group 1"

sprite:deleteLayer(layer)

layer

Layer | string

required

Layer object or layer name.

Deletes a layer.

sprite:deleteLayer(layer)
sprite:deleteLayer("Layer 1")

sprite:newFrame([frameNumber])

frameNumber

number

Frame position (default: adds at end).

Creates a new frame by copying the specified frame.

local frame = sprite:newFrame()
local frame2 = sprite:newFrame(2)

sprite:newEmptyFrame([frameNumber])

frameNumber

number

Frame position (default: adds at end).

Creates a new empty frame.

local frame = sprite:newEmptyFrame()

sprite:deleteFrame(frameNumber)

frameNumber

number

required

Frame to delete.

sprite:deleteFrame(2)

sprite:newCel(layer, frame [, image] [, position])

layer

Layer

required

Target layer.

frame

Frame

required

Target frame.

image

Image

Image for the cel.

position

Point

Cel position.

Creates a new cel.

local cel = sprite:newCel(layer, 1)
local cel2 = sprite:newCel(layer, 2, image, Point(10, 10))

sprite:deleteCel(cel)

cel

Cel

required

Cel to delete.

sprite:deleteCel(cel)

sprite:newTag(from, to)

from

number

required

Start frame.

number

required

End frame.

Creates a new tag.

local tag = sprite:newTag(1, 10)
tag.name = "Walk Cycle"

sprite:deleteTag(tag)

tag

Tag | string

required

Tag object or tag name.

sprite:deleteTag(tag)
sprite:deleteTag("Walk Cycle")

sprite:newSlice([bounds])

bounds

Rectangle

Initial slice bounds.

Creates a new slice.

local slice = sprite:newSlice(Rectangle(0, 0, 16, 16))
slice.name = "Button"

sprite:deleteSlice(slice)

slice

Slice | string

required

Slice object or slice name.

sprite:deleteSlice(slice)
sprite:deleteSlice("Button")

Examples

Creating and Modifying a Sprite

local sprite = Sprite(32, 32)
sprite.filename = "my-sprite.aseprite"

local layer = sprite:newLayer()
layer.name = "Main Layer"

local cel = sprite:newCel(layer, 1)
local image = cel.image
for y=0,31 do
  for x=0,31 do
    image:drawPixel(x, y, Color{ r=x*8, g=y*8, b=128 })
  end
end

sprite:saveAs("my-sprite.aseprite")

Working with Tags

local sprite = app.sprite

local walkTag = sprite:newTag(1, 8)
walkTag.name = "Walk"
walkTag.color = Color{ r=255, g=0, b=0 }

local jumpTag = sprite:newTag(9, 12)
jumpTag.name = "Jump"
jumpTag.color = Color{ r=0, g=255, b=0 }

Getting Started

API Reference

Examples

Sprite

Constructor

Sprite(width, height [, colorMode])

Sprite(spec)

Sprite(otherSprite)

Sprite

Properties

Methods

sprite:resize(width, height)

sprite:crop(rectangle)

sprite:saveAs(filename)

sprite:saveCopyAs(filename)

sprite:close()

sprite:loadPalette(filename)

sprite:setPalette(palette)

sprite:assignColorSpace(colorSpace)

sprite:convertColorSpace(colorSpace)

sprite:flatten()

sprite:newLayer()

sprite:newGroup()

sprite:deleteLayer(layer)

sprite:newFrame([frameNumber])

sprite:newEmptyFrame([frameNumber])

sprite:deleteFrame(frameNumber)

sprite:newCel(layer, frame [, image] [, position])

sprite:deleteCel(cel)

sprite:newTag(from, to)

sprite:deleteTag(tag)

sprite:newSlice([bounds])

sprite:deleteSlice(slice)

Examples

Creating and Modifying a Sprite

Working with Tags

Build docs developers (and LLMs) love

Getting Started

API Reference

Examples

​Constructor

​Sprite(width, height [, colorMode])

​Sprite(spec)

​Sprite(otherSprite)

​Sprite

​Properties

​Methods

​sprite:resize(width, height)

​sprite:crop(rectangle)

​sprite:saveAs(filename)

​sprite:saveCopyAs(filename)

​sprite:close()

​sprite:loadPalette(filename)

​sprite:setPalette(palette)

​sprite:assignColorSpace(colorSpace)

​sprite:convertColorSpace(colorSpace)

​sprite:flatten()

​sprite:newLayer()

​sprite:newGroup()

​sprite:deleteLayer(layer)

​sprite:newFrame([frameNumber])

​sprite:newEmptyFrame([frameNumber])

​sprite:deleteFrame(frameNumber)

​sprite:newCel(layer, frame [, image] [, position])

​sprite:deleteCel(cel)

​sprite:newTag(from, to)

​sprite:deleteTag(tag)

​sprite:newSlice([bounds])

​sprite:deleteSlice(slice)

​Examples

​Creating and Modifying a Sprite

​Working with Tags

Build docs developers (and LLMs) love

Constructor

Sprite(width, height [, colorMode])

Sprite(spec)

Sprite(otherSprite)

Sprite

Properties

Methods

sprite:resize(width, height)

sprite:crop(rectangle)

sprite:saveAs(filename)

sprite:saveCopyAs(filename)

sprite:close()

sprite:loadPalette(filename)

sprite:setPalette(palette)

sprite:assignColorSpace(colorSpace)

sprite:convertColorSpace(colorSpace)

sprite:flatten()

sprite:newLayer()

sprite:newGroup()

sprite:deleteLayer(layer)

sprite:newFrame([frameNumber])

sprite:newEmptyFrame([frameNumber])

sprite:deleteFrame(frameNumber)

sprite:newCel(layer, frame [, image] [, position])

sprite:deleteCel(cel)

sprite:newTag(from, to)

sprite:deleteTag(tag)

sprite:newSlice([bounds])

sprite:deleteSlice(slice)

Examples

Creating and Modifying a Sprite

Working with Tags