//* ANIMATION LIB 4 *\\

 
This is the FOURTH release of Animation Lib. THIS VERSION SUPPORTS ALL SPRITE SHEETS
AND ITS SOOOO EASY!


IMPORTANT: when loading a sprite sheet, you have to call it like this:

blah = SS.new(whatever) 

NOT

blah = ANIM.new(whatever)



// FUNCTION LIST //

function ANIM.new(header, extension, frames, where)	-- loads a new animation

function ANIM:blit(x, y, delay, numLoops)	-- blits an animation

function ANIM:pause()	-- pauses the animation

function ANIM:resume()	-- resumes the animation

function ANIM:reset(num)	-- resets the animation (brings it back to the frame you want, which is what "num" means)


function ANIM:resetLoop()	-- restores the loop counter. It is recommended that you do this everytime you call the advanceBlit function.

function ANIM:getTime()	-- returns the current timer time

function ANIM:getFrame()	-- returns the current frame of the animation

function ANIM:getLoops()	-- returns how many loops the animation has made.

function ANIM:free()	-- frees the animation



// SPRITESHEET FUNCTIONS //

function SS.new(header, extension, nWidth, nHeight, where) -- loads a new animation, REALLY EASY.

function SS:blit(x, y, delay, numLoops) -- blits a current sprite sheet. EVEN EASIER.


function SS:pause() -- pauses the sprite sheet

function SS:resume() -- resumes the sprite sheet

function SS:reset() -- resets the sprite sheet

function SS:free() -- frees the sprite sheet from memory

function SS:resetLoop() -- resets loop number, you should call this everytime after you use the SS:advancedBLit() function

function SS:getTime() -- returns the current timer time

function SS:getRow() -- returns the current row of the animation (not really needed)

function SS:getColumn() -- returns the current column of the animation (not really needed)

function SS:getLoops() -- returns the number of lops the animation has made. (only if youre using the advancedBLit function)


// END FUNCTION LIST //


Here is a MUCH SMALLER tutorial on how to use Animation Lib:


// TUTORIAL //

-------------------------------------------------------------------------------------
function ANIM.new(frames, header, extension, where)
-------------------------------------------------------------------------------------

this function loads a new animation. here are what the arguments mean:

frames - the number of frames in your animation.
header - the header of your file, which will be explained later.
extension - the extension of your image.
where - this is used if your images are in a seperate directory. if your pictures are in the same folder as your script, then just leave this blank.


here is some code that will load an animation:

-------------------------------------------------------------------------------------
test = ANIM.new(14, "test", "png", "DATA/animLib/")
-------------------------------------------------------------------------------------

that code will load 14 images:

test1.png
test2.png
test3.png
... all the way to test14.png

in a folder called DATA, and inside that, another folder called animLib. (The example that came with this uses that exact command.)


-------------------------------------------------------------------------------------
function ANIM:blit(x, y, delay)
-------------------------------------------------------------------------------------

this will blit an animation. NOW, when using OOP, you treat it as an object, SO, since you called: test = ANIM.new(14, "test", "png", "DATA/animLib/"),
NOW to blit the animation, you have to call:

------------------------------
test:blit(x, y, delay)
------------------------------

cool huh?

now, lets go to the arguments:

x - x position of the animation.
y - y position of the animation.
delay - the delay you want inbetween frames, (in millisceonds)
numLoops - How many times you want the animation to loop. If nohing is given, it will continue forever.

the rest of the functions are self-explanatory. but i will explain one more:


// SPRITE SHEET TUTORIAL //

-------------------------------------------------------------------------------------
function SS.new(header, extension, nWidth, nHeight, where)
-------------------------------------------------------------------------------------

this function loads a new sprite sheet. arguments:

header - the name of the sheet (without the extension)
extension - the extension of the image
nWidth - the width of every "frame" in your sprite sheet. ALL FRAMES MUST HAVE THE SAME WIDTH FOR ANIMLIB TO WORK!
nHeight - the height of every "frame" in your sprite sheet. ALL FRAMES MUST HAVE THE SAME HEIGHT FOR ANIMLIB TO WORK!
where - use this if your image is in another folder

-------------------------------------------------------------------------------------
function SS:blit(x, y, delay, numLoops)
-------------------------------------------------------------------------------------

see? this is what i meant by how EASY it is. all you have to give is:

x - x position of the animation.
y - y position of the animation.
delay - the delay you want inbetween frames, (in millisceonds)
numLoops - How many times you want the animation to loop. If nohing is given, it will continue forever.

if you cant give that much info, then animlib is not for you.


//END TUTORIAL//


to use this lib, simply put: 

dofile("animLib.lua")

at the beginning of your code.


well, thats it. if you have any questions, look in the sample file, "index.lua". chances are, itll answer your question. if it doesnt, you can PM me at the 
QJ forums. my name there is:

Grimfate126


you can also PM me if you want to tell me suggestions.

please give credit to Grimfate126 if you use it.


have fun!!!!

P.S. the "index.lua" file, when executed, will show 3 random sprite sheet animations i made in about 5 seconds. :p




