The Texture property is a reference to the Texture2D referenced by an AnimationFrame. This is the Texture that it will apply when the animation is being displayed. This is automatically set when loading a .achx file (such as in Glue), but it can be changed at runtime, or can be set when creating a new frame.

Introduction

A ShapeCollectionSave instance which can be used to apply a frame's collision to an entity. By default this is null.

Example - Setting an Entity's Collision

The most common usage is to add shapes to an AnimationChainListSave file (.achx) and to apply animations to a collidable Entity. The following example assumes that shapes have been added to a frame in the AnimationEditor.

// in an Entity's CustomActivity:
SpriteInstance.CurrentFrame?.ShapeCollectionSave?.SetValuesOn(this.Collision, this, true);

// Optional, if you want to see the shapes visually:
this.ForceUpdateDependenciesDeep();
this.Collision.Visible = true;

The code performs null checks (through the null coalescing operator), since a frame may not have collision data. If a frame does not have collision data, then the collision will not be modified. Note that if one frame does have collision, but subsequent frames do not, then the collision will remain unchanged when the later frames are played. Therefore, if one frame has collision, other frames should as well to avoid confusing behavior.

Introduction

AnimationFrames represent the state of an IAnimationChainAnimatable. The following properties can be set by an AnimationFrame:

• Texture

• RelativeX/Y Position

• Texture Coordinates

• Horizontal/Vertical Flipping

AnimationFrames usually exist inside AnimationChains.

Creating an AnimationFrame

AnimationFrame instances are typically contained in AnimationChains, and are created by loading a .achx file. AnimationFrames can be constructed in code, and can be added to AnimationChains (see below).

Creating an AnimationFrame in Code

Although .achx files are the most common way to create AnimationFrames and AnimationChains, AnimationFrames can also be constructed in code. The following code shows how to construct an AnimationChain and AnimationFrame in code, assign it to an existing Sprite, and update the Sprite to the AnimationChain:

void CustomInitialize()
{
    // This code assumes SpriteInstance is a valid Sprite,
    //  TextureFile is a valid Texture2D.
    AnimationChain animationChain = new AnimationChain();

    AnimationFrame animationFrame = new AnimationFrame();
    animationFrame.Texture = TextureFile;

    // TextureCoordinates are normalized. In other
    // words:
    // * 0 represents the left or top edge of the texture
    // * 1 represents the right or bottom edge of the texture
    animationFrame.LeftCoordinate = 0;
    animationFrame.RightCoordinate = 1;
    animationFrame.TopCoordinate = 0;
    // A value of .5 means halfway down the texture. 
    // By setting the BottomCoordinate to .5f, only the top
    // half of the Sprite gets drawn.
    animationFrame.BottomCoordinate = .5f;

    animationChain.Add(animationFrame);

    SpriteInstance.SetAnimationChain(animationChain);

    SpriteInstance.UpdateToCurrentAnimationFrame();
}

FrameLength

The FrameLength property defines how long an AnimationFrame is displayed. Adding the FrameLengths of all AnimationFrames in an AnimationChain results in the length of the entire animation. FrameLength - like all timing in FlatRedBall - is performed in seconds. Therefore, if an AnimationFrame has a FrameLength of 1, the AnimationFrame will show for 1 second. If you are familiar with working in milliseconds, then simply divide the desired value by 1,000. For example, to set the FrameLength to 600 millseconds, simply divide 600 by 1,000 and set that value to your FrameLength:

myFrame.FrameLength = 600/1000.0f;
// OR
myFrame.FrameLength = .6f;

Introduction

The RelativeX and RelativeY values in an AnimationFrame can be used to offset an animated object on a per-frame basis. This is useful if the images that are being used for the animation do not line up as desired. The relative values can be set by code or in the AnimationEditor.

Requirements for use

Simply setting the RelativeX and RelativeY values on an AnimationFrame is not sufficient to change the position of an IAnimationChainAnimatable (such as a Sprite. The following conditions must be met:

• The object (such as the Sprite) that is displaying the animation must be attached to another PositionedObject.

• The UseAnimationRelativePosition property must be true.

If you are using objects created in Glue, then both of the above will usually be true.

Example

The following code creates an AnimationFrame which displays the four quadrants of a redball.bmp graphic, then displays it in its entirety. The RelativeX and RelativeY values are used to offset the frames which display a single quadrant. Notice that the animated Sprite must be attached to an object and that the Sprite's UseAnimationRelativePosition property must be set to true.

// Create the animationChain
AnimationChain animationChain = new AnimationChain();

// Create the redball texture that will be used
Texture2D redballTexture = FlatRedBallServices.Load<Texture2D>("redball.bmp");

// Add the 5 frames
float frameLength = .1f; // in seconds
AnimationFrame frame = new AnimationFrame(redballTexture, frameLength);
animationChain.Add(frame); // this is the "whole ball" image

frame = frame.Clone(); // same frame time, same texture
frame.RightCoordinate = .5f;
frame.BottomCoordinate = .5f;
frame.RelativeX = -.5f;
frame.RelativeY = .5f;
animationChain.Add(frame); // top left quadrant

frame = frame.Clone();
frame.LeftCoordinate = .5f;
frame.RightCoordinate = 1;
// top and bottom are still the same - 0 and .5f respectively
frame.RelativeX = .5f;
// RelativeY still .5f like it should be for this frame
animationChain.Add(frame); // top right quadrant

frame = frame.Clone();
// left and right are set ok from the cloned frame
frame.TopCoordinate = .5f;
frame.BottomCoordinate = 1;
// RelativeX still .5f like it shoudl be for this frame
frame.RelativeY = -.5f;
animationChain.Add(frame); // bottom right quadrant

frame = frame.Clone();
// top and bottom are set ok from the cloned frame
frame.LeftCoordinate = 0;
frame.RightCoordinate = .5f;
// RelativeY still -.5f like it shoudl be for this frame
frame.RelativeX = -.5f;
animationChain.Add(frame); // bottom right quadrant

Sprite animatedSprite = SpriteManager.AddSprite(animationChain);
// make sure to have the Sprite use the AnimationFrame's relative values:
animatedSprite.UseAnimationRelativePosition = true;

// Set the pixel size so it gets resized:
// Make sure to use a float!!
animatedSprite.PixelSize = 1.0f / redballTexture.Width;

// Normally this'd be added to the SpriteManager,
// but for this example it's not necessary.
PositionedObject parent = new PositionedObject();

animatedSprite.AttachTo(parent, false);