Parameters:

• image Image

  represents the image on which the SpriteSheet coordinate will be applied.

• config Object

  represents the object which provides the description of each animation.

  var mySpriteSheet = new SpriteSheet(image, config);
  

  config object represents the raw configuration of the spriteSheet. Please see below the synthax of a spriteSheet :

  The SpriteSheet in tumbleweed work on JSON objects. Inside of these JSON objects, there is a description of all or just one animation. In the previous example, config is a full description of the animation. Here is how tumbleweed's spritesheets are configured :

  First of all let's define the structure of our SpriteSheet object :

  {}
  

  As you can see it is only an empty JSON object. This object can handle some informations about the animation.

  Setting default values

  default : {}
  

  The default object can handle default values. It is useful to make some constants in the spriteSheet. For example if you want to define 5 constants (x = 10, y = 30, w = 50, h = 60, framerate = 25) You must proceed like this :

  default : {
       x : 10,
       y : 30,
       w : 50,
       h : 60,
       framerate : 25
  }
  

  Setting animations

  Each animation is composed by frames and can also define a framerate value which override the framerate from default values. Here is an important tip, in some animations you may don't want to use the default values. Then you just Have to redefine them inside of the animation. To create an animation named 'walk' which have framerate set to 12 you must proceed like this :

  walk : {
       framerate: 12,
       frames : []
  }
  

  Note that there is an entry in you walk animation called frames. This entry must contain each frame of the walk animation.

  Setting frames

  Each animation contain some frames. It works like a flipbook, each frame are displayed one after another, tumbleweed will wait 1/framerate seconds to display the next frame. Let's imagine that your walk animation is made of three frames inside of your SpriteSheet. The first one will have the coordinate : x = 0, y = 0, w = 50, h = 50 The second one will have the coordinate : x = 50, y = 0, w = 50, h = 50 And finally the third one will have the coordinate : x = 0, y = 50, w = 50, h = 50

  Let's see below what will be the result of these frame inside of our walk animation object :

  walk : {
       framerate: 12,
       frames : [
           { x: 0, y: 0, w: 50, h: 50 },
           { x: 50, y: 0, w: 50, h: 50 },
           { x: 0, y: 50, w: 50, h: 50 }
       ]
  }
  

  Let's wrap it inside of our config object :

  var config = {
       default: {
           x: 0,
           y: 0,
           w: 50,
           h: 50,
           framerate: 25
       },
       walk: {
           framerate: 12,
           frames: [
               {x:0, y:0, w: 50, h: 50},
               {x:50, y:0, w:50, h:50},
               {x:0, y:50, w:50, h:50}
           ]
       }
  };
  

  Now you have a walk animation which contain 3 frames which will be displayed with a framerate of 12. You have the basics to build your own animations. In the following parts i will describe how to make animation's reference and how you can do transformations on them.

  Animation's reference

  Sometimes you can need to specify another animation which is a copy of another animation but with some transformations on it, the typical case will be an animation of walking to right and another animation which is walking to left. Frames are the same except that they must be reverted horizontally. To make it we will introduce a new entity which is the flip flags. Flip flags allow you to flip images from an animation. You can either flip them by the x axis (horizontal flip) or by the y axis (vertical flip).

  To illustrate it we will improve our config object which contain the walk animation. Now we want 2 walk animation (walkleft and walkright). Initially we will consider that our previous definition of the walk animation was equivalent to the walk_left animation.

  Now let's see now how looks like our config object :

  var config = {
       default: {
           x: 0,
           y: 0,
           w: 50,
           h: 50,
           framerate: 25
       },
       walk_left: {
           framerate: 12,
           frames: [
               {x:0, y:0, w: 50, h: 50 },
               {x:50, y:0, w:50, h:50 },
               {x:0, y:50, w:50, h:50 }
           ]
       },
       walk_right: {                           //This is our new animation entry : walk_right
           framerate: 12,                      //The framerate is the same than walk_left
           frames: [
               {x:0, y:0, w:50, h:50},         //The frames are also the same than walk_left
               {x:50, y:0, w:50, h:50},
               {x:0, y:50, w:50, h:50}
           ],
           flipX: true,                       //Flip_x true indicate that all the frames must be
                                               //horizontally flipped before being draw.
       }
  };
  

  There's one annoying thing in the previous definition, as you can see, the frames of the walkleft animation and the frames of the walkright animation are duplicated. There's one way to solve this problem : the alias flag.

  Alias flag

  Alias flag allows you to define an animation by referencing another, it's quite useful when an animation has the same frames than another. And we're actually in this case. Using the alias flag, this is what will be your config object :

  var config = {
       default: {
           x: 0,
           y: 0,
           w: 50,
           h: 50,
           framerate: 25
       },
       walk_left: {
           framerate: 12,
           frames: [
               {x:0, y:0, w: 50, h: 50 },
               {x:50, y:0, w:50, h:50 },
               {x:0, y:50, w:50, h:50 }
           ]
       },
       walk_right: {               //This is our new animation entry : walk_right
           framerate: 12,          //The framerate is the same than walk_left
           alias: "walk_left",     //by declaring walk_left as alias,
                                   // walk_right will share it's frames with walk_left.
           flipX: true,           //Flip_x true indicate that all the frames must be
                                   //horizontally flipped before being draw.
       }
  };
  

  define frames more quickly

  It's possible to define many frames in one line, if these frames follow or if they are identical.

  If all frames are on the same line, or the same collumn, we can just specify the number of frames we want, and the direction of repetition. No direction means we want to copy and repeat the frame.

  Repeat a frame can be useful in some case. For example if you want to wait more than one cycle to go on the next frame.

  • nbFrames is the number of frames we want

  • way is the direction we want to move for the next frames. If not defined, it's a repetition. It can take 4 values :

    • "LEFT",
    • "RIGHT"
    • "UP"
    • "DOWN"

  Example :

  var config = {
       default: {
           x: 0,
           y: 0,
           w: 50,
           h: 50,
           framerate: 25
       },
       walk_left: {
           framerate: 12,
           frames: [
               {x:0, y:0, w: 50, h: 50 },
               {x:50, y:0, w:50, h:50 },
               {x:0, y:50, w:50, h:50, nbFrames: 5 }                  //This frame will be duplicated 5 times.
               {x:0, y:100, w:50, h:50, nbFrames: 5, way: "RIGHT" }   //We take 5 frames, moving on the right.
           ]
       },
       walk_right: {
           framerate: 12,
           alias: "walk_left",
           flipX: true
       }
  };
  

  Now let me introduce you the last feature which allows you to reverse the frames order of an animation. There's some case where you will need to reverse the frames of an animation, especially when you animation is an alias of another. Let's took our previous example, now, i want to add two moonwalk animation (moonwalkleft, moonwalkright). To make them i will apply to them respectively an alias of the walkleft and walkright, and then, i will apply to moonwalkright and moonwalkright the reverse flag which will reverse the frames that the animation contains.

  var config = {
       default: {
           x: 0,
           y: 0,
           w: 50,
           h: 50,
           framerate: 25
       },
       walk_left: {
           framerate: 12,
           frames: [
               {x:0, y:0, w: 50, h: 50 },
               {x:50, y:0, w:50, h:50 },
               {x:0, y:50, w:50, h:50, nbFrames: 5 },                 //This frame will be duplicated 5 times.
               {x:0, y:100, w:50, h:50, nbFrames: 5, way: "RIGHT" }   //We take 5 frames, moving on the right.
           ]
       },
       walk_right: {
           framerate: 12,
           alias: "walk_left",
           flipX: true
       },
       moonwalk_left: {
           framerate: 12,
           alias: "walk_right",
           reverse: true           //We set our moonwalk_left animation to be reversed.
       },
       moonwalk_right: {
           framerate: 12,
           alias: "walk_left",
           reverse: true           //We set out moonwalk_right animation to be reversed.
       }
  };
  

  Hotpoint

  As it's possible to define frames of any size, two frames in an animation can be of differents sizes. However, this fact hides a problem : if the element must change size, how to enlarge the sprite ? by the right or the left ? Up or bottom ?

  Usually, we can use the centerPoint. If it's defined in the up-left corner, the sprite will grow toward bottom and right. If it's defined on the center, the sprite will grow from all sides.

  But it's not always the best choice. So, you can redefine the centerPoint for the transition with the hotpoint param. It can take these following values :

  • TOP-LEFT
  • TOP-CENTER
  • TOP-RIGHT
  • CENTER-LEFT
  • CENTER-CENTER
  • CENTER-RIGHT
  • BOTTOM-LEFT
  • BOTTOM-CENTER
  • BOTTOM-RIGHT

  Example:

  grow_up: {
       framerate: 12,
       frames: [
           {x:0, y:0, w:50, h:50 },
           {x:50, y:0, w:50, h:150, hotpoint: "BOTTOM-CENTER" }
           //the height grow from 50 to 150
           //but the center bottom point will not move.
       ]
  }