Introduction

Collision shapes can be controlled through the AnimationEditor. This allows collision to align with animation frames.

Adding Collision to an Animation

The simplest setup for using collisions from an animation requires an animated collidable entity. For example, such an entity would contain a Sprite and an AxisAlignedRectangle as shown in the following entity creation dialog:

Of course, existing entities (such as Player) can also be animated using collision so long as they contain an animated Sprite and they implement ICollidable.

For this example we will use the Player object as an example, but these concepts can be applied to any entity. Animation collisions can be defined in the AnimationEditor. Each frame can contain one or more shapes. To add a shape to a frame:

1. Open the AnimationEditor

2. Select a frame which should have collision

3. Right-click on the frame in the tree view and select Add AxisAlignedRectangle. Note that at the time of this writing only AxisAlignedRectangles are supported, but future versions of shapes will be added.
4. Once added, the AxisAlignedRectangle displays in the bottom preview window
5. The AxisAlignedRectangle's properties can be modified in the property grid

Changes to shapes will automatically be saved to disk. The example above shows an animation with a single frame, but since each frame can contain rectangles, then this allows the collision size to change frame-by-frame.

Setting Animation Collision Through FlatRedBall Editor

If you have an animated Sprite, you can automatically tell FlatRedBall to generate code which will update the entity's Collision object by checking the Set Collision From Animation property.

To do this:

1. Add a Sprite to your collidable entity

2. Add an animation to the Sprite

3. Check the Set Collision From Animation checkbox

This automatically generates code which updates the collision. If you would like to perform this manually, see the next section.

Setting Animation Collision in Code

Once an animation contains shapes, the shapes can be used at runtime. The easiest way to implement this is to use the SetValues method on the frame's ShapeCollection as shown in the following snippet:

private void CustomActivity()
{
    this.SpriteInstance.CurrentFrame?.ShapeCollectionSave?.SetValuesOn(
        this.Collision, this, createMissingShapes:true);

    // This is needed if you want to see the rectangle visibly. It is not necessary
    // for proper collision functionality.
    this.ForceUpdateDependenciesDeep();

}

This code automatically updates the collision to match how it is laid out in the AnimationEditor.

Names Matching

Entities and animation frames can each contain multiple shapes. To use the SetValuesOn method, the names between the two must match. In the example above, the rectangles on the animation and entity are both called AxisAlignedRectangleInstance (the default name).

Using matching names is especially important if you intend to have multiple shapes per frame of animation.

Missing Shape Behavior

Animation frames which do not have any shapes will not affect the collision in the entity. In the example above the CharacterIdleRight animation contains a frame which defines a rectangle. When this animation plays, the rectangle size will be applied. When other animations are played, the rectangle will remain the same size as was set by CharacterIdleRight. Keep this in mind, as creating animations which only have some frames defining a rectangle may result in unexpected behavior. The following animation shows the behavior of the rectangle when only the idle right animation defines the shape. Notice that the rectangle grows when the player faces to the right, and then remains the same size for all other animations:

Multiple Shapes per Frame

As mentioned above, multiple shapes can be added per frame. This can be useful if you have different subcollision behaviors in your game. For example, your Player may have a shape for its entire body, and one shape for feet so the player can stomp on enemies.

In this case you would want to also add the same shapes in your entity so that the code shown above could be used to automatically manage the rectangle positions and sizes.

Troubleshooting

If your shapes in game are not modified by the shapes in the AnimationEditor you can check a few things to locate the problem.

SetCollisionFromAnimation in Generated Code

If your Sprite is set up properly, you should see the SetCollisionFromAnimation method being called on a Sprite. This method should appear in your Activity method in generated code.

If this does not appear, verify that the following are true:

• Your entity is an ICollidable entity, or implements ICollidable recursively. This should be true if you added shapes to the entity when it was first created.

• Your .gluj file version is greater than or equal to 45. For more information see the FileVersion (.gluj) page.

• You have a Sprite in the entity

• The Sprite's Set Collision From Animation is set to true

• You are playing the animation in your game

Introduction

The AnimationEditor is a tool which simplifies the creation and editing of AnimationChainList files (.achx files). AnimationChainLists are the standard file format for sprite animations in the FlatRedBall Engine. Note that since the AnimationEditor produces plain XML files, these files can be consumed in any environment, so it can be used for any type of game, not just FlatRedBall games.

Opening the AnimationEditor

The AnimationEditor is distributed along FRB in the FRBDK.zip file. For info on downloading the FRBDK.zip file, see the Downloads page. You can open the AnimationEditor by either:

• Double-clicking an .achx file in the FRB Editor. Note that if you have not set up the Windows file association for .achx files, you may be asked how to open this file. You can select to use the AnimationEditor.exe, which is located in the place shown in the next point:
• Or opening the AnimationEditor.exe in the XNA 4 Tools folder

You can also add a new .achx file to your FlatRedBall project in any Screen, Entity, or in Global Content Files:

1. Right-click on the Files folder in any Screen or Entity, or in Global Content Files

2. Select Add File -> New File
3. Select Animation Chain List (.achx)

4. Click OK

Troubleshooting the AnimationEditor

If you are seeing a popup that tells you that XNA is not available, then you probably do not have the XNA runtimes installed. The text for this error might look like this: System.IO.FileNotFoundException: Could not load file or assembly 'Microsoft.Xna.Framework.Graphics.dll' or one of its dependencies. The specified module could not be found. To fix this problem, install the XNA 4 redistributable: https://www.microsoft.com/en-us/download/details.aspx?id=27598 Once you run AnimationEditor.exe you will have an empty animation project.

Creating an Animation

To create an animation:

1. Click the + icon on the left-side of the window
2. Enter the name "Idle" and click OK

Next we'll add a frame to our animation. To do this:

1. Right-click on the newly-added Idle animation

2. Select "Add Frame"

Setting the Texture

Now we have an animation with one frame, but the frame does not yet have a texture associated with it. Textures are image files which are displayed by the frame. To add a texture:

1. Save this file to your computer.

3. Click the button for the "TextureName" property \
4. Navigate to where you saved the Idle.png file and select it

5. You may see a window asking you if you want the file copied. In most cases you do; however you may not if in the future you are working with textures which are shared between multiple files which are not in the same location.

You should now see your art in the AnimationEditor: \

Alternative - Changing the Texture

A frame's texture is displayed in two places:

1. In the TextureName propert in the property grid

2. In the texture selection drop-down

The drop-down can be used to change a frame's texture to any png file that is part of your FlatRedBall project. This can be easier than navigating to find the file on-disk, and can save you from accidentally selecting files outside of your project resulting in duplicate copies.

To change a texture using the dropdown:

1. Select the frame that you would like to change

2. Use the dropdown to pick a different file\
3. Once you have changed the texture, you may need to adjust your X/Y/Width/Height coordinates on the frame

Setting the frame using SpriteSheet values

The FRB editor provides a number of ways to specify the region of a texture which will be displayed by a frame. If you are using separate image files for each frame of animation then you will not need to change the region values. However, if you are using a sprite sheet, then you will need to adjust the region that the frame displays.

What is a sprite sheet? In the context of the AnimationEditor plugin, a sprite sheet is a image file which contains multiple frames of animation. Although not necessary, many sprite sheets arrange each animation frame in a grid, and all frames are spread out evenly.

First we'll cover how to create animation frames using sprite sheets. To do this in the AnimationEditor plugin, the frames must be evenly spaced out. The Idle.png file supplied above is evenly spaced out, so it will work fine for this tutorial. First we need to tell the AnimationEditor plugin that we want to use sprite sheet coordinates. To do this:

1. Set the combo box value at the top of the property grid to "SpriteSheet"
2. Find and select where it says <UNTEXTURED> in the leftmost menu area. You should then see an option for editing the cell width and cell height of the texture. Set the cell height to "2 cells". Notice that the plugin automatically calculates this value as 64 pixels after the value is selected.
3. Set the cell width to "4 cells"

4. Notice that the preview window now shows the image divided up into its cells according to the values you just selected \

Now that the cells are set up properly, you can select the cell of a frame by clicking on the appropriate cell. Once the cell has been clicked on, it will highlight. The preview window (the window under the editing window) will also show the single frame as it will appear in game.

Adding Additional Frames

Once a single frame has been added, additional frames are very easy to add. To add another frame:

1. Right-click on the Animation (which is called Idle)

2. Select "Add Frame"

3. The newly-added frame will be selected. Click on the cell that you want the frame to use

Since the FRB editor remembers the cell settings, additional frames can be added with just a few mouse clicks. Try adding more frames so that your animation includes all 8 idle frames.

Viewing the Animation

Once you have added all frames, you can view the animation as it will play in your game by clicking on the animation itself in the far-left window. The animation will play in the preview window automatically. Clicking on any individual frame will also update the preview window. Similar to other FRB tools, you can use the mouse wheel to zoom in and out, and you can hold the middle mouse button down to pan. These controls are available both in the editing window and the preview window.

Editing in Pixel Coordinates

If you are working with an image file which is not structured in a sprite sheet you can still use this file in the AnimationEditor plugin. In this situation you will need to use the "Pixel" coordinate mode. Next we'll use the Pixel coordinate mode to create a run animation. First, let's set up a frame:

2. Right-click in the far-left window and select "Add Animation"

3. Enter the name "Run"

4. Right-click on the newly-added animation and select "Add Frame"

5. Select the downloaded Running.png image for the new frame's TextureName

6. If asked, copy the file to the same folder as the AnimationChain

Using the Guides

The AnimationEditor plugin provides rulers and guides to help you verify that animations are positioned properly. Next, we'll use guides to align our animations. The animations that we have been working with so far (idle and run) are created for a side-view game (specifically a platformer game). The location of the ground is an important consideration when working on games like these. Therefore, we will use guides to verify that the animations are aligned properly.

Note: I intentionally created the animations so that they were of different sizes. Your animations may or may not be set up this way, so keep that in mind when working through the rest of this guide tutorial.

The first step is to decide which animation we want to set up our guides to. I'll use the idle animation since we created it with sprite sheet coordinates, so it is likely more accurate. To do this:

1. Select the "Idle" animation

2. Zoom in on the preview of the animation (the bottom display)

1. Change the source .PNG to have the character positioned higher. This is not a good approach in this particular case because the art was actually created to include equally-spaced frames.

2. Adjust the pixel coordinates of the frame to be lower, adding more transparent space under the character and shifting up the animation. While this is a good approach, we'll skip over it in favor of the next option.

3. Set the relative values of each frame to shift the animation upward.

Next we'll cover how to shift each frame.

Shifting Frames

Each frame can be independently positioned. By default all frames are not shifted at all - frames are positioned with their center at (0,0). To shift the first frame in "Run":

1. Expand the Run animation

2. Select the first frame

Once the RelativeY value (and similarly RelativeX) is changed, the preview window will update immediately, allowing you to update frames appropriately.

Frame Time

Each frame in an animation defines how long it is displayed when the animation is played. The animation editor allows editing the frame time to speed up or slow down individual frames or the entire animation.

Changing the Frame Time

To change the amount of time that an individual frame is displayed in an animation:

1. Select a frame in the animation

2. Find the FrameLength property

3. Change the value to the desired length in seconds

Changing the Entire Animation Length

The entire length of an animation can be changed without manually changing each individual frame. To do this:

1. Right-click on the desired animation

2. Select Adjust All Frame Time

3. Enter the new desired length of the animation

4. (Optionally) select the desired option for changing the frame time. The frames can be adjusted to all have the same value, or can be adjusted proportionally to achieve the desired animation length