Mannequin Overview 3.5

Overview

CryMannequin is a high-level animation system. The main goals of the system are:

Decoupling animation and game logic.
Accurate previewing within the editor, including sound and particle effects.
Animating multiple characters in one place (co-operative animations, weapon reloading, etc).
Sequencing multiple-layer animations (partial-body animations, additive animations, etc).
Selecting animations based on context information.
Providing a framework to sequence additional procedural work (driving IKs, activating rag-dolls, play sound or particle effects, game logic, etc).

The CryMannequin editor builds an animation database which is then queried by the game code whenever an animation is requested. This query process will then select the best match based on additional context information (character stance, health, equipment, etc).

Key Concepts

CryMannequin relies on the following concepts. It is important to understand this naming convention to avoid confusion when using the system.

Fragment: A fragment is an abstraction layer relating to some animation and procedural work. Fragments are associated to a set of tags describing the context requirements. A fragment can sequence multiple animation or procedural layers on several scopes. A fragment could for instance contain one full-body animation, an additive animation played on top of it, some IK processing, some sound or particle effects as well as several gameplay specific events.
Fragment ID: A fragment ID is just a name which is associated to a set of fragments.
Scope: A scope is a part of an animated character. We could for instance have a scope dedicated to full-body animations, another one for upper-body animations, another one for the weapon, another one for slave characters when playing co-operative animations, and so on. Multiple scopes can be edited simultaneously.
Tag: A tag is a selection criteria evaluated when querying a fragment. It refers to some context information (e.g.: injured, in combat, low health, right foot forward, etc.). In game, the tag state is set by the game code and is then processed by the animation database to find the best match.
Options: Multiple fragments can share the same ID and tag state. In this situation, we say that each one of these is a different option. At runtime, the default behavior is to randomly select one of the available options when querying a fragment. Creating multiple options with the same tag state can be useful to implement several variations of the same animation. In specific situations, the game code can also implement its own selection logic to pick the best option based on additional selection criterion (e.g.: picking the best attack animation given a specific tag state based on the distance to the target).

The following screenshot shows where these elements appear within the CryMannequin editor UI.

Creating a new fragment ID

To create a new fragment ID, just click the "New ID..." button and enter the name you wish to create.

Binding scopes to a fragment ID

To bind some scopes to a fragment, first select the fragment ID you wish to update and then click the "Edit ID..." button. In the window that pops-up, you can check the scopes you'd like your fragment to work on. You can also assign a fragment specific tag definition file.

Creating a new fragment

You can create a new fragment from scratch or copy/paste an existing one. To create a new fragment, just select the appropriate Fragment ID in the Fragment Browser window and click the "New" button. To copy an existing fragment, drag and drop with a right click the fragment you'd like to duplicate.

Creating new animation and procedural clips

Animation and procedural clips are sequenced using animation and procedural layers. You can create a new layer by right-clicking on a scope in the Fragment Editor window and the selecting "Add Track". To add a new entry inside a layer, you just need to double-click in the track-view where you want the clip to be created. Selecting a clip lets you then edit its properties.

Working with synchronized combat animations

To create a synchronized combat animation, you first need to make sure that the FullBody and at least one Slave scope are active for the Fragment ID you want to work on. Then, just create one animation layer on each scope and pick the appropriate animation from the list. This will take care of playing both attacker and target animations simultaneously.

To setup the character alignment for the attack, you need to add a "CombatAlignment" procedural clip or edit the existing one. In the properties of this clip you can setup an ideal attack range for the target. The game will then make sure that the target slides in position within this range. The following screenshot shows a typical setup for a synchronized melee attack with character alignment:

The min and max distance to target parameters are used to find out whether character sliding is necessary or not. The "turnAngle" and "selectionWeight" parameters aren't used yet. The "slideDistribution" parameter determines whether the player should slide towards its target (value of 1), whether the target should slide (value of 0), or if both characters should slide (any value in between). 0.5 is a good default value for this setting as it implies that both characters are going to slide equally.

By default, both the attacker and the target are going to spawn at the exact same position in the preview window and then they are going to slide so that the ideal target distance is reached. You can however change the initial target position for preview/debugging purposes by creating a new parameter called "targetStartLoc" on the "Params" track. Make sure that this parameter is located on the first frame of your fragment and use the gizmo in the 3D view to move it around. You can hit "e" and "w" in the 3D view to toggle between the translation and rotation gizmos. The following screenshot shows up the proper setup for this feature:

When using parametric animations for melee attacks, please make sure that all the animations within the same blend-space are indeed blendable (i.e.: they share the same properties, such as number of foot plants). This is crucial as breaking this rule will prevent sound designers to properly setup footstep sound effects and will generate incorrect blended results. Footstep timing does not have to be strictly identical across all the animation clips though: animations can be broken down into individual segments to deal with this type of complex scenarios.