Home

Awesome

anim8

Animation library for LÖVE.

Build Status Coverage Status

In order to build animations more easily, anim8 divides the process in two steps: first you create a grid, which is capable of creating frames (Quads) easily and quickly. Then you use the grid to create one or more animations.

LÖVE compatibility

Since anim8 uses LÖVE's graphical functions, and they change from version to version, you must choose the version of anim8 which is compatible with your LÖVE.

Example

local anim8 = require 'anim8'

local image, animation

function love.load()
  image = love.graphics.newImage('path/to/image.png')
  local g = anim8.newGrid(32, 32, image:getWidth(), image:getHeight())
  animation = anim8.newAnimation(g('1-8',1), 0.1)
end

function love.update(dt)
  animation:update(dt)
end

function love.draw()
  animation:draw(image, 100, 200)
end

You can see a more elaborated example in the demo branch.

That demo transforms this spritesheet:

1945

Into several animated objects:

1945

Explanation

Grids

Grids have only one purpose: To build groups of quads of the same size as easily as possible. In order to do this, they need to know only 2 things: the size of each quad and the size of the image they will be applied to. Each size is a width and a height, and those are the first 4 parameters of @anim8.newGrid@.

Grids are just a convenient way of getting frames from a sprite. Frames are assumed to be distributed in rows and columns. Frame 1,1 is the one in the first row, first column.

This is how you create a grid:

anim8.newGrid(frameWidth, frameHeight, imageWidth, imageHeight, left, top, border):

To see this a bit more graphically, here are what those values mean for the grid which contains the "submarine" frames in the demo:

explanation

Grids only have one important method: Grid:getFrames(...).

Grid:getFrames accepts an arbitrary number of parameters. They can be either numbers or strings.

But you will probably never use getFrames directly. You can use a grid as if it was a function, and getFrames will be called. In other words, given a grid called g, this:

g:getFrames('2-8',1, 1,2)

Is equivalent to this:

g('2-8',1, 1,2)

This is very convenient to use in animations.

Let's consider the submarine in the previous example. It has 7 frames, arranged horizontally.

If you make its grid start on its first frame (using left and top), you can get its frames like this:

                           -- frame, image,    offsets, border
    local gs = anim8.newGrid(32,98, 1024,768,  366,102,   1)

    local frames = gs('1-7',1)

However that way you will get a submarine which "emerges", then "suddenly disappears", and emerges again. To make it look more natural, you must add some animation frames "backwards", to give the illusion of "submersion". Here's the complete list:

local frames = gs('1-7',1, '6-2',1)

Animations

Animations are groups of frames that are interchanged every now and then.

local animation = anim8.newAnimation(frames, durations, onLoop)

Animations have the following methods:

animation:update(dt)

Use this inside love.update(dt) so that your animation changes frames according to the time that has passed.

animation:draw(image, x,y, angle, sx, sy, ox, oy, kx, ky)

Draws the current frame in the specified coordinates with the right angle, scale, offset & shearing. These parameters work exactly the same way as in love.graphics.draw. The only difference is that they are properly recalculated when the animation is flipped horizontally, vertically or both. See getFrameInfo below for more details.

animation:gotoFrame(frame)

Moves the animation to a given frame (frames start counting in 1).

animation:pause()

Stops the animation from updating (@animation:update(dt)@ will have no effect)

animation:resume()

Unpauses an animation

animation:clone()

Creates a new animation identical to the current one. The only difference is that its internal counter is reset to 0 (it's on the first frame).

animation:flipH()

Flips an animation horizontally (left goes to right and viceversa). This means that the frames are simply drawn differently, nothing more.

Note that this method does not create a new animation. If you want to create a new one, use the clone method.

This method returns the animation, so you can do things like local a = anim8.newAnimation(g(1,'1-10'), 0.1):flipH() or local b = a:clone():flipV().

animation:flipV()

Flips an animation vertically. The same rules that apply to flipH also apply here.

animation:pauseAtEnd()

Moves the animation to its last frame and then pauses it.

animation:pauseAtStart()

Moves the animation to its first frame and then pauses it.

animation:getDimensions()

Returns the width and height of the current frame of the animation. This method assumes the frames passed to the animation are all quads (like the ones created by a grid).

animation:getFrameInfo(x,y, r, sx, sy, ox, oy, kx, ky)

This functions returns the parameters that would be passed to love.graphics.draw when drawing this animation:

frame, x, y, r, sx, sy, ox, oy, kx, ky

The getFrame method can be used when working with spriteBatches. Here's how it can be used for adding & setting the corresponding quad in a spritebatch:

local id = spriteBatch:add(animation:getFrameInfo(x,y,r,sx,sy,ox,oy,kx,ky))

...

spriteBatch:set(id, animation:getFrameInfo(x,y,r,sx,sy,ox,oy,kx,ky))

You can see an example of this in the spritebatch-demo branch.

Installation

Just copy the anim8.lua file wherever you want it. Then require it wherever you need it:

local anim8 = require 'anim8'

Please make sure that you read the license, too (for your convenience it's included at the beginning of the anim8.lua file).

Specs

This project uses busted for its specs. If you want to run the specs, you will have to install it first. Then just execute the following from the root folder:

busted