KinsonDigital.VelaptorAseprite 1.0.0-preview.1

VelaptorAseprite

Seamless Aseprite integration for the Velaptor 2D game framework Features • Installation • Quick Start • Examples

📖 Overview

VelaptorAseprite is a powerful NuGet package that brings native Aseprite sheet support to Velaptor 2D games. Load your Aseprite-exported sprite sheets and JSON data seamlessly, with full support for frame-by-frame animations, looping behaviors, and playback control. Perfect for indie game developers who want to use Aseprite's excellent pixel art tools with the Velaptor game framework.

✨ Features

• Direct Aseprite Integration - Load sprite sheets exported from Aseprite with their JSON data
• Full Animation Control - Play, pause, stop, and reset animations with ease
• Flexible Looping - Support for infinite loops, single play through, or custom loop counts
• Directional Playback - Play animations forward or backward
• Speed Control - Adjust animation speed dynamically
• Simple API - Extension methods on IContentManager for familiar content loading
• Frame-Accurate - Maintains Aseprite's original frame timing and metadata

📦 Installation

Install via NuGet Package Manager:

dotnet add package KinsonDigital.VelaptorAseprite

Or via Package Manager Console:

Install-Package KinsonDigital.VelaptorAseprite

🚀 Quick Start

1. Export from Aseprite

Export your sprite sheet from Aseprite:

• File → Export Sprite Sheet
• Output: JSON Data format
• Ensure both .png and .json files are saved to your Content folder

2. Load and Animate

using VelaptorAseprite;
using Velaptor.Content;
public class MyScene : SceneBase
{
private IContentManager contentManager;
private IAsepriteAtlas? atlasData;
public override void LoadContent()
{
contentManager = ContentManager.Create();
// Load the Aseprite atlas data
atlasData = contentManager.LoadAsepriteAtlas("my-character");
// Start the animation
atlasData.Play();
}
public override void Update(FrameTime frameTime)
{
// Update the animation each frame
atlasData?.Update(frameTime);
}
public override void Render()
{
if (atlasData is null)
{
return;
}
var frame = this.atlasData.GetCurrentFrame();
var srcRect = frame.Bounds;
var destRect = new Rectangle(0, 0, (int)(this.atlasData.Texture.Width ?? 0), (int)(this.atlasData.Texture.Height ?? 0));
destRect.X = WindowCenter.X;
destRect.Y = WindowCenter.Y;
this.textureRenderer.Render(
this.atlasData.Texture,
srcRect,
destRect,
RenderScale,
0f,
Color.White,
RenderEffects.None);
}
public override void UnloadContent()
{
if (atlasData is not null)
{
contentManager.UnloadAsepriteAtlas(atlasData);
}
}
}

💡 Examples

Example 1: Simple Character Animation

// Load and play a character walk cycle
var walkCycle = contentManager.LoadAsepriteAtlas("character-walk");
walkCycle.LoopingBehavior = LoopingBehavior.Infinite;
walkCycle.Play();
// In your update loop
walkCycle.Update(frameTime);

Example 2: Play Animation X Times

// Play a spell effect 3 times then stop
var spellEffect = contentManager.LoadAsepriteAtlas("spell-cast");
spellEffect.LoopingBehavior = LoopingBehavior.Count;
spellEffect.MaxLoops = 3;
spellEffect.Play();

Example 3: Reverse Animation

// Play an animation backward
var rewindAnim = contentManager.LoadAsepriteAtlas("door-open");
rewindAnim.Direction = AnimationDirection.Backward;
rewindAnim.Play();

Example 4: Speed Control

// Make animation play twice as fast
var fastAnim = contentManager.LoadAsepriteAtlas("fast-action");
fastAnim.SetAnimationSpeed(50); // 50ms per frame instead of exported Aseprite default
fastAnim.Play();

Example 5: Animation State Machine

public class Player
{
private IAsepriteAtlas playerAtlasData;
private readonly IAppInput<KeyboardState> keyboard;
private KeyboardState prevKeyState;
public Player() => this.keyboard = HardwareFactory.GetKeyboard();
public override void LoadContent()
{
// Load the main player animation atlas
this.playerAtlasData = contentManager.LoadAsepriteAtlas("main-player", "player-idle");
// Set the initial animation
this.playerAtlasData.Play();
this.playerAtlasData.LoopingBehavior = LoopingBehavior.Infinite;
}
public void Update(FrameTime frameTime)
{
var currentKeyState = this.keyboard.GetState();
if (currentKeyState.IsKeyDown(KeyCode.Left) || currentKeyState.IsKeyDown(KeyCode.Right))
{
this.playerAtlasData.LoopingBehavior = LoopingBehavior.Infinite;
this.playerAtlasData.AnimationName = "player-walk";
}
if (currentKeyState.IsKeyUp(KeyCode.Space) && this.prevKeyState.IsKeyDown(KeyCode.Space))
{
this.playerAtlasData.LoopingBehavior = LoopingBehavior.None;
this.playerAtlasData.AnimationName = "player-jump";
}
this.prevKeyState = currentKeyState;
this.playerAtlasData.Update(frameTime);
}
public override void Render()
{
// ... render code here
}
}

🤝 Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.

🙏 Acknowledgments

• Velaptor – The 2D game framework this library extends
• Aseprite – The amazing pixel art and animation tool
• Built by KinsonDigital (Creator of Velaptor)

Made with ❤️ for indie game developers