Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/aseprite/aseprite/llms.txt

Use this file to discover all available pages before exploring further.

A sprite is the fundamental container in Aseprite that holds all the elements of your pixel art project. It’s essentially a canvas that contains layers, frames, palettes, and all the visual data for your artwork.

​
What is a Sprite?

In Aseprite, a sprite represents a complete document with specific dimensions, a color mode, and a collection of visual elements organized in layers and frames. Think of it as the “project file” that contains everything about your artwork.
Every sprite has a fixed width and height measured in pixels, with a maximum size of 65535×65535 pixels.

​
Creating a Sprite

You can create sprites programmatically using the Lua API: 
-- Create a 32x64 pixel sprite (RGB mode by default)
local sprite = Sprite(32, 64)

-- Create a sprite with a specific color mode
local indexedSprite = Sprite(32, 32, ColorMode.INDEXED)

-- Create using named parameters
local sprite = Sprite{
  width = 100,
  height = 100,
  colorMode = ColorMode.RGB
}

-- Load an existing sprite from file
local sprite = Sprite{ fromFile = "path/to/file.aseprite" }

​
Sprite Properties

​
Dimensions

Every sprite has specific dimensions that define its canvas size: 
local sprite = Sprite(32, 64)
print(sprite.width)   -- 32
print(sprite.height)  -- 64
print(sprite.bounds)  -- Rectangle{x=0, y=0, width=32, height=64}

​
Color Mode

The color mode determines how pixel data is stored and displayed. See Color Modes for detailed information. 
local sprite = Sprite(32, 32)
print(sprite.colorMode)  -- ColorMode.RGB (default)

-- Color mode affects how pixels are stored
local indexed = Sprite(32, 32, ColorMode.INDEXED)

​
Transparent Color

For indexed sprites, you can specify which palette index represents transparency: 
local sprite = Sprite(32, 32, ColorMode.INDEXED)
print(sprite.transparentColor)  -- 0 (default)

sprite.transparentColor = 8  -- Set index 8 as transparent

​
Pixel Ratio

Pixel ratio allows you to define non-square pixels, useful for emulating retro systems: 
local sprite = Sprite(320, 200)
print(sprite.pixelRatio)  -- Size{1, 1} (default - square pixels)

-- Set 3:2 pixel ratio (wider pixels)
sprite.pixelRatio = Size{3, 2}

​
Grid Settings

Sprites can have grid settings that help with alignment and tiling: 
local sprite = Sprite(32, 32)
-- Default grid is 16x16
print(sprite.gridBounds)  -- Rectangle{0, 0, 16, 16}

-- Set custom grid (8x8 tiles starting at origin)
sprite.gridBounds = Rectangle{0, 0, 8, 8}

-- Offset grid (8x8 tiles starting at 2,3)
sprite.gridBounds = Rectangle{2, 3, 8, 8}

​
Working with Sprite Content

​
Layers

Sprites contain a hierarchy of layers. See Layers for details. 
local sprite = Sprite(32, 32)

-- Access layers
local layer = sprite.layers[1]
print(#sprite.layers)  -- Number of top-level layers

-- Add new layer
local newLayer = sprite:newLayer()

​
Frames

Sprites can have multiple frames for animation. See Frames for details. 
local sprite = Sprite(32, 32)
print(#sprite.frames)  -- 1 (default)

-- Add frames
sprite:newFrame()
print(#sprite.frames)  -- 2

​
Palettes

Each sprite has one or more palettes. See Palettes for details. 
local sprite = Sprite(32, 32, ColorMode.INDEXED)
local palette = sprite.palettes[1]
print(#palette)  -- 256 (default palette size)

​
Sprite Types

​
Standard Sprites

Most sprites are created with a transparent background layer: 
-- Creates sprite with one transparent layer
local sprite = Sprite(32, 32)

​
Background Layer

Sprites can have a locked background layer: 
local sprite = Sprite(32, 32)
local bg = sprite.layers[1]
bg:setBackground(true)  -- Make it a background layer

print(sprite:isOpaque())  -- true (has visible background)

​
Tilemap Sprites

Sprites can use tilesets for efficient tile-based graphics: 
-- Check if sprite uses tilesets
if sprite:hasTilesets() then
  local tilesets = sprite:tilesets()
end

​
Common Operations

​
Duplicating Sprites

local original = Sprite(32, 32)
original:newLayer()
original:newLayer()

-- Clone the sprite
local copy = Sprite(original)
print(#copy.layers)  -- Same as original

​
Flattening

local sprite = Sprite(32, 32)
sprite:newLayer()
sprite:newLayer()
print(#sprite.layers)  -- 3

sprite:flatten()  -- Merge all layers
print(#sprite.layers)  -- 1

​
Saving Sprites

local sprite = Sprite(32, 32)

-- Save as .aseprite file
sprite:saveAs("myart.aseprite")

-- Save as PNG
sprite:saveAs("myart.png")

-- Save a copy without changing the sprite's filename
sprite:saveCopyAs("backup.aseprite")

​
Sprite Lifecycle

​
Checking Validity

local sprite = Sprite(32, 32)
print(sprite.isValid)  -- true

sprite:close()
print(sprite.isValid)  -- false
After closing a sprite, any references to it become invalid. Always check isValid before using a sprite reference that might have been closed.

​
Undo/Redo

local sprite = Sprite(32, 32)

-- Make changes
sprite:resize(64, 64)
print(sprite.undoHistory.undoSteps)  -- 1

app.undo()
print(sprite.width)  -- 32 (reverted)

​
Best Practices

Select your color mode based on your target:
  • RGB: Modern games, web graphics, full-color artwork
  • Indexed: Retro games, limited palettes, small file sizes
  • Grayscale: Black and white artwork, alpha masks
Consider your target platform:
  • Game sprites: Often powers of 2 (32×32, 64×64)
  • Pixel art: Common sizes like 16×16, 32×32, 48×48
  • Maximum size: 65535×65535 pixels
Set grid bounds to match your tile size for easier alignment and drawing of tile-based graphics.

​
Related Concepts

Layers

Learn about organizing content in layers

Frames

Understand animation frames

Color Modes

Explore different color modes

Palettes

Work with color palettes

​
API Reference

For complete API documentation, see:

Build docs developers (and LLMs) love

Get started for freeTalk to us