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" defined in the .chrparams.
Character Animation List
What does it do:
The Animation List specifies 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.
Creating a new Character Parameters File for a new Character
The .chrparams 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 .chrparams File:
Each Character has his/her own base .chrparams 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.chrparams"
Setting the Character's Base Animation Folder
To tell the engine where to look for the character's animations, the first line in the .chrparams 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 .chrparams file.
There can only be one filepath command per .chrparams file. But included .chrparams 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.
Setting up a new Animation in the .chrparams File
Add a line to the .chrparams File for each asset you want to map, and assign it an ingame name.
The syntax is:
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 .chrparams File maps caf, lmg and fsq files.
Line-by-Line adding of each single Animation can lead to very big .chrparams 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 .chrparams 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.
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.
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 .chrparams File as well.
This is a two step process:
- Mapping the Aim Poses themselves.
- 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.
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 .chrparams 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 Parameters File inside a character's own .chrparams File.
This will tell the Engine to parse this .chrparams file and load all the animations inside in addition to the ones in this .chrparams File.
Each .chrparams file can include multiple other .chrparams files:
For the soldier example:
- Create a new text file inside
Game\Animationsand name it "SoldiersShared.chrparams".
- Open the file you just created and map all animations that all soldiers should share inside it
- Open each soldier's individual .chrparams file and add this line:
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 .chrparams 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 .chrparams files. If you have very character dependent animation events database, set them in the characters base .chrparams file (which is in the same folder as their chr), otherwise set it in the global .chrparams file and share it among all characters including it.
Here's the line that needs to be added to the .chrparams File to specify the events database. For more information, please see the documentation on Animation Events (animevents).
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 .chrparams 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)
Mapping Facial Assets
You can also map facial expressions library file in a .chrparams file.
This associates an .fxl file with a specific .chr file. Thus, when you load this .chr file in Facial Editor, it will automatically load all the expressions from the specified .fxl file.
You also map facial animation sequence files in a .chrparams file in same fashion as mapping .caf files.