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.
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:
Right-click on the Files folder in any Screen or Entity, or in Global Content Files
Select Add File -> New File
Select Animation Chain List (.achx)
Click OK
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.
To create an animation:
Click the + icon on the left-side of the window
Enter the name "Idle" and click OK
Next we'll add a frame to our animation. To do this:
Right-click on the newly-added Idle animation
Select "Add Frame"
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:
Save this file to your computer.
Click the button for the "TextureName" property \
Navigate to where you saved the Idle.png file and select it
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: \
A frame's texture is displayed in two places:
In the TextureName propert in the property grid
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:
Select the frame that you would like to change
Use the dropdown to pick a different file\
Once you have changed the texture, you may need to adjust your X/Y/Width/Height coordinates on the frame
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:
Set the combo box value at the top of the property grid to "SpriteSheet"
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.
Set the cell width to "4 cells"
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.
Once a single frame has been added, additional frames are very easy to add. To add another frame:
Right-click on the Animation (which is called Idle)
Select "Add Frame"
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.
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.
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:
Right-click in the far-left window and select "Add Animation"
Enter the name "Run"
Right-click on the newly-added animation and select "Add Frame"
Select the downloaded Running.png image for the new frame's TextureName
If asked, copy the file to the same folder as the AnimationChain
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:
Select the "Idle" animation
Zoom in on the preview of the animation (the bottom display)
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.
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.
Set the relative values of each frame to shift the animation upward.
Next we'll cover how to shift each frame.
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":
Expand the Run animation
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.
Collision shapes can be controlled through the AnimationEditor. This allows collision to align with animation frames.
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:
Open the AnimationEditor
Select a frame which should have collision
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.
Once added, the AxisAlignedRectangle displays in the bottom preview window
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.
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:
Add a Sprite to your collidable entity
Add an animation to the Sprite
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.
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:
This code automatically updates the collision to match how it is laid out in the AnimationEditor.
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.
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:
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.
If your shapes in game are not modified by the shapes in the AnimationEditor you can check a few things to locate the problem.
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
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.
To change the amount of time that an individual frame is displayed in an animation:
Select a frame in the animation
Find the FrameLength property
Change the value to the desired length in seconds
The entire length of an animation can be changed without manually changing each individual frame. To do this:
Right-click on the desired animation
Select Adjust All Frame Time
Enter the new desired length of the animation
(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
The location doesn't matter, but remember where you save it because you will need to find it later. However, if you would like to use this file in a FlatRedBall project, you will want to save this file somewhere in your project's Content folder.
Download the following file to your computer:
To edit the frame using pixel coordinates, change the "Sprite Sheet" value to "Pixel You will now see a white square with 8 circle handles. You can push on the circles and drag to resize the frame. As you do so, you will notice that the preview window at the bottom updates in realtime. Keep in mind that you can pan and zoom by pushing/scrolling the mouse wheel. Just like when we were using sprite sheets, we can add additional frames to our animation by right-clicking on it and selecting "Add Frame". Do this to add a second frame. The newly added frame will use the same region as the previous frame. You can move the mouse over the region and the cursor will turn into a cross with arrows to indicate that the region can be moved. Push the mouse button to move the frame to the appropriate location for the second frame. To help keep the tutorial shorter we won't include the steps for creating the rest of the animation, but feel free to do so if you would like a complete running animation.
Click on the left side of the preview window on the ruler. A guide should appear
Push and drag on the guide line to adjust its position. Move the line so that it is just below the feet of the character so it represents the ground. The value of the line will update as the line moves
Now that we have a guide which represents the ground we can select the other animation to see how it lines up. Click on the "Run" animation to view it relative to the guide. Notice that the character is below the guide line. If we were to use this animation as-is in a platformer game, the character would appear to sink below the ground when running. We can fix this in a number of ways:
Change the RelativeY value so that the character is positioned properly relative to the guide