Use the animation.loop class from the SDK, implement mid-animation reversal.

src/entity.lua

@@ -2,6 +2,7 @@
 import "CoreLibs/object"
 import "CoreLibs/graphics"
 import "CoreLibs/sprites"
+import "CoreLibs/animation"
 import "statemachine"
 
 local gfx <const> = playdate.graphics
@@ -16,9 +17,8 @@ function Entity:init(img, health, armor)
    self.armor = armor or 0
    self.introAnimator = nil
 
-   -- For imagetable-based animation
-   self.animationIndex = nil
-   self.animationTimer = nil
+   -- For imagetable-based animation. see :animate()
+   self.animation = nil
 
    -- movement direction, every update() the entity will move along this vector and return
    -- collision data to the subclass
@@ -73,27 +73,29 @@ function Entity:update()
    -- update state machine
    self.fsm:execute()
 
-   if self.animationTimer then
-      local targetIndex = math.floor(self.animationTimer.value)
-      if self.animationIndex ~= targetIndex then
-         self:setImage(self.animationTable:getImage(targetIndex))
-      end
+   if self.animation and self.animation:isValid() then
+      -- TODO: consider efficiency of this vs implementing loop:draw() in a custom draw function
+      self:setImage(self.animation:image())
    end
 end
 
--- animate the entity based on the passed in imageTable. If reverse is true, play the
--- animation backwards. duration is how long the animation should be in total
--- TODO: it would be nice to be able to reverse the *current* animation without
---       starting all the way over at the beginning...
-function Entity:animate(imgTable, duration, reverse)
-   self.animationTable = imgTable
-   local startValue = 1
-   local endValue = #imgTable
-   if reverse then
-      startValue = #imgTable
-      endValue = 1
+-- animate the entity based on the passed in imageTable.
+-- duration is the length of *each* frame
+-- If loop is true the animation will start over at the beginning
+-- If reverse is true the animation will re-use the position in the *existing*
+--   animation, but inverted. This assumes the new imgTable is the same number of
+--   frames *and* is a valid reversal of the current animation
+function Entity:animate(imgTable, duration, loop, reverse)
+   local frame = 1
+
+   -- reverse has no effect if there is not an active animation
+   if reverse and self.animation and self.animation:isValid() then
+      frame = #imgTable - self.animation.frame + 1
    end
-   self.animationTimer = playdate.timer.new(duration, startValue, endValue)
+
+   loop = loop or false
+   self.animation = gfx.animation.loop.new(duration, imgTable, loop)
+   self.animation.frame = frame
 end
 
 -- State machine-controlled functions

src/kani.lua

@@ -46,11 +46,10 @@ local SPEED_SIZE_LOOKUP <const> = {
 
 -- animations table
 local animations <const> = {
-   defend=gfx.imagetable.new("images/kani/defend")
+   defend=gfx.imagetable.new("images/kani/defend"),
+   defend_reverse=gfx.imagetable.new("images/kani/defend_reverse"),
 }
 
-
-
 class("Kani").extends(Entity)
 
 function Kani:init(ui)
@@ -187,12 +186,12 @@ end
 
 function Kani:onDefend()
    self.armor = 5
-   self:animate(animations.defend, 500)
+   self:animate(animations.defend, 50)
 end
 
 function Kani:onDefendExit()
    self.armor = 0
-   self:animate(animations.defend, 500, true)
+   self:animate(animations.defend_reverse, 50, false, true)
 end
 
 function Kani:runDefend()