Home

Welcome to animX wiki! To help you not get lost here's the table of contents:-

Table of Contents

• Getting Started
• How animX works?
• Basic Terminology
  • Animation Object
  • Animation Modes
  • Animation handlers
  • Actor
  • Actor handlers
• Documentation
  • animX.newAnimation
  • animX.newActor
  • Actor API
  • Animation API

Getting Started

First require the package:-

animx=require 'animx'

Then update animx in love.update:-

function love.update(dt)
    animx.update(dt)
    --rest of your code here
end

And now just for illustration here's an example code:- (here's the image)

animx=require 'animx'

mushroomAnim=animx.newAnimation{
	img='walk.png',
	noOfFrames=4
}:loop()

function love.draw()
	mushroomAnim:draw(368,268)
end

Notice we don't update animx because by default animx overrides love.update with animx.update! Only when you have something else in love.update do you really have to update animx!

How animX works?

The basic concept of animX is that there are animation objects and then are actors. The animation objects are similar to the animation objects in other animation libraries. The actors are similar to the Sprite class of SodaPop which are nothing but animation holder. However note that other animation libraries have no notion of an "animation holder" so SodaPop and animX are unique in that context!

What an actor does is make it easier for the user to switch between different animations! Unlike Sodapop an Actor doesn't take much memory since the position, rotation, origin, etc are all set immediately and that also means that animX cannot flip animations! If you like to flip animation you can simply origin to center and negative scale along the axis along which you wanna flip!

The power of animX comes from the fact that animation objects are seperate from Actors - so each animation object can be associated to as many actors as you like. And also each actor can have infinite number of animations - as many your system supports! Also - there can be more than one atlas associated with the animation object. For instance - you could either have two seperate atlases 'walk.png' and 'run.png' for the animations 'Run' and 'Walk' or you could have a single-spritesheet 'character.png' and so basically the two animations would share the atlas. Note that while multiple atlas could be mapped to the animation object only one atlas could be mapped to one animation - that mean's you can't have seperate images 'run1.png', 'run2.png', etc and map them to the animation 'Run' - that just won't work plus that'd be inefficient as well.

Basic Terminology

Animation Instance

An Animation instance is really just a set of quads with an interface that makes it easy for you to work with those quads in a logical way!

Animation Modes

An animation instance must know not just how long should the animation run but also how many times or cycles should the animation run! This logic is defined by animation-modes.

• There's once for executing once (which is on by default)- There's loop for executing an animation an infinite or limited number of times in a particular sense!
• Then there's reverse which is same as loop but always in the reverse direction.
• There's rewind which rewinds the animation after completion a given number of times!
• And finally there's bounce which bounces the animation each time a cycle is complete! rewind and bounce may look familiar but the way they function are completely different!

Animation Handlers

Animations generate events and Animation Handlers respond to these events! Casually speaking they are just callback functions!

• There's onCycleOver which is called when an animation cycle is complete

• There's onAnimOver which is called when an entire animation is complete

• There's onAnimStart which is called when an animation is just started!

• There's onAnimRestart which is called when an animation is restarted using Animation:restart interface!

• There's onFrameChange which is called whenever current frame for the animation is changed

• Finally there's onUpdate which is at every frame regardless of whether the animation is active/running or not

All these handlers take in an animation object as a parameter!

Actor

An actor is nothing but a group of animations making transformations easier. They are very similar to an Animated-Sprite in SodaPop only difference being that they are much efficient! An actor can have multiple animations but only one animation can be displayed at a time. Further an actor can also act like a FSM in that it has in-built behaviour and logic for transitioning between states!

Actor Handlers

There's only one callback function for an actor:-

• onSwitch which is called whenever an actor switches from one state/animation to another! The actor itself and the previous state are passed as arguments!