Overview

Having a character aim or look towards a point in the 3d world is a common feature required by many games.

In some simple cases this can be achieved by manually manipulating some specific joints of a character. For example, a simple head look ik system could just grab the head joint and change its orientation after all animation has been processed to point in a certain direction.

With more complex scenarios this might be much trickier to achieve. For example, aiming with a weapon might require the weapon pointing at some specific location, the hands of the character firmly holding the weapon, and the character looking through the scope at all times. In many cases we want to add some flavor or style when the character is aiming. We usually also want to retain as much style as possible from the animations playing underneath to make it look as natural as possible. This involves a bit more effort than simply rotating a single joint.

For the more complex cases of looking and aiming, CRYENGINE provides a parametric directional blending system that allow animators or technical artists to provide a set of sample poses of characters looking and aiming in different directions. At run-time we blend those poses together and put them on top of the currently playing animation so that the character looks or aims towards a point in space requested by the game code, while retaining the style present in the original authored poses as much as possible.

Our current implementation is designed with characters that exhibit a range of motion similar to human characters in mind (eg. it doesn't support continuous 360 degrees aiming around a pivot point, like a mechanical turret would rotate)

Setup

Animation File Setup

The system requires a number of poses of our character aiming in several directions so that it can blend between them to aim in any intermediate direction. It works with 9 or 15 poses.

The poses are exported as an animation file, with a pose per frame. The naming of this file is important. Some part of its name should match the AnimToken provided in the definition.

The order of the poses in the animation is important.

How this could really look for the 9 poses case:

When creating aim or look poses it is common to use an underlying animation pose as starting point (eg. standing idle). The aimposes created from such a starting animation must be applied on top of similar animations.

If the underlying animation currently playing for a character is different enough (eg. crouching) it might be necessary to create aimposes for that specific case to achieve better quality.

Common Pitfalls

Aim and look poses are processed by the Resource Compiler (RC) as part of the animation folder processing step. As a result of this process, the RC writes the DirectionalBlends.img file.

DirectionalBlends.img contains, for all aim and look poses found during processing, the information that the run-time needs to figure out how each of poses need to be blended together so that characters look or aim precisely in the requested directions. This information is calculated from the pose data found in the CAF file and the AimIK and LookIK definitions in the chrparams file.

By default, when running Sandbox or the game, the animation system just loads this preprocessed information from DirectionalBlends.img file instead of recalculating it for each aim or look pose is loaded because this considerably reduces load times.

When working on aim or look pose CAF files, or editing the AimIK or LookIK definition in the chrparams file, we usually do not want to have to recreate this file, since requires that we have all the source animation files locally and it usually takes some time for the RC to process the full animations folder (creating DirectionalBlends.img isn't the only thing it does). In such cases, it's best to disable the loading of DirectionalBlends.img and have the engine recalculate the information it needs during load time, so the local changes can be picked up correctly.

To let the engine know that we do not want to load the DirectionalBlends.img file we must set the ca_useIMG_AIM cvar to 0 before starting Sandbox or the game (eg. in the user.cfg file). Now, when loading an aim or look pose, the information that used to be in DirectionalBlends.img will be recalculated.

Playing Directional Animation

Aim and look poses are applied on top of animation that is already playing on a character. For example, we might have a character playing an idle animation in layer 0, and we want it to aim towards its right.

To play an aim pose or a look pose, we start it as any other animation (by using StartAnimation or StartAnimationById).

CryCharAnimationParams animParams;
animParams.m_nLayerID = ikLayer;
...
skeletonAnim.StartAnimationById(animationId, animParams);

The main particularity that we must observe is to start the animation in the layer where we've told our pose blender we will be placing the aim or look animation during our setup.

IAnimationPoseBlenderDir* pPoseBlenderAim = skeletonPose.GetIPoseBlenderAim();
if (pPoseBlenderAim)
{
  pPoseBlenderAim->SetLayer( ... );
}
IAnimationPoseBlenderDir* pPoseBlenderLook = skeletonPose.GetIPoseBlenderLook();
if (pPoseBlenderLook)
{
  pPoseBlenderLook->SetLayer( ... );
}

To enable or disable:

if (pPoseBlenderAim)
{
  pPoseBlenderAim->SetState( ... );
}

To set the target location:

if (pPoseBlenderAim)
{
  pPoseBlenderAim->SetTarget(targetPositionInWorldSpace);
}

Debugging

General

The ca_UseLookIK and ca_UseAimIK cvars can be used to enable or disable look and aim poses on a global level for debugging.

Character Editor

The easiest way to try if aim or look poses are working properly is to look at them in character editor.

Start a base animation in layer 0.

Start an aimpose animation in layer 14 (must be the same layer specified in the "AimIK Layer" property in character editor).

Enable "AimIK" checkbox in the "Post Processing" section.

Set the ca_DrawAimIKVEGrid cvar to 1

Move the camera around so that the character aims or looks towards the camera.

Game

During gameplay debugging it might be useful to use es_debugAnim EntityName to see the current state of a character in the animation system.

Since it contains information on all animations that are being played, we get information on which aimposes and lookposes are being played in combination of which base animations. This might explain why certain lookposes look broken if the combination does not match for example.

The base layer also displays information on the blend weights and final influences of the look and aim ik, and whether it is being requested by the game or not.