A Cross Platform C# Library for Reading Aseprite Files

AsepriteDotNet is a cross-platform C# library for reading Aseprite (.aseprite/.ase) files. Once file has been read, the library presents an easy to navigate AsepriteFile class containing the data read from the file.

Features

• Simple one line import method (see Usage section below)
• Supports Aseprite files using RGBA, Grayscale and Indexed color modes.
• Supports all Aseprite layer blend modes.
• Support Aseprite Tileset, Tilemap Layer, and Tilemap Cel.
• Provides processors to convert the Aseprite data loaded into common formats, including:
  • Sprite
  • SpriteSheet
  • TextureAtlas
  • Tileset
  • Tilemap
  • AnimatedTilemap

Installation

Install via NuGet

dotnet add package AsepriteDotNet --version 1.8.1

Usage

Load Aseprite file

The following example demonstrates how to load an Aseprite file from disk.

//  Import namespaces
using AsepriteDotNet.Aseprite;
using AsepriteDotNet.IO;

//  Load the Aseprite file from disk.
AsepriteFile aseFile = AsepriteFileLoader.FromFile("file.aseprite");

Get Frame Color Data

In Aseprite, each frame is a collection of cels, with each cel on a different layer and each layer having its own blending mode. To get the full image of a single frame, the frame needs to be flattened. Flatting a frame blends all cel elements, starting with the bottom most layer and blending the layer above it until all layers have blended producing a single iamge.

Doing this in AsepriteDotNet will produce a Rgba32[] containing the pixel data from flattening the frame. You can specify if only cel elements that are on a visible layer should be included, if cels on the background layer should be included, and if tilemap cels should be included.

//  Import namespaces
using AsepriteDotNet.Aseprite;
using AsepriteDotNet.Common;
using AsepriteDotNet.IO;

//  Load the Aseprite file from disk.
AsepriteFile file = AsepriteFileLoader.FromFile("file.aseprite");

//  Flatten the frame to get the pixel data
Rgba32[] framePixels = file.Frames[0].FlattenFrame(onlyVisibleLayers: true, includeBackgroundLayer: false, includeTilemapCels: false);

Processor

AsepriteDotNet provides several out-of-the-box processors that can be used to transform the data in the AsepriteFile that is loaded into common formats. These are out-of-the-box general solutions and may not fit all use cases, but should give an idea if you want to create your own.

Some processors take a ProcessorOptions argument. The following table defines the values that can be set for these options

Property	Type	Description
OnlyVisibleLayers	bool	Indicates whether only visible layers should be processed.
IncludeBackgroundLayer	bool	Indicates whether the layer assigned as the background layer should be processed.
IncludeTilemapLayers	bool	Indicates whether tilemap layers should be processed.
MergeDuplicateFrames	bool	Indicates whether duplicates frames should be merged.
BorderPadding	int	The amount of transparent pixels to add to the edge of the generated texture.
Spacing	int	The amount of transparent pixels to add between each texture region in the generated texture.
InnerPadding	int	The amount of transparent pixels to add around the edge of each texture region in the generated texture.

The examples below demonstrate how to transform the AsepriteFile using one of the processors:

//  Import namespaces
using AsepriteDotNet.Aseprite;
using AsepriteDotNet.Common;
using AsepriteDotNet.IO;
using AsepriteDotNet.Processors;

//  Load the Aseprite file from disk.
AsepriteFile aseFile = AsepriteFileLoader.FromFile("file.aseprite");

//  Create new processor options or use the provided defaults
ProcessorOptions options = ProcessorOptions.Default;

//  Use the Sprite processor to create a sprite from a single frame
Sprite sprite = SpriteProcessor.Process(aseFile, frameIndex: 0, options);

//  Use the TextureAtlas processor to generate a texture atlas from the Aseprite file.  A TextureAtlas generates a packed texture with all frames and TextureRegion data describing the bounds of each frame in the source texture
TextureAtlas atlas = TextureAtlasProcessor.Process(aseFile, options);

//  Use the SpriteSheet processor to generate a sprite sheet from the Aseprite file.  A SpriteSheet contains a TextureAtlas as well as AnimationTags which define the animations created from tags in Aseprite.
SpriteSheet spriteSheet = SpriteSheetProcessor.Process(aseFile, options);

//  Use the TileSetProcessor to generate a texture from a tileset in the Aseprite file
Tileset tileset = TilesetProcessor.Process(aseFile, tilesetIndex: 0, options);

//  Use the TilemapProcessor to generate a tilemap from a specified frame in the Aseprite file
Tilemap tilemap = TilemapProcessor.Process(aseFile frameIndex: 0, options);

//  Use the AnimatedTilemapProcess to generate an animated tilemap from the Aseprite file
AnimatedTilemap animatedTilemap = AnimatedTilemapProcessor.Process(aseFile, options);

License

AsepriteDotNet is licensed under the MIT License. Please refer to the LICENSE file for full license text.

Contributors

Made with contrib.rocks.