2.0 Alpha Build

Currently documentation hasn't been written for the 2.0 release. The following serves as a quickstart guide

Quick Start Guide

Download

Download the MonoGame.Aseprite.2.0-alpha.zip file below. It contains the Monogame.Aseprite.dll and MonoGame.Aseprite.ContentPipeline.dll files. Extract these somewhere on you computer where you can remember

Alternatively you can clone the repo and build it yourself. To do this, you'll need to ensure you're in the tags/2.0-alpha of the repo. The following commands should do it all for you

1. Clone the repository with: git clone https://github.com/manbeardgames/monogame-aseprite.git
2. cd to the repo directory with: cd monogame-aseprite
3. Switch to the 2.0-alpha tree with: git checkout tags/2.0-alpha You'll get a message about the HEAD being detached. This is normal
4. Initialize the submodules with: git submodule update --init

Add Pipeline Reference

1. Open the Content.mgcb file for your project with the Content Pipeline Tool.
2. In the Content Pipeline Tool, click "Content" in the project panel.
3. Scroll down to "References" in the Properties panel and click it to open the Reference Editor dialog
4. Click the "Add" button and locate the MonoGame.Aseprite.ContentPipeline.dll file to add it.
5. Click Ok.

Add Project Reference

With your project open in Visual Studio:

1. Right-click your project in the Solution Explorer panel and select Add > Project Reference. This may just be Add > Reference... if using VS 2017. This will open the Reference Manager dialog window.
2. Click the Browse button at the bottom
3. Navigate to and select the MonoGame.Aseprite.dll file to add it.
4. Once added, click OK to close the Reference Manager dialog window.

Using MonoGame.Aseprite

To use this tool, first add a new .ase/.aseprite file to your project using the Content Pipeline tool. When you select the file in the content pipeline tool, you should see in the Properties panel that it is using the Aseprite Animation Importer and Aseprite Animation Procesor for the importer and processor respectively. Click the save button and you can close the pipeline tool now.

In your project, to load the content in, you do so like any other content, with the following command

// Lets say we added the file player_animations.aseprite
AsepriteDocument doc = Content.Load<AsepriteDocument>("player_animations");

Doing this will create the AsperiteDocument object that has all the information from importing the aseprite file, including a Texture2D that you can use for rendering. The texture that is generated is a spritesheet of all the frames from the aseprite file. To get the boundries of the frames within the spritesheet, you can use the AsepriteDocument.Frames property. If you aseprite file had animation tags defined, they are in the AsepriteDocument.Tags property, which is a Dictionary where the key is the name of the animation.

MonoGame.Aseprite also come with an out-of-the-box AnimatedSprite class that you can use to create animated sprites from the AsepriteDocment. To use this, just pass the document into a new instance of the class like so

AsepriteDocument doc = Content.Load<AsepriteDocument>("player_animations");
AnimatedSprite _sprite = new AniamtedSprite(doc);

Note that for theAnimatedSprite class to function properly, you have to create animation tags in the Aseprite file as it relies on this to parse correctly. For more information, see the Aseprite documentation at https://www.aseprite.org/docs/tags/

Then when you want a certain animation to play, just use the .Play(string) method, and give it the name of an animation tag from your file.

sprite.Play("animation_tag_name");

Take a look at the AnimatedSprite class to see what properties and methods are available.
You can also take a look at the monoagem-aseprite-demo project to see a working example of some of the things you can do.

Update for MonoGame 3.8

This update adds support for MonoGame 3.8.

NuGet Package Users

Due to needing to adjust how the content pipeline reference files are added from the NuGet package, this is considered a breaking change and users will need to read the wiki page documentation to see how to add the content pipeline references.