AsepriteDotNet 0.2.1

There is a newer version of this package available.
See the version list below for details.
dotnet add package AsepriteDotNet --version 0.2.1                
NuGet\Install-Package AsepriteDotNet -Version 0.2.1                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="AsepriteDotNet" Version="0.2.1" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add AsepriteDotNet --version 0.2.1                
#r "nuget: AsepriteDotNet, 0.2.1"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install AsepriteDotNet as a Cake Addin
#addin nuget:?package=AsepriteDotNet&version=0.2.1

// Install AsepriteDotNet as a Cake Tool
#tool nuget:?package=AsepriteDotNet&version=0.2.1                

AsepriteDotNet Logo

A Cross Platform C# Library for Reading Aseprite Files

build and test License: MIT Twitter

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.

Built against .NET7

Installation

Install via NuGet

dotnet add package AsepriteDotNet --version 0.2.1

Features

  • Simple one line import method (see Usage section below)
  • Aseprite editor UI only data is excluded so you only have to navigate through the sprite/image data
  • Internal Aseprite flags are converted to easily consumed bool properties.
  • Supports Aseprite files using RGBA, Grayscale and Indexed color modes.
  • Supports Aseprite 1.3-beta Tileset, Tilemap Layer and Tilemap Cel.
    • Tile data found in cels is converted to a Tile object
      • Tile X-Flip, Y-Flip, and Rotation values are not fully implemented in Aseprite 1.3-beta (https://github.com/aseprite/aseprite/issues/3603). The values are still read but until they are fully implemented in Aseprite, they will always be 0.
  • Aseprite File can be converted to a packed Asepritesheet which contains a Spritesheet and a collection of Tilesheet for each tileset
  • Individual Aseprite components such as Frame, Cel, and Tileset components, as well as generated Spritesheet, Tilesheet and Asepritesheet can be saved to disk as a .png file.

Usage

Load Aseprite file

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

//  Import namespace
using AsepriteDotNet;

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

Get Frame Color Data

Each Frame in Aseprite is a collection of Cel elements, with each Cel on a different Layer. To get the full image of a single Frame, the Frame needs to be flattened. Flattening a Frame blends all Cel elements, starting with the top most Layer and blending down until a single image is produced.

Doing this in AsepriteDotNet will produce a Color[] containing the pixel data from flattening the Frame. You can specify if only Cel elements that are on a Layer that is visible should be included.

using AsepriteDotNet;
using AsepriteDotNet.Common;

AsepriteFile file = AsepriteFile.Load("file.aseprite");

Color[] framePixels = file.Frame[0].FlattenFrame(onlyVisibleLayers: true);

Save Components To PNG

Individual components can be saved as a PNG file, including Frame, ImageCel and Tileset components

using AsepriteDotNet;

AsepriteFile file = AsepriteFile.Load("file.aseprite");

//  Save a frame as png
file.Frames[0].ToPng("frame.png");

//  Save an individual ImageCel as png
if(file.frames[0].Cels[0] is ImageCel imageCel)
{
    imageCel.ToPng("cel.png");
}

//  Save a tileset as png
file.Tilesets[0].ToPng("tileset.png");

Create Spritesheet

A Spritesheet can be created from the AsepriteFile instance that contains:

  • Color[] image data generated from all Frame data
  • SpritesheetFrame elements for each frame in the image data which includes the source rectangle and duration
    • Each SpritesheetFrame also includes Slice data for that Frame if there was a Slice on that Frame.
  • SpritesheetAnimation elements for all Tag data that includes the information about the animation such as frames and loop direction.

Spritesheet can also be saved as a .png file

using AsepriteDotNet;
using AsepriteDotNet.Image;

AsepriteFile file = AsepriteFile.Load("file.aseprite");

//  Options to adhere to when generating a spritesheet
SpritesheetOptions options = new
{
    //  Should only visible layers be included?
    OnlyVisibleLayers = true,

    //  Should duplicate frames be merged into one frame?
    MergeDuplicate = true,  

    //  Can be Horizontal, Vertical, or Square.        
    PackingMethod = SquarePacked,   

    //  Padding added between each frame and edge of spritesheet.
    BorderPadding = 0,  

    //  Amount of transparent pixels to added between each frame.
    Spacing = 0,

    //  Amount of transparent pixels to add to the inside of each frame's edge.
    InnerPadding = 0    
}

//  Create the spritesheet using the options from the file.
Spritesheet sheet = file.ToSpritesheet(options);

//  Save the spritesheet as a .png
sheet.ToPng("sheet.png");

Create Tilesheet

Each Tileset in the AsepriteFile can be converted into a Tilesheet that contains:

  • The Name of the `Tileset
  • Color[] image data of the Tileset
  • A collection of TilesheetTile elements that indicate the source rectangle in the image data for each tile.

Tilesheet can also be saved as a .png file

using AsepriteDotNet;
using AsepriteDotNet.Image;

AsepriteFile file = AsepriteFile.Load("file.aseprite");

//  Options to adhere to when generating a tilesheet
SpritesheetOptions options = new
{
    //  Should duplicate tiles be merged into one tile?
    MergeDuplicate = true,  

    //  Can be Horizontal, Vertical, or Square.        
    PackingMethod = SquarePacked,   

    //  Padding added between each tile and edge of tilesheet.
    BorderPadding = 0,  

    //  Amount of transparent pixels to added between each tile.
    Spacing = 0,

    //  Amount of transparent pixels to add to the inside of each tile's edge.
    InnerPadding = 0    
}

//  Create the tilesheet form a tile using the options.
Tilesheet sheet = file.Tileset[0].ToTilesheet(options);

//  Save the tilesheet as a .png
sheet.ToPng("tilesheet.png");

Create Asepritesheet

An Asepritesheet combines both the Spritesheet and Tilesheet data into a single class instance.

using AsepriteDotNet;
using AsepriteDotNet.Image;

AsepriteFile file = AsepriteFile.Load("file.aseprite");

//  Create options for spritesheet generation.  Default constructor will create
//  default options using only visible layer, merge duplicates, square packed,
//  and 0 for padding and spacing
SpritesheetOptions spriteSheetOptions = new();

//  Create options for tilesheet generation.  Default constructor will create
//  default options using merge duplicates, square packed, and 0 for padding and
//  spacing
TilesheetOptions tilesheetOptions = new();

//  Create the Asepritesheet from the file using the options
Asepritesheet sheet = file.ToAsepritesheet(spritesheetOptions, tilesheetOptions);

License

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

Product Compatible and additional computed target framework versions.
.NET net7.0 is compatible.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • net7.0

    • No dependencies.

NuGet packages (6)

Showing the top 5 NuGet packages that depend on AsepriteDotNet:

Package Downloads
MonoGame.Aseprite

MonoGame.Aseprite is a cross-platform C# library that adds support to MonoGame projects for Aseprite (.asepirte/.ase) files.

FlatRedBallDesktopGLNet6

FlatRedBall Game Engine

FlatRedBallAndroid

FlatRedBall Game Engine

FlatRedBalliOS

FlatRedBall Game Engine

FlatRedBall.FNA

FlatRedBall Game Engine

GitHub repositories (2)

Showing the top 2 popular GitHub repositories that depend on AsepriteDotNet:

Repository Stars
vchelaru/FlatRedBall
Cross-platform 2D game engine focused on ultimate productivity built in .NET
AristurtleDev/monogame-aseprite
A Cross Platform C# Library That Adds Support For Aseprite Files in MonoGame Projects.