Difference between revisions of "AnAL"

(Changed version to 0.6.x)
(Added tut and docs)
Line 4: Line 4:
 
*love.graphics.newAnimation(...) becomes newAnimation(...)
 
*love.graphics.newAnimation(...) becomes newAnimation(...)
 
*love.graphics.draw(anim, ...) becomes anim:draw(...)
 
*love.graphics.draw(anim, ...) becomes anim:draw(...)
 +
*anim:setMode() uses string constants
  
 
===Compat mode===
 
===Compat mode===
Line 13: Line 14:
  
 
Disadvantage is the changed behavior of love.graphics.draw, it calls a custom draw field on all tables passed.
 
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).
 +
 +
[[Image:Explosion.png|thumb|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.
 +
<source lang="lua">
 +
function load()
 +
 +
  -- Load the animation source.
 +
  local img  = love.graphics.newImage("explosion.png")
 +
 
 +
  -- Create animation.
 +
  anim = newAnimation(img, 96, 96, 0.1, 0)
 +
 
 +
end
 +
</source>
 +
 +
 +
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.
 +
<source lang="lua">
 +
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
 +
</source>
 +
 +
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.
 +
<source lang="lua">
 +
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
 +
</source>
  
 
==Docs==
 
==Docs==
Further documentation coming soon.
+
 
 +
===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==
 
==See Also==

Revision as of 15:00, 25 February 2010

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.