For a (skeletal) character in the game, there are certain definitions that have to be made in a single unified XML file-structure called a .chrparams file.
These definitions are grouped into 3 Groups: LOD Definitions, IK Definitions, and List of Animations.
Earlier, this information was put into 3 files, namely the *.setup, the *.ik and the *.cal files. In CRYENGINE 3.3 the .cal file, .ik file and .setup file have all been merged into a single more manageable file.
The whole definition is braced by a <Params> </Params> tag. Inside this tag, there are 3 tags embracing the three sections named above.
LOD Definitions <Lod>
For every LOD, a JointList is provided which defines a number of joint names that are available in that LOD:
So the whole section would look like this:
There can be at most one <Lod> block in a chrparams file.
IK Definitions <IK_Definition>
This section defines the joint names that are used for the different IK mechanisms (AimIK, LookIK, LimbIK and Animation Driven IK Targets).
You need to include each different IK definition inside the <IK_Definition> tag.
There can be at most one <IK_Definition> block in a chrparams file.
Aim IK Definition
You can define the joint names required for Aim IK. You can refer to this document to learn how to create your aim poses.
Primary is just needed to get the fastest through the hierarchy to the end bone (weapon_bone).
Additive is to specify if it will take motion from below or not.
If you are using a different name for the weapon bone, make sure you replace all instances of weapon_bone with your custom name here!
There can be at most one <AimIK_Definition> block within an <IK_Definition>. Within an <AimIK_Definition> there can be at most one of each of the following blocks: DirectionBlends, PositionList, RotationList, ProcAdjustments.
Limb IK Definition
For Limb IK, you can specify the joint names here. Please check this document for more information on Limb IK.
You can choose your type of solver - if it's a two bone IK chain (2BIK), specify the root bone and the end effector. Also, you can define the handle of your IK.
This handle name is referred later when accessing the IK through flowgraph or code.
There can be at most one <LimbIK_Definition> block within an <IK_Definition>.
Look IK Definition
For Look IK, you can specify the eye attachment names, the animation token used and the joints influenced. Please check this document for more information on how to setup the animation assets for Look IK.
There can be at most one <LookIK_Definition> block within an <IK_Definition>. Within a <LookIK_Definition> there can be at most one of each of the following blocks: LEyeAttachment, REyeAttachment, DirectionBlends, PositionList, RotationList.
Weapon Recoil Definition
Here you can specify the IK handles used, the weapon joint influenced and the impact joints with delay and weight in the Recoil Definition.
There can be at most one <Recoil_Definition> block within an <IK_Definition>.
Feet Lock Definition
There can be at most one <FeetLock_Definition> block within an <IK_Definition>.
Animation Driven IK Targets
Animation Driven IK Targets are defined inside the <Animation_Driven_IK_Targets> </Animation_Driven_IK_Targets> tag.
You can specify the IK handle used defined in the the Limb IK Definition, the IK Target bones and the blend bones.
The Target bones are the goal the IK system in the engine uses to reach the limb to.
The Blend bones are used for defining how much the target should get reached. The system takes the local (parent space) X-axis distance from the parent as weight.
- 0cm distance = 0% weight
- 100cm distance = 100% weight
The length always gets clamped to 0cm-100cm so if you go over 100cm, it will stay at 100%.
If you work with additives, have the IK already 100% activated in a lower layer and want to remove using IK (might be needed for reload animations), you need to generate a negative weight: 1. frame = 0cm distance; 2. frame = -100cm distance. This will generate a negative weight and will deactivate the IK.
The recommendation is to always have IK on and the moment you want to do something else with the hand than grabbing onto the weapon, you animate the IKTarget instead. This prevents interpolation issues when blending IK out and in.
There is nothing hard-coded in the engine which might prevent a change of bone names, so whenever you setup a character, you can name the bones however you want as long as you update your .chrparams file with the different names.
For detailed information on IK Limb Retargeting, please refer to this document.
There can be at most one <Animation_Driven_IK_Targets> block within an <IK_Definition>.
By default the bounding box of the character is based on all the joints of the character. However, you can include the optional <BBoxIncludeList> section and specify exactly which joints you want to take the bounding box of.
- the minimum size of the bounding box is 5cm x 5cm x 5cm.
- attachments are included in the bounding box (unless the code flags them with FLAGS_ATTACH_NO_BBOX_INFLUENCE)
To extend the bounding box, you can use the optional <BBoxExtension> section.
In the example above the bounding box is extended by 30cm in the negative x direction, 20cm in the negative y direction, and so on.
- You don't need to stick to the Biped naming convention but there are some hard coded things that won't work if you do change to your own naming convention. Currently for Ground Alignment, you need Biped naming convention for the legs and feet. And for Mirroring Animations, you need Biped naming convention.
- The engine does include CCD IK implementations for more bones. If you modify the groundalignment code to support more bones, and make a call to one of these CCD Solvers instead of the regular Solver, you can have the Groundalignment work for your characters that have more than the default number of bones. This will involve some code changes. Also, it might suffer from joints bending in the wrong direction, as can happen with CCD IK.
Character Animation Lists <AnimationList>
The character animation lists are now also included in the *.chrparams file structure, in the <AnimationList> tag. For detailed information, please refer to the Mapping Animation Assets document.
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.
The <AnimationList> section covers all functionality of a CAL file, but now everything is encapsulated into XML syntax.
An animation alias is assigned to an animation file using
Animation Event Databases are defined by:
Other .chrparams files with an <AnimationList> section are included using the tag:
Only the animlist section of this included chrparams will be read. Other sections will be ignored. Included animlists can include chrparams themselves.
Tracked DBAs can be defined as before, with the $TracksDatabase directive:
A new feature here is that flags can be applied to $TracksDatabase definitions. The only available flag right now is "persistent" which means that the dba should stay in memory after it is loaded.
The #Filepath is used to move the next animation links local to its path:
And as before, wildcards are also supported with an addition of including subfolders:
There can only be a single <AnimationList> block within a chrparams file.
Creating .chrparams file using Python Script
If switching from an older CRYENGINE build to the latest CRYENGINE 3.3 or higher, you need to setup .chrparams file for all of your characters. Otherwise, your animations and IK won't work in the latest build.
You can use our python script to create .chrparams file from existing .setup, .ik and .cal files. The convert_to_chrparams.py file is available in your latest build's Tools folder.
- Install latest Python and place the convert_to_chrparams.py file in the Game folder.
- Double click the .py file to execute the Python script as it goes through all the folders inside the Game folder to look for the .setup, .ik and .cal files and create a merged .chrparams file.