Crate asefile

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:

[profile.dev.package.asefile]
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");
image.save(&output_path).unwrap();

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

Layers

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());

Cels

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);
let cel1 = layer0.frame(0);
let cel2 = ase.frame(0).layer(0);

let image = cel1.image();

Structs

AsepriteFile	A parsed Aseprite file.
Cel	A reference to a single Cel. This contains the image data at a specific layer and frame. In the timeline view these are the dots.
ColorPalette	The color palette embedded in the file.
ColorPaletteEntry	A single entry in a ColorPalette.
Frame	A reference to a single frame.
Layer	A reference to a single layer.
LayerFlags	Various layer attributes.
LayersIter	An iterator over layers. See AsepriteFile::layers.
Tag	A tag is a grouping of one or more frames.

Enums

AnimationDirection	Describes how the tag’s frames should be animated.
AsepriteParseError	An error occured while reading the Aseprite file.
BlendMode	Describes how the pixels from two layers are combined. See also Blend modes (Wikipedia)
PixelFormat	Pixel format of the source Aseprite file.

Type Definitions

Result

A specialized Result type for Aseprite parsing functions.