Aseprite Love2D Library

A comprehensive Love2D port of AsepriteDotNet that allows you to load and use Aseprite files directly in your Love2D games.

Features

• Complete Aseprite file parsing - Supports all Aseprite file format features including layers, frames, tags, slices, tilesets, and palettes
• Love2D integration - Converts Aseprite data to Love2D Images, Quads, and sprite objects
• Animation support - Automatic animation creation from Aseprite tags with proper timing
• Sprite sheets - Generate optimized sprite sheets from Aseprite files
• Advanced layer compositing - Full support for multi-layer rendering, including linked cels, proper layer blending and opacity
• Pixel-perfect rendering - Automatic nearest-neighbor filtering for crisp pixel art display
• Memory efficient - Optimized for Love2D's graphics system

Installation

1. Copy the aseprite-love2d folder to your Love2D project
2. Require the library in your code:

local AsepriteLove2D = require('aseprite-love2d')

• Requirements: Love2D 11.0 or newer (uses love.data.decompress for zlib)

Quick Start

Basic Sprite Loading

local AsepriteLove2D = require('aseprite-love2d')

local sprite

function love.load()
    -- Load an Aseprite file as a ready-to-use sprite
    sprite = AsepriteLove2D.loadSprite("character.aseprite")
    
    if sprite then
        -- Start playing the first available animation
        sprite:setAnimation("walk")
        sprite:play()
    end
end

function love.update(dt)
    if sprite then
        sprite:update(dt)
    end
end

function love.draw()
    if sprite then
        sprite:draw(100, 100)
    end
end

Advanced Usage

local AsepriteLove2D = require('aseprite-love2d')

local asepriteFile
local spriteSheet
local quads
local animations

function love.load()
    -- Load raw Aseprite data for advanced usage
    asepriteFile = AsepriteLove2D.loadFile("character.aseprite")
    
    if asepriteFile then
        -- Create a sprite sheet and quads
        spriteSheet, quads = AsepriteLove2D.createSpriteSheet(asepriteFile)
        
        -- Get animation data
        animations = AsepriteLove2D.createAnimations(asepriteFile)
        
        -- Print information about the file
        print("Canvas size: " .. asepriteFile.canvasWidth .. "x" .. asepriteFile.canvasHeight)
        print("Frame count: " .. #asepriteFile.frames)
        print("Layer count: " .. #asepriteFile.layers)
        
        for name, animation in pairs(animations) do
            print("Animation '" .. name .. "' has " .. #animation.frames .. " frames")
        end
    end
end

API Reference

Main Functions

AsepriteLove2D.loadSprite(filePath)

Loads an Aseprite file and returns a ready-to-use sprite object.

Parameters:

• filePath (string): Path to the .aseprite file

Returns:

• sprite (table): Sprite object with animation capabilities
• error (string): Error message if loading failed

AsepriteLove2D.loadSpriteFromData(data)

Loads an Aseprite file from binary data.

Parameters:

• data (string): Binary data of the .aseprite file

Returns:

• sprite (table): Sprite object with animation capabilities
• error (string): Error message if loading failed

AsepriteLove2D.loadFile(filePath)

Loads an Aseprite file and returns raw parsed data.

Parameters:

• filePath (string): Path to the .aseprite file

Returns:

• asepriteFile (table): Raw Aseprite file data
• error (string): Error message if loading failed

AsepriteLove2D.loadFileData(data)

Parses an Aseprite file from binary data and returns raw parsed data.

Parameters:

• data (string): Binary data of the .aseprite file

Returns:

• asepriteFile (table): Raw Aseprite file data

AsepriteLove2D.createSpriteSheet(asepriteFile)

Creates a sprite sheet and quads from parsed Aseprite data.

Parameters:

• asepriteFile (table): Parsed Aseprite file data

Returns:

• spriteSheet (Image): Love2D Image containing all frames
• quads (table): Array of Love2D Quads for each frame

AsepriteLove2D.createAnimations(asepriteFile)

Creates animation data from Aseprite tags.

Parameters:

• asepriteFile (table): Parsed Aseprite file data

Returns:

• animations (table): Dictionary of animation data keyed by tag name

AsepriteLove2D.readTags(filePath)

Reads tag information from an Aseprite file without fully parsing all image data.

Parameters:

• filePath (string): Path to the .aseprite file

Returns:

• tags (table): Array of tag objects with name, range, and loop direction

Sprite Object Methods

sprite:setAnimation(name)

Sets the current animation.

Parameters:

• name (string): Name of the animation (from Aseprite tags)

Returns:

• success (boolean): True if animation was found and set

sprite:play()

Starts playing the current animation.

sprite:pause()

Pauses the current animation.

sprite:stop()

Stops the animation and resets to the first frame.

sprite:update(dt)

Updates the animation state. Call this in love.update().

Parameters:

• dt (number): Delta time in seconds

sprite:draw(x, y, r, sx, sy, ox, oy, kx, ky)

Draws the current frame of the sprite.

Parameters:

• x, y (number): Position
• r (number): Rotation (optional)
• sx, sy (number): Scale (optional)
• ox, oy (number): Origin offset (optional)
• kx, ky (number): Shearing (optional)

Sprite Object Properties

• sprite.spriteSheet (Image): The sprite sheet image
• sprite.quads (table): Array of quads for each frame
• sprite.animations (table): Available animations
• sprite.canvasWidth (number): Width of each frame
• sprite.canvasHeight (number): Height of each frame
• sprite.frameCount (number): Total number of frames
• sprite.currentAnimation (string): Name of current animation
• sprite.currentFrame (number): Current frame index
• sprite.isPlaying (boolean): Whether animation is playing

Aseprite File Structure

The parsed Aseprite file contains the following structure:

asepriteFile = {
    canvasWidth = 64,           -- Canvas width in pixels
    canvasHeight = 64,          -- Canvas height in pixels
    colorDepth = 32,            -- Color depth (8, 16, or 32 bits)
    frames = {                  -- Array of frames
        {
            duration = 100,     -- Frame duration in milliseconds
            cels = {            -- Array of cels in this frame
                {
                    layerIndex = 0,
                    x = 0, y = 0,
                    width = 64, height = 64,
                    type = "image",
                    pixelData = {...}
                }
            }
        }
    },
    layers = {                  -- Array of layers
        {
            name = "Layer 1",
            isVisible = true,
            opacity = 255,
            blendMode = 0,
            type = "image"
        }
    },
    tags = {                    -- Array of animation tags
        {
            name = "walk",
            from = 0,           -- Start frame
            to = 3,             -- End frame
            loopDirection = 0   -- 0=forward, 1=reverse, 2=ping-pong
        }
    },
    slices = {},                -- Array of slices (9-patch data, etc.)
    tilesets = {},              -- Array of tilesets
    palette = {}                -- Color palette
}

Animation Data Structure

animations = {
    walk = {
        name = "walk",
        frames = {
            {index = 1, duration = 0.1},
            {index = 2, duration = 0.1},
            {index = 3, duration = 0.1},
            {index = 4, duration = 0.1}
        },
        totalDuration = 0.4,
        loopDirection = 0
    }
}

Examples

See the examples/ directory for complete working examples:

• basic_sprite/ - Simple sprite loading and animation
• sprite_sheet/ - Advanced sprite sheet usage with multiple instances

Supported Features

✅ Fully Supported

• All Aseprite file format versions
• RGBA, Grayscale, and Indexed color modes
• Layer compositing with blend modes and opacity
• Animation tags with proper timing
• Frame duration and loop directions
• Sprite sheet generation
• Zlib compression via Love2D's love.data.decompress

⚠️ Partially Supported

• Some blend modes fall back to alpha blending
• Indexed color mode converts to grayscale (palette support planned)

❌ Not Yet Supported

• Tilemap layers (planned for future release)
• Advanced slice features
• User data chunks

Performance Tips

1. Preload sprites - Load sprites during love.load() rather than during gameplay
2. Reuse sprite objects - Create one sprite object and reuse it for multiple instances
3. Use sprite sheets - For multiple instances of the same sprite, use createSpriteSheet() and manage animation manually
4. Batch drawing - When drawing many sprites, consider using Love2D's SpriteBatch

Troubleshooting

Common Issues

"Failed to load sprite"

• Ensure the .aseprite file path is correct
• Check that the file is a valid Aseprite file
• Verify the file is not corrupted

"Animation not found"

• Check that the animation name matches the tag name in Aseprite
• Use print() to list available animations

Decompression errors

• This library relies on Love2D's love.data.decompress for zlib. Ensure you're on Love2D 11.0+ and that your build enables this module.

Poor performance

• Avoid loading large sprites during gameplay
• Consider using smaller sprite sheets
• Use Love2D's profiler to identify bottlenecks

Blurry or soft-looking sprites

• The library automatically applies nearest-neighbor filtering for pixel-perfect rendering
• If sprites still appear blurry, check your Love2D scaling settings
• Ensure you're not applying additional transformations that use linear interpolation

Missing layers in multi-layer sprites

• The library fully supports linked cels (cel type 1) commonly used in Aseprite
• Ensure all layers are visible in your Aseprite file
• Check layer opacity settings - transparent layers won't be rendered

Debug Information

Enable debug output to see detailed information about loaded files:

local asepriteFile = AsepriteLove2D.loadFile("sprite.aseprite")
if asepriteFile then
    print("Loaded sprite: " .. asepriteFile.canvasWidth .. "x" .. asepriteFile.canvasHeight)
    print("Frames: " .. #asepriteFile.frames)
    print("Layers: " .. #asepriteFile.layers)
    print("Tags: " .. #asepriteFile.tags)
end

License

This library is licensed under the MIT License, same as the original AsepriteDotNet project.

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

Credits

Based on the excellent AsepriteDotNet library by AristurtleDev.