Sprite Sheets

Overview

Sprite sheets (also called texture atlases) pack multiple animation frames or sprites into a single image file. This is the standard format for delivering game assets, as it reduces file count, improves loading performance, and simplifies asset management.

Aseprite provides powerful sprite sheet export options with automatic packing, trimming, and metadata generation.

Why Use Sprite Sheets?

Better Performance

One image loads faster than hundreds of individual frames. Reduces HTTP requests and disk I/O.

Smaller File Size

Eliminates redundant headers and metadata. Can be compressed more efficiently.

Easier Management

One file instead of many. Simpler version control and asset pipeline.

GPU Efficiency

Single texture binding. Enables efficient batching and rendering.

Exporting Sprite Sheets

Open Export Dialog

Go to File → Export → Export Sprite Sheet or press Ctrl/Cmd + Alt + Shift + S.

Choose Layout

Select how frames should be arranged:

Horizontal Strip: All frames in one row
Vertical Strip: All frames in one column
Square: Packed into a square grid
Packed: Optimal automatic packing

Configure Options

Set export parameters:

Trim empty pixels
Add borders/padding
Include metadata (JSON/XML)
Split layers or tags

Export

Choose your output format (PNG recommended) and export both the image and metadata.

Always export with metadata! The JSON or XML file tells your game engine where each frame is located.

Export Layouts

Horizontal Strip
Vertical Strip
Grid (Rows/Columns)
Packed

All frames arranged in a single row, left to right.Best for:

Simple animations with few frames
Side-scrolling game sprites
Quick manual implementation

# CLI: Export as horizontal strip
aseprite --batch sprite.aseprite \
  --sheet-type horizontal \
  --sheet output.png

Can become very wide with many frames. May hit texture size limits.

All frames arranged in a single column, top to bottom.Best for:

Top-down character animations
UI element states
Mobile-optimized assets

# CLI: Export as vertical strip
aseprite --batch sprite.aseprite \
  --sheet-type vertical \
  --sheet output.png

Frames arranged in a rectangular grid with specified dimensions.Best for:

Consistent frame sizes
Easy manual parsing
Traditional game engines

# CLI: Export as 4x4 grid
aseprite --batch sprite.aseprite \
  --sheet-type rows \
  --sheet-columns 4 \
  --sheet output.png

Most predictable layout. Easy to calculate frame positions manually.

Automatically packed for optimal space usage. Frames can have different sizes.Best for:

Production assets
Multiple animations in one sheet
Minimizing texture memory

# CLI: Export with optimal packing
aseprite --batch sprite.aseprite \
  --sheet-type packed \
  --sheet output.png \
  --data output.json

Most efficient use of texture space. Requires metadata for frame positions.

Export Options

Trimming

Remove transparent pixels around each frame to save space:

Trim Cels: Remove empty space from individual frames
Trim Sprite: Remove border space from entire sheet
Keep Sprite Size: Maintain original canvas size

# CLI: Export with trimming
aseprite --batch sprite.aseprite \
  --trim \
  --sheet output.png

Trimming significantly reduces texture memory but requires metadata to correctly position frames.

Borders and Padding

Add spacing between frames and around edges:

Border Padding: Space around entire sheet
Shape Padding: Space between individual frames
Inner Padding: Space inside each frame

# CLI: Add 1px padding between frames
aseprite --batch sprite.aseprite \
  --sheet-pack \
  --shape-padding 1 \
  --sheet output.png

Add 1-2px padding to prevent texture bleeding when using mipmaps or texture filtering.

Metadata Formats

Export frame position data in various formats:JSON Hash:

{
  "frames": {
    "sprite-0.aseprite": {
      "frame": { "x": 0, "y": 0, "w": 32, "h": 32 },
      "duration": 100
    }
  }
}

JSON Array:

{
  "frames": [
    {
      "filename": "sprite-0.aseprite",
      "frame": { "x": 0, "y": 0, "w": 32, "h": 32 }
    }
  ]
}

XML:

<sprite>
  <frame name="sprite-0" x="0" y="0" w="32" h="32" />
</sprite>

JSON is recommended for modern game engines. Most frameworks parse it automatically.

Layer Export Options

Control how layers are exported:

Merge Layers: Flatten all visible layers (default)
Split Layers: Export each layer as separate sheet
Split Tags: Export each animation tag as separate sheet
Split Grid: Export based on grid selection

# CLI: Split by animation tags
aseprite --batch sprite.aseprite \
  --split-tags \
  --sheet-type packed \
  --sheet output-{tag}.png \
  --data output-{tag}.json

Use {tag}, {layer}, or {tagframe} placeholders in filenames for automatic naming.

Command Line Export

Automate sprite sheet generation with the Aseprite CLI:

# Simple sprite sheet export
aseprite --batch input.aseprite \
  --sheet-type packed \
  --sheet output.png \
  --data output.json

CLI Placeholders:

{title}: Sprite filename without extension
{tag}: Current tag name
{layer}: Current layer name
{frame}: Current frame number
{tagframe}: Frame within current tag

Importing Sprite Sheets

Aseprite can also import sprite sheets back into frames:

Open Import Dialog

File → Import Sprite Sheet

Select the Image

Choose your sprite sheet PNG file.

Define Frame Layout

Tell Aseprite how frames are arranged:

Grid dimensions (rows × columns)
Or select frames manually

Import

Aseprite creates a new sprite with each frame on the timeline.

# CLI: Import sprite sheet
aseprite --batch \
  --sheet-type rows \
  --sheet-columns 8 \
  --sheet spritesheet.png \
  --save-as output.aseprite

Game Engine Integration

Unity
Godot
Phaser
Custom Engine

Import sprite sheets into Unity:

Import the PNG file into your Assets folder
Select it in the Project panel
Set Texture Type to Sprite (2D and UI)
Set Sprite Mode to Multiple
Open Sprite Editor
Use Slice → Automatic or import JSON metadata
Apply and create animations

Use a Unity sprite sheet plugin to automatically parse Aseprite JSON metadata.

Use sprite sheets in Godot:

Import the PNG file
Create an AnimatedSprite2D node
Create a SpriteFrames resource
Add frames from the sprite sheet
Or use an Aseprite importer plugin

# GDScript: Load sprite sheet
var texture = load("res://character-sheet.png")
var sprite_frames = SpriteFrames.new()

# Add frames (parse JSON for coordinates)
sprite_frames.add_frame("walk", atlas_texture)

The Godot Aseprite Importer plugin automatically handles JSON metadata.

Load sprite sheets in Phaser 3:

// Preload sprite sheet with JSON metadata
this.load.atlas(
  'character',
  'character-sheet.png',
  'character-sheet.json'
);

// Create animated sprite
this.anims.create({
  key: 'walk',
  frames: this.anims.generateFrameNames('character', {
    prefix: 'walk-',
    start: 0,
    end: 7
  }),
  frameRate: 10,
  repeat: -1
});

Phaser natively supports Aseprite JSON format! No conversion needed.

Parse Aseprite JSON in your engine:

// Example: Parse JSON metadata
fetch('sprite-sheet.json')
  .then(response => response.json())
  .then(data => {
    data.frames.forEach(frame => {
      const { x, y, w, h } = frame.frame;
      const duration = frame.duration;
      
      // Create frame object for your engine
      addFrame({
        texture: spriteSheetTexture,
        sourceRect: { x, y, width: w, height: h },
        duration: duration
      });
    });
  });

Optimization Tips

Use Power of 2 Sizes

Export sheets with dimensions like 512×512, 1024×1024, or 2048×2048 for best GPU compatibility.

Trim Transparent Pixels

Enable trimming to remove wasted space, especially for sparse animations.

Add Padding

Include 1-2px padding between frames to prevent texture bleeding with mipmaps.

Compress Wisely

Use PNG-8 for indexed color, PNG-24 for RGBA. Consider WebP for web games.

Split Large Sheets

Keep sheets under 2048×2048 for mobile compatibility. Split by animation or character.

Include Metadata

Always export JSON metadata. It’s tiny and makes integration much easier.

Advanced Techniques

Scripting Automation

Automate sprite sheet export with Lua:

-- Export all open sprites as sprite sheets
for i, sprite in ipairs(app.sprites) do
  app.command.ExportSpriteSheet {
    ui = false,
    type = "packed",
    textureFilename = sprite.filename:gsub(".aseprite", "-sheet.png"),
    dataFilename = sprite.filename:gsub(".aseprite", "-sheet.json"),
    dataFormat = "json-array",
    trim = true,
    shapePadding = 2
  }
end

Batch Processing

Process entire directories:

#!/bin/bash
# Export all characters as sprite sheets
for dir in characters/*/; do
  char=$(basename "$dir")
  aseprite --batch "$dir"*.aseprite \
    --sheet-type packed \
    --merge-duplicates \
    --trim \
    --sheet "output/$char-sheet.png" \
    --data "output/$char-sheet.json"
done

Multi-Character Sheets

Combine multiple sprites into one sheet:

# Combine all enemy sprites into one atlas
aseprite --batch \
  enemy1.aseprite \
  enemy2.aseprite \
  enemy3.aseprite \
  --sheet-type packed \
  --sheet enemies-atlas.png \
  --data enemies-atlas.json

Great for level-specific atlases that load all needed sprites at once.

Troubleshooting

Frames cut off or missing

Cause: Trim settings are too aggressiveFix: Disable trimming or adjust sprite canvas size to include padding

Texture bleeding between frames

Cause: No padding between frames with texture filtering enabledFix: Add 1-2px shape padding in export settings

Metadata not loading in game

Cause: Incorrect format or file pathFix: Verify JSON format matches engine expectations. Check file paths are relative.

Sprite sheet too large

Cause: Too many frames or not using packed layoutFix: Split into multiple sheets by animation tag or character state

Animation Timeline

Learn how to create the animations you’ll export

CLI Overview

Master command-line batch processing

GIF Export

Export animations as GIF files instead

Scripting API

Automate exports with Lua scripts

Get Started

Core Concepts

Drawing Tools

Advanced Features

Workspace

Import & Export

Overview

Why Use Sprite Sheets?

Better Performance

Smaller File Size

Easier Management

GPU Efficiency

Exporting Sprite Sheets

Export Layouts

Export Options

Command Line Export

Importing Sprite Sheets

Game Engine Integration

Optimization Tips

Use Power of 2 Sizes

Trim Transparent Pixels

Add Padding

Compress Wisely

Split Large Sheets

Include Metadata

Advanced Techniques

Troubleshooting

Animation Timeline

CLI Overview

GIF Export

Scripting API

Build docs developers (and LLMs) love

Get Started

Core Concepts

Drawing Tools

Advanced Features

Workspace

Import & Export

​Overview

​Why Use Sprite Sheets?

Better Performance

Smaller File Size

Easier Management

GPU Efficiency

​Exporting Sprite Sheets

​Export Layouts

​Export Options

​Command Line Export

​Importing Sprite Sheets

​Game Engine Integration

​Optimization Tips

Use Power of 2 Sizes

Trim Transparent Pixels

Add Padding

Compress Wisely

Split Large Sheets

Include Metadata

​Advanced Techniques

​Troubleshooting

​Related Features

Animation Timeline

CLI Overview

GIF Export

Scripting API

Build docs developers (and LLMs) love

Overview

Why Use Sprite Sheets?

Exporting Sprite Sheets

Export Layouts

Export Options

Command Line Export

Importing Sprite Sheets

Game Engine Integration

Optimization Tips

Advanced Techniques

Troubleshooting

Related Features