An animation library for LÖVE.
Lua
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
Examples Changed to MIT license; added license and URL to animator.lua; fixed … Dec 17, 2016
Images
.gitignore
README.md Fixed broken README.md formatting Nov 16, 2017
animator.lua

README.md

Walt

An animation library for LÖVE.

Table of Contents

Usage

local animator = require 'path.to.walt'

function love.load()
    local image = love.graphics.newImage( 'Path/to/image.png' )
    anim = animator.newAnimation( { image }, 1 )
end

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

function love.draw()
    anim:draw()
end

And that's it!

Name

  • Walt is named for famous animator Walt Disney.

Functions

animator.merge

  • Combine several tables into one compact table.
  • Synopsis:
    • frames = animator.merge( ... )
  • Arguments:
    • ...: Tables. A list of images and quads in the order of the animation.
  • Returns:
    • frames: Table. A flattened list of the quads and images.
  • Notes:

animator.newAnimation

  • Creates a new animation object.
  • Synopsis:
    • anim = animator.newAnimation( frames, duration, [quadImage] )
    • anim = animator.newAnimation( frames, durations, [quadImage] )
  • Arguments:
    • frames: Table. A flat table of images and quads in the order that they will be played.
    • duration: Number. The amount of time each animation will be played.
    • durations: Table. There are several "flavors" to this table. Each must have the same number of entries as frames. You can combine these in any way. See below table for more.
    • quadImage: Image. The image that the quads for the animation will be using. Not needed if you aren't using any quads.
Flavor Description Example
Flat A numbered list, representing the corresponding frame. { .1, .2, .1, .5 }
List A table key, listing the frame numbers, in the style of lower - larger. Can have 0-unlimited spaces between the -. { ['1 - 5'] = 1 }
Key Frame numbers are seperated by ,. Can have 0-unlimited spaces after the ,. { ['1, 3, 5'] = 1 }
  • Returns:
    • anim: Table. Animation object that can be used. For more, see the anim: sub-functions.
  • Notes:
    • The quads should all be from the same image.
    • After all of the Keys and Lists are inserted, the unassigned keys are done in the order of the flat entries.
      • { ['1 - 3'] = .5, ['6 - 10'] = 1, .2, .3, .4 } = { .5, .5, .5, .2, .3, 1, 1, 1, 1, 1, .4 }

anim:draw

  • Draw the animation.
  • Synopsis:
    • anim:draw()
  • Arguments:
  • Returns:
    • Nothing.
  • Notes:
    • You have to call [anim:update](#animupdate) as well.

anim:getActive

  • Returns if the animation is currently playing.
  • Synopsis:
    • active = anim:getActive()
  • Arguments:
  • Returns:
    • active: Boolean. Whether the animation is playing or not.

anim:getCurrentFrame

  • Gets the current frame number.
  • Synopsis:
    • frame = anim:getCurrentFrame()
  • Arguments:
  • Returns:
    • frame: Number. The number frame that the animation is on.

anim:getDimensions

  • Gets the width and height of the current frame of the animation.
  • Synopsis:
    • width, height = anim:getDimensions()
  • Arguments:
  • Returns:
    • width: Number. The width of the current frame.
    • height: Number. THe height of the current frame.

anim:getHeight

  • Gets the height of the current frame of the animation.
  • Synopsis:
    • height = anim:getHeight()
  • Arguments:
  • Returns:
    • height: Number. The height of the current frame.

anim:getLooping

  • Gets whether the animation is a looping animation or not.
  • Synopsis:
    • isLooping = anim:getLooping()
  • Arguments:
  • Returns:
    • isLooping: Boolean. Whether the animation is looping or not.

anim:getOnAnimationChange

  • Gets the function called on frame-change.
  • Synopsis:
    • func = anim:getOnAnimationChange()
  • Arguments:
  • Returns:
    • func: Function. The function called on frame-change.

anim:getOnLoop

  • Gets the function called on-loop.
  • Synopsis:
    • func = anim:getOnLoop()
  • Arguments:
  • Returns:
    • func: Function. The function called on-loop.

anim:getPauseAtEnd

  • Gets whether the animation should pause on the last frame.
  • Synopsis:
    • shouldPause = anim:getPauseAtEnd()
  • Arguments:
  • Returns:
    • shouldPause: Boolean. Whether the animation will pause at the end or not.

anim:getPaused

  • Gets whether the animation is paused or not.
  • Synopsis:
    • isPaused = anim:getPaused()
  • Arguments:
  • Returns:
    • isPaused: Boolean. Whether the animation is paused or not.

anim:getWidth

  • Gets the width of the current frame of the animation.
  • Synopsis:
    • width = anim:getWidth()
  • Arguments:
  • Returns:
    • width: Number. The width of the frame.

anim:pause

  • Pauses the animation.
  • Synopsis:
    • anim:pause()
  • Arguments:
  • Returns:
    • Nothing.

anim:pauseAtEnd

  • Sets the function to pause after the last frame has played.
  • Synopsis:
    • anim:pauseAtEnd()
  • Arguments:
  • Returns:
    • Nothing.

anim:restart

  • Resets the animation to the first frame.
  • Synopsis:
    • anim:restart()
  • Arguments:
  • Returns:
    • Nothing.

anim:resume

  • Resumes the animation from a pause.
  • Synopsis:
    • anim:resume()
  • Arguments:
  • Returns:
    • Nothing.

anim:setActive

  • Stops or resumes the animation.
  • Synopsis:
    • anim:setActive( active )
  • Arguments:
    • anim: Table. An animation object returned from animator.newAnimation.
    • active: Boolean. Whether the animation should be playing (true) or not (false).
  • Returns:
    • Nothing.

anim:setCurrentFrame

  • Sets the current frame of the animation.
  • Synopsis:
    • anim:setCurrentFrame( frame )
  • Arguments:
    • anim: Table. An animation object returned from animator.newAnimation.
    • frame: Number. The frame to be set.
  • Returns:
    • Nothing.

anim:setLooping

  • Sets whether the animation should loop at the end or not.
  • Synopsis:
    • anim:setLooping( loop )
  • Arguments:
    • anim: Table. An animation object returned from animator.newAnimation.
    • loop: Boolean. Whether the animation should loop at the end or not.
  • Returns:
    • Nothing.

anim:setOnAnimationChange

  • Sets the function executed on animation change.
  • Synopsis:
    • anim:setOnAnimationChange( func )
  • Arguments:
    • anim: Table. An animation object returned from animator.newAnimation.
    • func: Function. The function to be called on each animation increment.
  • Returns:
    • Nothing

anim:setOnLoop

  • Sets the function executed on loop.
  • Synopsis:
    • anim:setOnLoop( func )
  • Arguments:
    • anim: Table. An animation object returned from animator.newAnimation.
    • func: Function. The function to be called on each loop.
  • Returns:
    • Nothing.

anim:setPauseAtEnd

  • Sets the animation to pause after displaying the final frame.
  • Synopsis:
    • anim:setPauseAtEnd( shouldPause )
  • Arguments:
    • anim: Table. An animation object returned from animator.newAnimation.
    • shouldPause: Boolean. Whether or not the function should pause after displaying the final frame.
  • Returns:
    • Nothing.

anim:setPaused

  • Sets if the animation is paused or not.
  • Synopsis:
    • anim:setPaused( isPaused )
  • Arguments:
    • anim: Table. An animation object returned from animator.newAnimation.
    • isPaused: Boolean. Whether the animation should be paused or not.
  • Returns:
    • Nothing.

anim:togglePause

  • Toggles the pause of the animation.
  • Synopsis:
    • anim:togglePause()
  • Arguments:
  • Returns:
    • Nothing.

anim:toggleActive

  • Toggles whether the animation is active or not.
  • Synopsis:
    • anim:toggleActive()
  • Arguments:
  • Returns:
    • Nothing.

anim:toggleLooping

  • Toggles whether the animation is looping or not.
  • Synopsis:
    • anim:toggleLooping()
  • Arguments:
  • Returns:
    • Nothing.

anim:togglePauseAtEnd

  • Toggles whether the animation pauses after playing the last frame.
  • Synopsis:
    • anim:togglePauseAtEnd()
  • Arguments:
  • Returns:
    • Nothing.

anim:update

  • Update the animation.
  • Synopsis:
    • anim:update( dt )
  • Arguments:
    • anim: Table. An animation object returned from animator.newAnimation.
    • dt: Number. The time between each update-frame.
  • Returns:
    • Nothing.

animator.newGrid

  • Creates a new grid to make animation easier.
  • Synopsis:
    • grid = animator.newGrid( frameWidth, frameHeight, image, [startX, startY, stopX, stopY] )
  • Arguments:
    • frameWidth: Number. The width each quad will be.
    • frameHeight: Number. The height each frame will be.
    • image: Image. The image that will be used.
    • startX: Number. The x position to start creating the grid. Defaults as 0.
    • startY: Number. The y position to start creating the grid. Defaults as 0.
    • stopX: Number. The x position to stop creating the grid. Defauls as the image's width.
    • stopY: Number. The y position to stop creating the grid. Defaults as the image's height.
  • Returns:
    • grid: Table. A table of quads.

grid:getFrames

  • Returns the quads in the specified order you create it.

  • Synopsis:

    • frames = grid:getFrames()
  • Arguments:

    • grid: Table. A grid object retured by animator:newGrid. See the picture below to get a better idea of how they work.
  • Returns:

    • frames: Table. A table containing the quads created from the grid.
  • Each pair of numbers is a pair of x and y coordinates, referring to the grid.

    • Use plain numbers to refer to single simple x and y coordinates.
    • Use a string with numbers seperated by a hyphen (-) to represent "through".
    • In a pairs, both arguments can't be strings.
  • So you would make a grid like this (assuming the image is called 'grid.png'):

Grid

local image = love.graphics.newImage( 'grid.png' )
local grid = animator.newGrid( 32, 32, image, 32, 32, 288, 224 )
local anim = animator.newAnimation( grid.getFrames( 1,1  2,1  3,1  '4 - 7',1,  8, '1 - 6' ), 1, image )
-- You have to remember to pass the image that the quads are from. 

Alisases

  • There functions are also available, and work just like their conterpart.
Alias Corresponding Function
anim:isActive anim:getActive
anim:isLooping anim:getLooping
anim:isPaused anim:getPaused
anim:getFrame anim:getGetCurrentFrame
anim:gotoFrame anim:setCurrentFrame
anim:setAnimationChange anim:setOnAnimationChange
anim:setFrame anim:setCurrentFrame
grid:__call grid:getFrames

Examples

See Examples.