Examples

example_1A

Basic initialisation.
See this page for all available parameters.

sprite = AnimatedSprite.new(imagetable) -- Creating AnimatedSprite instance (imagetable or path)
sprite:addState("idle", 1, 5, {tickStep = 2}) -- Adding custom animation state
sprite:playAnimation() -- Playing the animation

• You can use loaded imagetable or imagetable path (string). If you use the same imagetable at least twice, it's highly recommended to cache it and don't use path to load each time.
• Here 1 is index of first frame from the imagetable to be used in the animation, 5 is index of the last frame from the imagetable. Animation will be sequential between this two frames, i.e. 1-2-3-4-5-1...
• For yoyo effect (1-2-3-4-5-4-3-2-1-2...) you can use yoyo param.
• For not sequential frames take a look to frames param.

example_1B

You can overwrite the sprite's :update() function. If you do so, don't forget to call updateAnimation() in :update().

sprite = AnimatedSprite.new(imagetable)
sprite:addState("idle", 1, 5, {tickStep = 2})
sprite:addState("appear", 6, nil, {tickStep = 2, nextAnimation = "idle"}).asDefault() -- nil can be passed to represent last frame of the imagetable

function sprite:update()
    local newX = sprite.x + 1
    if newX > 400 then
        sprite:changeState("appear")
        newX -= 400
    end
    sprite:moveTo(newX, sprite.y)

    sprite:updateAnimation()
end

sprite:playAnimation()

example_1C

Pass nil if you want your animation state to play from the first frame to the last frame of the imagetable, but you want to configure playback.
Alternatively you can just change states.default state as shown in example_3A or manually by changing sprite.states.default's values.

sprite = AnimatedSprite.new(imagetable)
sprite:addState("idle", nil, nil, {tickStep = 2}, true) -- "True" stands for autoplay, substitutes :playAnimation()

example_2A

Best practice. Using states from configuration json file.

local states = AnimatedSprite.loadStates("path")
sprite = AnimatedSprite.new(imagetable, states, true) -- "True" stands for autoplay, substitutes :playAnimation()

example_2B

You can start the animation later after initialising sprite.

local states = AnimatedSprite.loadStates("path")
sprite = AnimatedSprite.new(imagetable, states)
sprite:playAnimation()

example_2C

You can set up states later after initialising sprite.

local states = AnimatedSprite.loadStates("path")
sprite = AnimatedSprite.new(imagetable)
sprite:setStates(states)
sprite:playAnimation()

example_2D

One line initialisation.

sprite = AnimatedSprite.new(imagetable, AnimatedSprite.loadStates("path"), true) -- "True" stands for autoplay, substitutes :playAnimation()

example_3A

Only "default" state can be partly updated, other states will be fully overwritten when using :setStates.
If you want to update some values, please refer to them directly (example_3B).

sprite = AnimatedSprite.new(imagetable)
sprite:setStates({
    {
        name = "default",
        onFrameChangedEvent = function (self) print(self._currentFrame) end,
        onStateChangedEvent = function (self) print("State changed to", self.currentState) end,
        onLoopFinishedEvent = function (self) print("Finished loops =", self._loopsFinished) end,
        onAnimationEndEvent = function (self) print("Ended animation of the state", self.currentState) end
    },
    {
        name = "idle",
        firstFrameIndex = 3,
        framesCount = 5,
        tickStep = 4,
        yoyo = true,
    },
    {
        name = "run",
        firstFrameIndex = "idle",
        framesCount = 10,
        tickStep = 2,
        loop = 5,
        nextAnimation = "idle"
    }
}, true, "run")

example_3B

You can directly change values in states on the go.

local states = AnimatedSprite.loadStates("path")
sprite = AnimatedSprite.new(imagetable, states)
sprite.states.default.tickStep = 4
sprite.states.idle.flip = gfx.kImageFlippedXY
sprite.states.idle.onFrameChangedEvent = function (self) print(self._currentFrame) end
sprite:playAnimation()

example_3C

If your state can transit to several other states, then you can write it's behaviour logic in the onAnimationEndEvent

sprite.states["stand up"].onAnimationEndEvent = function ()
    sprite:changeState(sprite.jumping and "fall idle" or "run")
end

Or make use of self argument that is automatically sent for all events:

sprite.states["stand up"].onAnimationEndEvent = function (self)
    self:changeState(self.jumping and "fall idle" or "run")
end