Sprite Sheet Generation

Aseprite’s CLI can generate sprite sheets (texture atlases) from your animations, complete with JSON metadata for use in game engines.

Basic Sprite Sheet Export

Generate a sprite sheet with accompanying JSON data:

aseprite --batch animation.ase \
  --sheet spritesheet.png \
  --data spritesheet.json

This creates:

spritesheet.png - The texture atlas
spritesheet.json - Metadata with frame positions and sizes

Sheet Layout Types

Control how frames are arranged in the sprite sheet:

Horizontal Layout

aseprite --batch animation.ase \
  --sheet-type horizontal \
  --sheet output.png \
  --data output.json

Arranges all frames in a single horizontal row.

Vertical Layout

aseprite --batch animation.ase \
  --sheet-type vertical \
  --sheet output.png \
  --data output.json

Arranges all frames in a single vertical column.

Rows Layout

aseprite --batch animation.ase \
  --sheet-type rows \
  --sheet-columns 8 \
  --sheet output.png \
  --data output.json

Arranges frames in rows with a fixed number of columns.

Columns Layout

aseprite --batch animation.ase \
  --sheet-type columns \
  --sheet-rows 8 \
  --sheet output.png \
  --data output.json

Arranges frames in columns with a fixed number of rows.

Packed Layout

aseprite --batch animation.ase \
  --sheet-type packed \
  --sheet output.png \
  --data output.json

Or use the shorthand:

aseprite --batch animation.ase \
  --sheet-pack \
  --sheet output.png \
  --data output.json

Uses a bin-packing algorithm to minimize texture size.

Sheet Dimensions

Fixed Width and Height

aseprite --batch animation.ase \
  --sheet-width 1024 \
  --sheet-height 1024 \
  --sheet output.png \
  --data output.json

Fixed Columns

aseprite --batch animation.ase \
  --sheet-type rows \
  --sheet-columns 10 \
  --sheet output.png \
  --data output.json

Fixed Rows

aseprite --batch animation.ase \
  --sheet-type columns \
  --sheet-rows 10 \
  --sheet output.png \
  --data output.json

Data Formats

Choose the JSON data format:

JSON Hash (Default)

aseprite --batch animation.ase \
  --format json-hash \
  --sheet output.png \
  --data output.json

Outputs frame data as an object with frame names as keys:

{
  "frames": {
    "frame_0": { "frame": { "x": 0, "y": 0, "w": 32, "h": 32 } },
    "frame_1": { "frame": { "x": 32, "y": 0, "w": 32, "h": 32 } }
  }
}

JSON Array

aseprite --batch animation.ase \
  --format json-array \
  --sheet output.png \
  --data output.json

Outputs frame data as an array:

{
  "frames": [
    { "frame": { "x": 0, "y": 0, "w": 32, "h": 32 } },
    { "frame": { "x": 32, "y": 0, "w": 32, "h": 32 } }
  ]
}

Padding Options

Border Padding

Add padding around the entire texture:

aseprite --batch animation.ase \
  --border-padding 2 \
  --sheet output.png \
  --data output.json

Shape Padding

Add padding between frames:

aseprite --batch animation.ase \
  --shape-padding 2 \
  --sheet output.png \
  --data output.json

Inner Padding

Add padding inside each frame:

aseprite --batch animation.ase \
  --inner-padding 1 \
  --sheet output.png \
  --data output.json

Combined Padding

aseprite --batch animation.ase \
  --border-padding 4 \
  --shape-padding 2 \
  --inner-padding 1 \
  --sheet output.png \
  --data output.json

Extrude Edges

Duplicate edge pixels to prevent texture bleeding:

aseprite --batch animation.ase \
  --extrude \
  --sheet output.png \
  --data output.json

Splitting Options

Split Layers

Create separate sprite sheets for each layer:

aseprite --batch character.ase \
  --split-layers \
  --sheet character-{layer}.png \
  --data character-{layer}.json

Split Tags

Create separate sprite sheets for each animation tag:

aseprite --batch animations.ase \
  --split-tags \
  --sheet {tag}.png \
  --data {tag}.json

Split Slices

Create separate files for each slice:

aseprite --batch tileset.ase \
  --split-slices \
  --sheet tile-{slice}.png \
  --data tile-{slice}.json

Split Grid

Split by grid tiles:

aseprite --batch tileset.ase \
  --split-grid \
  --sheet tiles.png \
  --data tiles.json

Layer Filtering

Specific Layers Only

aseprite --batch character.ase \
  --layer "Body" \
  --layer "Head" \
  --sheet output.png \
  --data output.json

Exclude Layers

aseprite --batch character.ase \
  --ignore-layer "Background" \
  --sheet output.png \
  --data output.json

Include Hidden Layers

aseprite --batch character.ase \
  --all-layers \
  --sheet output.png \
  --data output.json

Tag-Based Export

Export Specific Tag

aseprite --batch animations.ase \
  --tag "walk" \
  --sheet walk.png \
  --data walk.json

With Subtags

aseprite --batch animations.ase \
  --tag "main" \
  --play-subtags \
  --sheet output.png \
  --data output.json

Frame Filtering

Frame Range

aseprite --batch animation.ase \
  --frame-range 0,10 \
  --sheet output.png \
  --data output.json

Ignore Empty Frames

aseprite --batch animation.ase \
  --ignore-empty \
  --sheet output.png \
  --data output.json

Merge Duplicate Frames

aseprite --batch animation.ase \
  --merge-duplicates \
  --sheet output.png \
  --data output.json

This reuses the same texture region for identical frames, reducing file size.

Trimming

Trim Individual Cels

aseprite --batch animation.ase \
  --trim \
  --sheet output.png \
  --data output.json

Trims transparent pixels from each frame individually.

Trim Entire Sprite

aseprite --batch animation.ase \
  --trim-sprite \
  --sheet output.png \
  --data output.json

Trims the sprite as a whole before generating the sheet.

Trim by Grid

aseprite --batch tileset.ase \
  --trim-by-grid \
  --sheet output.png \
  --data output.json

Metadata Options

Include Layers in Metadata

aseprite --batch character.ase \
  --list-layers \
  --sheet output.png \
  --data output.json

Include Layer Hierarchy

aseprite --batch character.ase \
  --list-layer-hierarchy \
  --sheet output.png \
  --data output.json

Include Tags in Metadata

aseprite --batch animation.ase \
  --list-tags \
  --sheet output.png \
  --data output.json

Include Slices in Metadata

aseprite --batch tileset.ase \
  --list-slices \
  --sheet output.png \
  --data output.json

Custom Naming

Filename Format

aseprite --batch animation.ase \
  --filename-format "{title}-{tag}-{frame}" \
  --sheet output.png \
  --data output.json

Tagname Format

aseprite --batch animation.ase \
  --tagname-format "{title}_{tag}" \
  --sheet output.png \
  --data output.json

Tileset Export

Export only tilesets from tilemap layers:

aseprite --batch tilemap.ase \
  --export-tileset \
  --sheet tileset.png \
  --data tileset.json

Complete Examples

Game Character Sprite Sheet

aseprite --batch character.ase \
  --sheet-type packed \
  --shape-padding 2 \
  --border-padding 4 \
  --trim \
  --ignore-empty \
  --merge-duplicates \
  --list-tags \
  --sheet character.png \
  --data character.json

Multi-Animation Export

aseprite --batch animations.ase \
  --split-tags \
  --sheet-type rows \
  --sheet-columns 8 \
  --trim \
  --list-layers \
  --sheet {tag}.png \
  --data {tag}.json

Layered Character Parts

aseprite --batch character.ase \
  --split-layers \
  --sheet-pack \
  --shape-padding 2 \
  --trim \
  --sheet parts/{layer}.png \
  --data parts/{layer}.json

Optimized for Game Engine

aseprite --batch sprite.ase \
  --sheet-type packed \
  --sheet-width 2048 \
  --sheet-height 2048 \
  --extrude \
  --shape-padding 1 \
  --border-padding 1 \
  --trim \
  --ignore-empty \
  --merge-duplicates \
  --format json-hash \
  --list-tags \
  --sheet atlas.png \
  --data atlas.json

Processing Multiple Files

Generate sprite sheets for multiple source files:

aseprite --batch character1.ase character2.ase character3.ase \
  --sheet-pack \
  --sheet {title}.png \
  --data {title}.json

Or use wildcards:

aseprite --batch *.ase \
  --sheet-pack \
  --shape-padding 2 \
  --trim \
  --sheet output/{title}.png \
  --data output/{title}.json

Command Line

Documentation Index

​Basic Sprite Sheet Export

​Sheet Layout Types

​Horizontal Layout

​Vertical Layout

​Rows Layout

​Columns Layout

​Packed Layout

​Sheet Dimensions

​Fixed Width and Height

​Fixed Columns

​Fixed Rows

​Data Formats

​JSON Hash (Default)

​JSON Array

​Padding Options

​Border Padding

​Shape Padding

​Inner Padding

​Combined Padding

​Extrude Edges

​Splitting Options

​Split Layers

​Split Tags

​Split Slices

​Split Grid

​Layer Filtering

​Specific Layers Only

​Exclude Layers

​Include Hidden Layers

​Tag-Based Export

​Export Specific Tag

​With Subtags

​Frame Filtering

​Frame Range

​Ignore Empty Frames

​Merge Duplicate Frames

​Trimming

​Trim Individual Cels

​Trim Entire Sprite

​Trim by Grid

​Metadata Options

​Include Layers in Metadata

​Include Layer Hierarchy

​Include Tags in Metadata

​Include Slices in Metadata

​Custom Naming

​Filename Format

​Tagname Format

​Tileset Export

​Complete Examples

​Game Character Sprite Sheet

​Multi-Animation Export

​Layered Character Parts

​Optimized for Game Engine

​Processing Multiple Files

Build docs developers (and LLMs) love