Overview

The engine must know which animation assets a (skeletal) character in the game needs and load these ones.
For this purpose, each character has a "Character Animation List"-File, or short: CAL File.

The CAL File - Character Animation List

What does it do:
The CAL File lists all animation asset filenames that the engine is supposed to load for this character and each asset gets assigned a new ingame name which will be used everywhere in the engine.

Specifying the desired assets inside a designated file instead of bulk loading them for example from a folder structure has certain advantages:

• Only needed assets are actually loaded - no memory wasted
• Assets can be tagged with additional information (Aim Poses)
• Various Characters can easily share the same animation assets, or sub sets of each others animation assets
• InGame Names make it easy to change asset filenames without changing Code or Animation Graph
• Naming Conventions can be enforced

1.1 Creating a new CAL File for a new Character

The CAL File for a character is not automatically created, it must be set up manually to enable this character to play animations ingame. This needs to be done only once per character.

Location of the CAL File:
Each Character has his/her own base CAL file. Since animations are based on the skeleton, this file is located inside the same folder as this character's chr file.
It is automatically loaded upon loading of this skeleton information and has to have the same name as the chr file.

If the name of your character's main skeleton chr is "skeleton_character.chr" you will need to create a text file in the same folder and name it "skeleton_character.cal"

1.2 Setting the Character's Base Animation Folder

To tell the engine where to look for the character's animations, the first line in the CAL File will point the Loader to the correct folder.

All Animations for this character will be inside this folder or in its subfolders. Usually this folder should be placed within the Game/Animations folder.
Animations above this folder cannot be loaded from within this CAL file.

There can only be one filepath command per cal file (but included cal files can set their own filepaths).
The filepath will not affect the location for the AnimEvent or the Tracks Database (see below).

The base folder must be set before the first line that maps an animation to an ingame name.

1.3 Setting up a new Animation in the CAL File

1.3.1 Animations

Add a line to the CAL File for each asset you want to map, and assign it an ingame name.
The syntax is:
Ingame_Name = Path_to_Asset_File

The Path to the file is to be specified relative to the base folder (see above) and the filename must include the extension.
It is not possible to use "\..\" in the path to reach higher folders in the hierarchy.

The CAL File maps caf, lmg and fsq files.

1.3.2 Wildcard Mapping

Line-by-Line adding of each single Animation can lead to very big CAL Files and may take a long time to set up.
It is only necessary if the ingame that is supposed to be assigned to the animation is substantially different than the filename.

If this is not the case, the CAL file supports batch loading of animations inside a folder.
This Wildcard Mapping uses the asterisk * to represent the filename. Using the asterisk in the ingame name will replace it with the part of the actual filename that is wildcarded.

Example:
Test_* = TestFolder\HighJump*.caf
The above line will load all animation from the folder "TestFolder" than start with the words "HighJump" and have the extension ".caf".
These animations will automatically be assigned an ingame name that starts with "Test_" and then follows the part of the filname that comes after "HighJump" (which will be truncated from the name).
A file name HighJump120m.caf would be mapped to Test_120m.

Wildcard Mapping is useful to map entire folders.
It requires however that these folders are kept clean of old and unused assets to not waste memory.

Note:+Wildcard Mapping does +NOT support Locomotion Groups, and wildcard loaded assets cannot be assigned an AimPose.

1.3.3 Aimposes

Aim Poses are automatically started with the fullbody animations they are assigned to (but only executed if Aiming is turned on).
This assignment happens in the CAL File as well.

This is a two step process:

1. Mapping the Aim Poses themselves
2. Assigning them to Fullbody Animations.

Aim Poses are mapped just like any other regular caf file and assigned an ingame name.
They are then assigned to other animations by putting this ingame name in brackets behind the filepath.

AimPoses cannot be assigned to animations loaded via Wildcard mapping.

It is possible to assign two AimPoses to an animation, in which case the Engine will blend from the first AimPose to the second during the course of the animations. This is useful if the animation drastically changes the characters pose (for example in a transition animation).
This is done by separating the start and the destination AimPose name with a comma ',' in the brackets.

1.4 Sharing Assets between Multiple Characters

Often times many NPCs need the same assets loaded. For example all enemy soldiers should use the same Run and Walk Cycles. Each Character has his own CAL File, but to duplicate all the entries in all these files is tedious work and very error prone, as it is difficult to maintain and propagate changes to all files.

Instead the solution is to include other Character Animation List-files inside a character's own CAL File.

This will tell the Engine to parse this CAL file and load all the animations inside in addition to the ones in this CAL File.

Each CAL file can include multiple other CAL files:

For the soldier example:

1. Create a new text file inside Game/Animations/ and name it "SoldiersShared.cal".
2. Open the file you just created and map all animations that all soldiers should share inside it
3. Open each soldier's individual CAL file and add this line:

$Include = game\animations\SoldiersShared.cal

1.5 Setting the Animation Events Database

Animation Events like Footstep Markup and Particle Effects can be set up in the Character Editor. (See documentation on Particle Effects, Sounds and Character Editor for more details on how to do this). These information are stored inside an AnimEvent database. The CAL File of a character must point to the database file which should be used for his animations (usually this is the same database for the entire game so no effects have to be set up multiple times)
A character can only use one Animation Events Database, keep this in mind when including other cal files. If you have very character dependant animation events database, set them in the characters base cal file (which is in the same folder as their chr), otherwise set it in the global cal file and share it among all characters including it.

Here's the line that needs to be added to the CAL File to specify the events database. For more information, please the the documentation on Animation Events (animevents) .

$AnimEventDatabase = animations\human_male\human_male.animevents

1.6 Setting the Animation Tracks Database

the AnimationTracksdatabase is one big file which all animations a character uses can be stored into. It is compressed (without reducing animation quality) and removes the need to ship individual cal files, so animations can not be extracted from the build. Animations inside this dba file will also be loaded automatically, while caf files outside of the file will be loaded on demand when they are used for the first time.
For more information on this, please see the documentation: Animation Events (animevents)