Animating Objects and Properties

This section explains how animations can be applied to animatable object and properties.

Animating a property

The following example demonstrates how an IAnimatablePropertyT can be animated.

// Create new property which can be animated.
AnimatableProperty<Vector3F> position = new AnimatableProperty<Vector3F>();

// Create an animation that animates the position from point (0, 0, 0)
// to point (100, 200, 300) over a time of 3 seconds.
var animation = new Vector3FFromToByAnimation
{
  From = new Vector3F(0, 0, 0),
  To = new Vector3F(100, 200, 300),
  Duration = TimeSpan.FromSeconds(3),
};

// Fetch the animation service from the global service provider.
var animationService = (IAnimationService)Game.Services.GetService(typeof(IAnimationService));

// Start the animation
animationService.StartAnimation(animation, position);

Animating an object

The advantage of an IAnimatableObject is that multiple animations can be applied at once. The following example to animations are combined into a "storyboard" (see class TimelineGroup). Each animation in the storyboard affects a different property. (The example applies the storyboard to an AnimatableSprite which was defined in the previous section.)

Copy

// Create an object which can be animated.
var sprite = new AnimatableSprite();

// Move the sprite from point (100, 100) to point (300, 200) on screen.
var positionAnimation = new Vector2FromToByAnimation
{
  TargetProperty = "Position",
  From = new Vector2(100, 100),
  To = new Vector2(300, 200),
};

// Change its color from red to blue.
var colorAnimation = new ColorFromToByAnimation
{
  TargetProperty = "Color",
  From = Color.Red,
  To = Color.Blue,
};

// Group the animations together in one 'storyboard'.
var storyboard = new TimelineGroup { positionAnimation, colorAnimation };

// Fetch the animation service from the service provider.
var animationService = (IAnimationService)Game.Services.GetService(typeof(IAnimationService));

// Start the animation
animationService.StartAnimation(storyboard, sprite);

The property TargetProperty assigns an animation to a certain property. The animation system automatically applies the animations to the matching properties. (Note that the type of the animation value needs to match the type of the property value.)

Important
Note that the sprite's current position does not change immediately after calling StartAnimation! The method only schedules the animation for playback. The new animation values are computed when AnimationManagerUpdate(TimeSpan) is called and the result are written in AnimationManagerApplyAnimations. The next section "Controlling Animations" shows how new animation values can be applied immediately if necessary.

Important

Note that the sprite's current position does not change immediately after calling StartAnimation! The method only schedules the animation for playback. The new animation values are computed when AnimationManagerUpdate(TimeSpan) is called and the result are written in AnimationManagerApplyAnimations.

The next section "Controlling Animations" shows how new animation values can be applied immediately if necessary.

Animating a group of objects

It is also possible to go one step further. Animations for different objects can be grouped together into a single storyboard.

Copy

// Create some sprites.
var sprites = new List<AnimatableSprite>
{
  new AnimatableSprite() { Name = "SpriteA" };
  new AnimatableSprite() { Name = "SpriteB" };
  new AnimatableSprite() { Name = "SpriteC" };
};

// Move spriteA from point (100, 100) to point (300, 100) on screen and at 
// the same time change its color from red to blue.
var positionAnimation = new Vector2FromToByAnimation
{
  TargetProperty = "Position",
  From = new Vector2(100, 100),
  To = new Vector2(300, 100),
};
var colorAnimation = new ColorFromToByAnimation
{
  TargetProperty = "Color",
  From = Color.Red,
  To = Color.Blue,
};

// Group the animations together.
var animationA = new TimelineGroup(); 
animationA.TargetObject = "SpriteA";
animationA.Add(positionAnimation);
animationA.Add(colorAnimation);

// Move spriteB from point (100, 200) to point (300, 200) on screen.
var animationB = new Vector2FromToByAnimation
{
  TargetObject = "SpriteB",
  TargetProperty = "Position",
  From = new Vector2(100, 200),
  To = new Vector2(300, 200),
};

// Move spriteC from point (100, 300) to point (300, 300) on screen.
var animationC = new Vector2FromToByAnimation
{
  TargetObject = "SpriteC",
  TargetProperty = "Position",
  From = new Vector2(100, 300),
  To = new Vector2(300, 300),
};

// Now, group all animations together in one 'storyboard'.
var storyboard = new TimelineGroup { animationA, animationB, animationC };

// Fetch the animation service from the global service provider.
var animationService = (IAnimationService)Game.Services.GetService(typeof(IAnimationService));

// Start the storyboard.
animationService.StartAnimation(storyboard, sprites);

The property TargetObject assigns each animation or timeline group to an object. The animation system then automatically applies the animations to the appropriate objects.

As shown in the example above, TimelineGroups can be nested. A timeline group can contain one or more animations or timeline groups.