ZoomEngine.Animation Part 1

ZoomEngine.Animation is a lightweight, easy to use, and powerful declarative animation library for XNA Game Studio.

As a gift for those who found my newly revived blog, I decided to share it with you.  It’s a small part of a larger game engine called ‘ZoomEngine’, but it doesn’t have any dependencies on the rest of the engine so I thought it would be a good candidate to share.  Hopefully down the line I’ll pull out more of our engine to share.

NOTE: This is from my personal game engine, and not something that’s in any way affiliated or supported by Microsoft.

In Part 1 of this series I will go over the basics of how to use this animation library in your game, and in subsequent posts I’ll go into more details on some of the advanced features and how you can extend the library.

So you may be asking yourself “what is a declarative animation library?”  To answer this, lets first look at how ZoomEngine.Animation is used.

    1                 var positionAnim = new Vector2FromToAnimation(clockManager)

    2                 {

    3                     From              = item.Position,

    4                     To                = new Vector2(item.Position.X + 600, item.Position.Y),

    5                     Duration          = 2,

    6                 };

    7 

    8                 positionAnim.Start();

You can see from the code above, by ‘declarative’ I mean that properties on the animation object determine what range of values the animation produces as time goes on.  The properties are declared before the animation begins, and are not typically changed during the animation (although this is possible).

Take notice of the naming of the type Vector2FromToAnimation.  The convention I use for the animation types is [TypeBeingAnimated][KindOfAnimation]Animation.  In this library an ‘animation’ is an object that produces values of a specific type (TypeBeingAnimated).  The ‘FromTo’ part indicates how you specify the range of values.  In this case it’s by specifying the From/To properties for the endpoints of a linear interpolation.  Another example of “KindOfAnimation” would be KeyFrame.  We’ll talk more about this in a later post.

Q: What does the above animation do?
A: Basically nothing.  I said that animations produce values, but we haven’t yet told the animation what to do with the values.  The next bit of code will show you how to apply the produced value.

    1                 var positionAnim = new Vector2FromToAnimation(clockManager)

    2                 {

    3                     From              = item.Position,

    4                     To                = new Vector2(item.Position.X + 600, item.Position.Y),

    5                     Duration          = 2,

    6                     Apply             = (v) => item.Position = v,

    7                 };

    8 

    9                 positionAnim.Start();

The Apply property is a delegate of type Action<T> where T is the TypeBeingAnimated.  This delegate gets called each time the ClockManager is Updated, and the new animated value is passed as the ‘v’ parameter.  You can do whatever you want with this value, but typically it is directly applied to a property on an object (like item.Position).  In this case the above animation will slide the Position of ‘item’ to the right by 600 units over a duration of 2 seconds.

Simple linear animations are lame, so lets now look at a more interesting example.

    1                 var colorAnim = new ColorFromToAnimation(clockManager)

    2                 {

    3                     From              = item.Color,

    4                     To                = Color.Firebrick,

    5                     Duration          = 2,

    6                     ProgressTransform = ProgressTransforms.Snake,

    7                     AutoReverse       = true,

    8                     RepeatCount       = int.MaxValue,

    9                     Apply             = (v) => item.Color = v,

   10                 };

   11 

   12                 colorAnim.Start();

In this example, we’re animating the color of ‘item’ from its initial color to Firebrick over 2 seconds.  This is similar to before except this time three new properties are introduced. ProgressTransform is a delegate that transforms the animation progress so that you can control the pacing of the animation.  In this case we’re using a predefined ProgressTransform called Snake (which looks like half a cosine wave).  AutoReverse tells the animation system that once the animation reaches the To value, it should head back to the From value.  RepeatCount tells the animation system how many times to do this before the animation is complete.  In this case, we’re more or less saying ‘do it forever’.  The end result is that the color will oscillate smoothly between its initial color & Firebrick.

 

That’s all for now folks.  If you want to see these animations in action, the zip below contains an XNA 3.1 project with the ZoomEngine.Animation library & a sample app.  Feel free to use this animation system in your own game and/or modify it in any way.  If you make something cool, send me a link (REMOVETHISbrandf AT microsoftREMOVETHIS.com)

Comments

• Anonymous
  April 06, 2010
  Your API looks really cool:) I think I'll make an API much like yours in my engine:) Underlying implementation probably have to be different, but the declarative form its very cool. Thank you for sharing