doc/animation_tutorial.txt

   1 = Animation Tutorial =
   2
   3 == The Basic Idea ==
   4 LuaGame already takes care of splitting apart horizontal animation strips and
   5 blitting the right frame through the *display_frame* function. The only thing that
   6 actually needs to be tracked is what frame should currently be playing. Luckily,
   7 there's an easy to use way to do this.
   8
   9 There is a function called *create_animation_iterator* which returns a closure.
  10 This function gets passed the number of frames, the time per frame (in ms), and
  11 the number of times one wants the animation to play. If the third argument is
  12 omitted, then the animation will loop continuously. This returned function, when
  13 run, will return the current frame of the animation, and whether or not the
  14 animation is still playing (useful for dealing with entities that disappear
  15 after playing their animation).
  16
  17 == Using It ==
  18 Unless one wants all animations to be synchronized, then one should initialize
  19 a relevant field in the constructor of an object, not the class initialization.
  20
  21 [lua]
  22 source~~~~~~~~~~~~~~~~~~~~~~~~~~
  23 function MyObject:new(o)\r
  24   o = o or {}\r
  25   setmetatable(o, self)\r
  26   self.__index = self
  27   o.anim = create_animation_iterator(16,100)\r
  28   return o\r
  29 end
  30 source~~~~~~~~~~~~~~~~~~~~~~~~~~
  31
  32 The above code shows creating a 16-frame animation iterator where each frame lasts
  33 for 100 milliseconds. One thing to note, is that animation is always time-based
  34 and not frame-based. The actual usage of this iterator occurs right before the
  35 image is drawn.
  36
  37 [lua]
  38 source~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  39 function MyObject:draw()
  40   local f, p = self.anim()
  41   display_frame(self.image, self.x, self.y, 16, f, 0, 1, 1, 255)
  42 end
  43 source~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  44
  45 == Reinitializing Animations ==
  46 If one wants to re-use an animation iterator that has already looped past the maximum
  47 number of loops, then one need only pass some value other than *nil* as an argument
  48 to the iterator. This will reset the frame, the loop, and the time variables and
  49 make it so that it can be re-used reliably. This is useful if an entity has a
  50 number of states which each have their own animations and the transitions rely on
  51 animations ending.