AnAL

AnAL (Animations And Love) is a library to replace 0.5.0's animations (removed in 0.6.0), with minimum code changes for the lover.

Code Changes

• love.graphics.newAnimation(...) becomes newAnimation(...)
• love.graphics.draw(anim, ...) becomes anim:draw(...)
• anim:setMode() uses string constants

Compat mode

It even features a compat mode, which adds love.graphics.newAnimation and changes love.graphics.draw.

Animations_legacy_support = true

Disadvantage is the changed behavior of love.graphics.draw, it calls a custom draw field on all tables passed.

Tutorial

Shamelessly ripped from the old 0.5.0 tutorial (on the old wiki).

File:Explosion.png

A simple explosion.

This is our image, information:

• Dimensions: 480x288 px
• Frame size: 96x96 px
• Frames: 5x3 = 15

Now let's look at how we can load this animation.

function load()

   -- Load the animation source.
   local img  = love.graphics.newImage("explosion.png")
   
   -- Create animation.
   anim = newAnimation(img, 96, 96, 0.1, 0)
   
end

First, we need to load the source image used for the animation. Then, we create the animation with newAnimation(). The first argument should be the source image we loaded earlier. The second is the frame width, the third is the frame height, and the fourth is the delay after each frame (in seconds). You do not need to worry about the size of the image, or the number of frames; that will be taken care of for you, if you specify number of frames as 0.

When this is done, two things remain: updating the animation, and displaying it. Updating is needed, because the animation needs to know how much time has passed in order to do frame changes. The full code for a working animation is listed below.

function load()
   local img  = love.graphics.newImage("explosion.png")
   anim = newAnimation(img, 96, 96, 0.1, 0)
end

function update(dt)
   -- Updates the animation. (Enables frame changes)
   anim:update(dt)   
end

function draw()
   -- Draw the animation at (100, 100).
   anim:draw(100, 100) 
end

This should draw the animation at (100,100).

Moving on to animation modes. There are three predefined animation modes: loop, once and bounce. Loop is the default behavior. With this mode enabled, the animation will restart at the first frame when it reaches the end. With once mode enabled, it will play once, and then stop. Finally, with bounce the animation will reverse itself upon reaching the ends, causing it to "ping-pong" between the first and the last frame. You can set the mode like shown in the code block below.

function load()
   local img  = love.graphics.newImage("explosion.png")
   anim = newAnimation(img, 96, 96, 0.1, 0)
   
   -- Mode constants:
   -- loop
   -- bounce
   -- once
   
   -- Sets the mode to "bounce"
   anim:setMode("bounce")
   
end

Docs

Function list

Following is a list of functions.

• addFrame(x, y, w, h, delay)
• setMode(mode)
• play()
• stop()
• reset()
• seek(frame)
• getCurrentFrame()
• getSize()
• setDelay(frame, delay)
• setSpeed(speed)
• getSpeed()
• getWidth()
• getHeight()
• update(dt)

Description

For the functions with arguments here are a few descriptions (the others are self-explanatory).

addFrame

• x: The x position of the frame in the image
• y: The y position of the frame in the image
• w: The width of the frame
• h: The height of the frame
• delay: How much time before going to the next frame

setMode

• mode: The mode, can be either "once", "loop" (default) or "bounce", more info in the tutorial

seek

• frame: The frame to go to in the animation

setDelay

• frame: The frame to change the delay of
• delay: How much time before going to the next frame

setSpeed

• speed: The speed of the animation, 1 being real time, 2 being twice as fast

update

• dt: Update the animation to allow it to go to the next frame.

See Also

Bartbes, creator and maintainer of AnAL.