“Animation Replacement and Coding Basics”
By Aavenr

[HTML Version]

 

As you probably already know if you have read Remedy's official "AI Scripting" tutorial, the only way to trigger character animations from within MaxED is by using the custom idle animation slots. Needless to say, whenever you are creating dynamic content for a level you are very likely to need in excess of the 8 default custom normal/wounded covered in the aforementioned tutorial provide, especially when crafting complex cinematic scenes. The game’s database however, contains more that 400 animations defined in the default_skeleton.txt file that could prove to be very useful and I’ll teach how to make use of them or include any custom made one.

Before we move on it is important to explain some Max FX coding basics that concern the whole animation system.

 

Animation blocks

All the game’s animations are defined in blocks along the the ‘default_skeleton.txt’ file. Some of them are more complex that others because they need to send different FSM commands during the animation or as well as setting the character’s movement distance on the level. On this article I will focus on pretty basic custom idle animations which will suffice your needs in most situations. They follow the basic structure highlighted on picture 1.

As you can see, in the ‘index = ’ slot comes the animation’s ID (‘CHARANIM_CUSTOMIDLE2’) which you will have to use when referring to this particular block. Then there’s the actual animation’s filepath (‘anim\idle_aim_beretta.kf2’) which tells the engine exactly what animation file to execute on this particular block. Everything else we leave should leave it as it is as this basic configuration will work well in most of cases. Only if you are looking to create a complex animation that can be triggered from the editor should you mess with the other settings as well as adding animation specific FSM messages.

 

Modifiers

In order to avoid having to write redundant lines of code for every animation for every single character model featured in the game, Remedy implemented a very efficient system that is focused around the ‘default_skeleton.txt’ file (data/database/skeleton/…) which can be considered the base ‘.txt’ file for the whole character animation system. This particular file contains a huge list of more than 400 animations that are defined in separate blocks along with any FSM commands that should be triggered whenever the animation is executed. The ‘default_skeleton.txt’ file affects all the game’s models except the rat model and therefore most of the animations defined on it are the same for all the models.

Different models however, need different specific animations to behave accordingly and logically some technique has to be employed for specializing the character’s animations. This specialization is achieved through what is known as ‘modifiers’. Modifiers are animation blocks placed on a model’s respective ‘skin.txt’ file (data/database/skins/…) with the sole purpose of overriding, or replacing if you will, a certain animation defined in the ‘default_skeleton.txt’ file. They must be placed in the file’s ‘modifiers’ section to work properly.

Basically a modifier works by overriding the original animation block and establishing a new one. It usually has a different filename so it executes a different animation and it can also have different message strings. These changes will only take place for this particular model so whenever the animation is triggered it will perform differently in the model featuring the modifier than on the rest of the other models, which unless they have other modifiers for the same animation themselves, will execute it by the book as defined in the ‘default_skeleton.txt’ file.

For example, the mercenary model needs a particular animation that the other models lack which makes him come down a rope (as seen on the Asgard building levels). On picture 2 you can see how this particular animation modifier looks in the ‘C5_All_Mercenary.txt’ skin file. Remember, you can tell a modifier from an original animation block because the modifier is always placed on a skin.txt and not on the ‘default_skeleton.txt’ file.

 

Animation Modes

All the game’s animations have 4 different versions: ‘one-handed normal’, ‘one-handed wounded’, ’two-handed normal’ and ‘two-handed wounded’. One-handed animations are used when the character has light weapon such as a pistol or a sawn off shotgun that can be hold on a single hand. Two-handed animations are meant to be used with a heavy weapon such as the jackhammer for obvious reasons. Whether a particular weapon will trigger a one-handed or a two-handed animation can be set on the weapon’s ‘.txt’ file (data/database/weapons/…). Similarly, there are ‘wounded’ and ‘normal’ versions for every one-handed and two-handed animation. The wounded animations are set either when the character receives damage, or as it’s the case with the custom idle animations, when you use the ‘C_SetWoundedAnimations(true);’ command in MaxED. Perhaps it may be easier to think of them in terms of animation modes so that for instance, if a character has a heavy weapon the two-handed mode will be activated and only the two-handed animation blocks will be triggered.

It is always important to keep in mind that whenever you switch from one ‘animation mode’ to another the animation slots that you trigger in MaxED might now correspond to another animation because they will now refer to another animation block. Remember there can only be 4 custom animations per mode and when you switch modes, you are switching to another set of animation blocks. You can check if a character is wounded/normal or one-handed/two-handed mode by using the ‘C_dump( );’ command on the console and checking under the ‘X CharacterProperties’ section (you can browse through the console with Ctrl+ up/down)

 

Revert Function

Another important point you should understand is the use of the ‘revert’ function within the script files. You are very likely to find it all the time and it always follows the structure highlighted on picture 3.

What this does is to, as a fellow modder once put it, redirect the code from one place to the other which saves the coder from writing the exact same lines of code twice. The lines of code found on the animation’s block referred in the ‘to’ slot (‘CHARANIM_CROUCH’ on the above example) are copied and applied to the animation in the ‘from’ slot (‘CHARANIM_W_CROUCH’ on the above example) who doesn’t necessarily need to have an animation block. This avoids wasting time writing the exact same code on two animations blocks and is particularly useful because very often ‘normal’ and ‘wounded’ or ‘one handed’ and ‘two handed’ versions of an animation don’t differ enough to need different code (they all play the same animation but still need to be defined in case they are triggered). For instance, in the example above it seems like both animations lack any significant difference and therefore the coder skipped the chore of making an animation block for ‘CHARANIM_W_CROUCH’ and executing a certain animation file and are just reverted it from the ‘CHARANIM_CROUCH’ animation block.

 

Defines

The so called ‘defines’ are constants or fixed values represented by a specific name and which are defined in the script files themselves or in the ‘.h’ files (data/database/…). The former can be referred only on the script file they are defined while the latter can be referred from any script file. These constants are useful because you only need to refer the constant’s name in your scripts and whenever you want that constant’s value changed, you just change it on its define and it affects all the elements in the script file that refer to it. When it comes to the use the animation system, they are mainly used in the ‘EndPosition’ slot. You can find the local defines for the animation blocks at the top of the ‘default_skeleton.txt’ file while the global ones that pertain the animation system are found on the ‘characters.h’ file. An example of the use of the defines can be seen on picture 4.

 

Replacing Custom Animations

When dealing with custom idle animations you can add any animation you want and afterwards be able to trigger it from within MaxED. Usually you will want to use simple animations that don’t require the execution of any message string. Some examples of these are: idle_dj_mixing.kf2, idle_max_listens_through_door.kf2, idle_junkie_dancing.kf2 or Idle_hitting_door.kf2. For them to work properly you will only need to change the animation’s filename (so that it executes a different animation than the original block). However, you also have the option of doing a complex animation with lots of message strings and using the movement/rotation properties. Here are some explanations on what the different settings of the animation block mean:

[Movement]

EndPosition = (X, Y, Z) -> controls how far from the original position (in meters) the character will move along the X, Y and Z axis when the animation is triggered. If you would like the character to move 3 meters forward for instance, you would have to add ‘3’ on the third parameter (they can accept floating point as well as negative values). You can find some predefined distances on the ‘#defines’ at the top of the ‘default_skeleton.txt’ file.

Middleposition1 = ( X, Y, Z); Middleposition2 = ( X, Y, Z); -> they have to do with specific coordinates the animation has to go through, sort of general keyframes. Particularly important for the shootdodge animations.

Rotation = (X,Y, Z) -> rotates the character’s position when doing the animation. Rarely used as this property is mainly set on the animation itself. I recommend only using the Y parameter as the X and Z parameters are not likely to work (why would you need to rotate a character in the X or Z axis?).

[Message]

Frame = X_frame -> sets the FSM message to the triggered at a particular frame of the animation. It is recommended to avoid placing messages on the last frame as may cause errors in some circumstances.

String = “X_RECEIVER->X_FSM_MESSAGE (‘X_PARAMETERS’);”; -> many different messages are triggered in this fashion. Among them you can see projectile creating messages, weapon animation messages, sound and particle effects messages and face texture animation commands. Make sure you add “” at the beginning/end of the string as well as a ‘;’ at the end of the FSM command and the whole string (as shown above).

Make sure you add {} at the beginning/end of the ‘[Properties]’ section.

 

Custom Idle Animations Chart

As I explained previously, there are several variants for every animation used in the game. In order to change the different custom idle animations you will need to refer to them in the in the modifier blocks. There are 8 one handed custom animations (4 wounded, 4 non-wounded) plus another 8 more two handed versions (again, 4 wounded, 4 non-wounded). This makes for a total of 16 different custom animations you can have at any given time for one specific character. Needless to say, you can increase the possibilities by making modifiers for other characters.

To use the wounded/non-wounded animations you will have to switch the character’s state with the ‘C_SetWoundedAnimations( ); command while the possibility of using the one handed/two handed animations depends on the kind of gun the character is using. One nice trick to gain access to the two handed animations without having to equip the character with a heavy weapon (or any weapon at all) is to make a ‘dummy’ (invisible) gun with the same properties as the Colt Commando (or any heavy weapon) that sets the character to a two handed animation state. Then you can equip the character that gun whenever you feel
the need to use the two handed animation slots but want the character to appear unarmed.

Here follows a chart of the custom animations defined in the ‘default_skeleton.txt’ file along with the line number where you can find them:

LINE #	ID NAME [ONE-HANDED NORMAL]	STRUCTURE	SLOT
106	CHARANIM_CUSTOMIDLE1	block	1
112	CHARANIM_CUSTOMIDLE2	block	2
118	CHARANIM_CUSTOMIDLE3	block	3
124	CHARANIM_CUSTOMIDLE4	block	4
LINE #	ID NAME [ONE-HANDED WOUNDED]	STRUCTURE	SLOT #
687	CHARANIM_W_CUSTOMIDLE1	block	1
693	CHARANIM_W_CUSTOMIDLE2	block	2
699	CHARANIM_W_CUSTOMIDLE3	block	3
705	CHARANIM_W_CUSTOMIDLE4	block	4
LINE #	ID NAME [TWO-HANDED NORMAL]	STRUCTURE	SLOT #
826	CHARANIM_W_2_CUSTOMIDLE1	block	1
833	CHARANIM_W_2_CUSTOMIDLE2	block	2
839	CHARANIM_W_2_CUSTOMIDLE3	reverted	3
840	CHARANIM_W_2_CUSTOMIDLE4	reverted	4
LINE #	ID NAME [TWO-HANDED WOUNDED]	STRUCTURE	SLOT #
1101	CHARANIM_W_2_CUSTOMIDLE1	block	1
1103	CHARANIM_W_2_CUSTOMIDLE2	block	2
1109	CHARANIM_W_2_CUSTOMIDLE3	block	3
1110	CHARANIM_W_2_CUSTOMIDLE4	block	4

 

Hands Down Example

I will now do an example of how to add a basic custom animation with the purpose of tying up the all the ends covered in this article. Suppose you are making a cinematic in which you want the Michelle Payne character to go on her knees at a certain point. Here’s how you can do it:

1) Open the the ‘michelle_payne.txt’ file and look for the part where it says ‘[Modifiers]’ after which add the following basic block:

[Animation] Index = ; Filename = ;
[Properties]
{
[Movement] EndPosition = (0,0,0); Rotation = (0,0,0);
}

2) On the ‘Index’ slot write ‘CHARANIM_CUSTOMIDLE1’ so it overrides the original slot 1 of the ‘one- handed normal’ custom animation.

3) Write ‘anim/Custom_TransitCop_on_knees.kf2’ on the ‘Filename’ slot. This animation will make the character go on its knees.

4) In your MaxED level use the ‘C_SetIdle (1, true);’ to trigger the custom animation and force the character to go its knees. Needless to say, make sure the enemy entity has the ‘Michelle_Payne’ model selected on it’s ‘properties’ drop-down menu.

Hopefully you are will now able to achieve broader results when creating dynamic content for the characters as well as a having a better possibility to work your way around the .txt files and know the basics of the MP scripts files. I strongly encourage you too experiment with triggering complex animations from within the editor and to toy around with the default_skeleton.txt file as well as the skin.txt files.

Additional Resources:

Maddieman’s animation tutorial

 

Written by Aavenr on 1/03. Many thanks go to Maddieman who helped me a great deal to understand much of the stuff covered here. If you find some errors/inaccuracies that you want to report, or have some comments/questions about this article please email me at: aavenr@3dactionplanet.com