Essentials Series/Custom Animations

This page is part of the Essential Series modding tutorials. In this guide, you will learn how to create custom ANIM assets for BFBB, and possibly other Heavy Iron games, using the BFBBAnimTools script for 3ds Max.

Installing BFBBAnimTools
You will 3ds Max and BFBBAnimTools in order to import and export ANIM assets:
 * 3ds Max (2018/2020 are supported, other versions have not been tested)
 * BFBBAnimTools

BFBBAnimTools is just a single MAXScript file (BFBBAnimTools.ms). You can place this file wherever you want, but it's recommended to place it inside your  folder. This allows you to skip a few steps when running BFBBAnimTools in 3ds Max.
 * Note: you will need administrator permissions in order to place BFBBAnimTools.ms in your  folder.

Importing the Model
In order to view and edit ANIM assets in 3ds Max, you first need to import a DFF model using the rwio plugin (see ../Extracting Models/ or the MODL page for more info).
 * For beginners, it's recommended to start with a model extracted from the game's files. In this guide, we'll use  from boot.HIP as an example.



It's very important that you make sure "Convert frame hierarchy" is enabled when importing your DFF model. This ensures that the skeleton's structure is laid out correctly for animations.
 * This window won't appear if you drag-and-drop your model into 3ds Max. Make sure you import by going to  instead.



If your DFF model imported correctly, you should have a hierarchy of "dummy" nodes along with the meshes. These nodes represent the bones of your model.
 * You can click the arrow on the left of a dummy node to expand its hierarchy.
 * Note: in order for ANIM assets to import and export correctly, the root dummy node MUST be named "Dummy002".



Running BFBBAnimTools
BFBBAnimTools is a utility script. To run utility scripts, first make sure the Command Panel is visible in 3ds Max.
 * If the Command Panel is not visible, from the menu bar, click.

Once the Command Panel is visible, click the ► button on the top-right corner until the Utilities tab is visible (it looks like a wrench).

Click the Utilities tab to show the Utilities rollout, then click the MAXScript button to show the MAXScript rollout.

The MAXScript rollout has a Utilities drop-down which is where you'll run BFBBAnimTools from.
 * If you placed BFBBAnimTools.ms in your  folder, you'll be able to select BFBB Anim Tools from the Utilities drop-down.
 * Otherwise, you'll need to tell 3ds Max where you placed BFBBAnimTools.ms. Click the Run Script button, and navigate to your BFBBAnimTools.ms file, wherever you placed it. Then you'll be able to select BFBB Anim Tools from the Utilities drop-down.



Your Command Panel should now look something like this:



The BFBB Anim Tools rollout has a few options:
 * Settings:
 * Reverse Bone Order: You may have to enable this setting if your animation does not appear correct when importing or exporting.
 * Import: Import an existing ANIM file onto the currently imported model.
 * Export: Export a custom ANIM file using the currently imported model's skeletal animation.
 * GameCube: this exports the ANIM file in a format supported by the GameCube version of BFBB.
 * PlayStation/Xbox: this exports the ANIM file in a format supported by the PlayStation and Xbox version of BFBB.

Importing an Existing Animation
To import an animation, click the Import button on the BFBB Anim Tools rollout and navigate to any file that's formatted an as ANIM asset. See the ANIM page for more info on the ANIM format.
 * GameCube, PlayStation 2, and Xbox are all supported formats for ANIM assets.

In this guide, we'll import  from boot.HIP onto our   model that we imported earlier.

If the animation imported correctly, you'll see that SpongeBob's skeleton has changed its pose to the starting frame of the animation.



At the bottom of the window, you'll see some controls to preview the animation:



You can click the Play button to play the animation. You may also want to click the Time Configuration button (clock and gear icon) and change your Playback settings to match these:



Editing
We won't go too much into the process of creating a custom animation in 3ds Max, since it is a fairly advanced topic.

From the menu bar, click  to open the timeline.



On the left you'll see the hierarchy of dummy nodes for your model. Just like in the normal Object List, you can expand a dummy node's hierarchy by clicking the arrow on the left of it.

If a dummy node is not selected in the Object List, you'll also see a plus-sign icon to the left of it. Click on the plus-sign icon to show that node's Tracks, which contain keyframes for its position and rotation throughout the animation.

To get a good view of a dummy node's Tracks, click the "Frame Horizontal and Value Extents" button at the bottom of the Curve Editor.



This will zoom in the timeline to show all the curves in the animation for the selected dummy node.

You can also click on individual Tracks, such as X Rotation, to show only the curves for that specific Track:



You can move points around on the curve to change the position or rotation of a dummy node at specific times. You can also click the big "Set Keys" button (plus-sign with a key) in the bottom-right corner of the window to add more points to the curve.

This is one way you can accomplish creating custom animations. Another way is using the Move and Rotate tools to transform dummy nodes and setting keys to capture their transformations at specific points on the timeline. That is outside of the scope of this tutorial. It is recommended that you become familiar with the rest of 3ds Max's interface in order to animate in this way.

Exporting the ANIM file
To export a custom animation, first select the platform you are targeting (GameCube or PlayStation2/Xbox) on the BFBB Anim Tools rollout. Then, click the Export button and enter a location you would like to save the file.

If everything goes well, your animation will be exported as an ANIM file. This file can be imported directly into a HOP archive as an ANIM asset, using a tool such as Industrial Park. You must use the Asset Header Editor for this, either on an existing ANIM or a new one.

Note: just like with importing, your animation might not look correct in-game. If this occurs, try checking the "Reverse Bone Order" checkbox before clicking Export.

Using the Animation
If you're importing over an existing animation, this step is not needed as the new animation will replace the previous one. Otherwise, check this page to learn how to make a Simple Object (or any other entity asset, actually) play animations.