Expand description

Utilities for loading Aseprite files. This library directly reads the binary Aseprite files (file format specification) and does not require you to export files to JSON. This should make it fast enough to load your assets when the game boots up. You can also use it to build your own asset pipelines.

Note that this library can be rather slow when compiled without optimizations. We recommend that you override the optimization settings for this dependency in dev mode by adding the following to your Cargo.toml:

opt-level = 2  # or 3

This is not necessary if you already have a wildcard override. See Cargo profile overrides for more info.

Basic Usage

Load file

The easiest way is to use AsepriteFile::read_file to load a file.

use asefile::AsepriteFile;
let ase = AsepriteFile::read_file(&path).unwrap();

println!("Size: {}x{}", ase.width(), ase.height());
println!("Frames: {}", ase.num_frames());
println!("Layers: {}", ase.num_layers());

Save frame as image

Aseprite files consist of multiple layers. Usually you just want the final image. You can do this by using Frame::image. This will return an image::RgbaImage from the image library.

let image = ase.frame(0).image();
let output_path = output_dir.join("example.png");

This blends together all visible layers the same way Aseprite would.


You can access a Layer by name or by ID.

let layer = ase.layer(0);
println!("Name of layer 0: {}", layer.name());
let layer = ase.layer_by_name("Layer 1").unwrap();
println!("Layer 1 is visible? {}", layer.is_visible());


A cel is the intersection of a frame and a layer. Because of this there are multiple ways to access a cel:

let layer0 = ase.layer(0);
// These are all the same cel
let cel1 = layer0.frame(1);
let cel2 = ase.frame(1).layer(0);
let cel3 = ase.cel(1, 0); // or directly, which can avoid some borrowing issues

let image = cel1.image();


Since Aseprite 1.3 you can also create tilesets and tilemaps layers.

You access each tile separately, or export them all as one image which is one tile wide.

let num_tilesets = ase.tilesets().len();
let tileset = ase.tilesets().get(0).unwrap();

let all_tiles: RgbaImage = tileset.image();
let single_tile: RgbaImage = tileset.tile_image(1);
// Note: tile 0 is the empty tile
    tileset.tile_size().width() as u32
    tileset.tile_size().height() as u32 * tileset.tile_count()


Aseprite also supports tilemaps which are layers that are composed entirely out of tiles from a tileset.

You can export those layers as a single large image or you can do some custom processing by looking at the tile indexes in the layer.

let layer = ase.layer_by_name("Tilemap 1").unwrap().id();
let tilemap = ase.tilemap(layer, 0).unwrap();

// This is the same as getting the image for the cel.
let tilemap_image = tilemap.image();

let num_tiles_x = tilemap.width();
let num_tiles_y = tilemap.height();
let (tile_width, tile_height) = tilemap.tile_size();
// Get a specific tile. Always succeeds. If the tile is out of bounds returns
// the empty tile (id 0).
let tile = tilemap.tile(0, 1);
println!("tile at (0, 1) references tile from tileset: {}", tile.id());
// You can access the tileset right through the tilemap.
let image = tilemap.tileset().tile_image(tile.id());

User data

Aseprite gives you the option to annotate certain entities with custom data. Usually, that’s a color and a text field. Each of those entities has a user_data() method.


Utilities not directly related to Aseprite, but useful for processing the resulting image data. (Requires feature utils.)


A parsed Aseprite file.

A reference to a single Cel. A cel contains the image data at a specific layer and frame. In the timeline view these are the dots.

The color palette embedded in the file.

A single entry in a ColorPalette.

An external file. Used to reference external palettes or tilesets.

Unique identifier of a reference to an ExternalFile.

A map of ExternalFileId values to ExternalFile instances.

A reference to a single frame.

A reference to a single layer.

Various layer attributes.

An iterator over layers. See AsepriteFile::layers.

A slice is a region of the sprite with some attributes.

A devision of a Slice into nine regions for 9-slice scaling.

The position and shape of a Slice, starting at a given frame.

A tag is a grouping of one or more frames.

A tile is a reference to a single tile in a tilemap.

The size of a tile in pixels.

A reference to a tilemap.

A set of tiles of the same size.

A map from tileset ids (u32) to Tilesets.

User-provided metadata which can be attached to various items.


Describes how the tag’s frames should be animated.

An error occured while reading the Aseprite file.

Describes how the pixels from two layers are combined. See also Blend modes (Wikipedia)

Types of layer.

Pixel format of the source Aseprite file.

An error occured while generating a tileset image.

Type Definitions

A specialized Result type for Aseprite parsing functions.