CryMannequin Editor Guide

This article refers to Mannequin tools in early CRYENGINE 3.5 versions. For later versions, please see the other Mannequin documentation sections. For example, for CRYENGINE 3.6, this tutorial can be found here: Part 1, Part 2, Part 3.

Overview

This article will guide you through all the major parts of the CryMannequin interface. It uses samples that are part of the SDK. Feel free to follow along with the step by step instructions.

The tutorial will use a lot of pictures and a simple color code to distinguish areas to interact with and areas to look at:

Loading the Preview File

Open up the CryMannequin Editor from the View menu:

Next load up the preview file for the first tutorial, it is called "sdk_tutorial1preview.xml"

The preview file sets a character similar to how this is done in the game, but now the character is fully inside this editor.

This is how the editor will look now, though you might need to resize the window a bit to make it fit the image below:

Notice there are two main areas in the editor:

  • Left area: This can show either Fragments, Sequences or Transitions. Click on the tabs at the bottom of this area to show those different panels. We will explain later what they mean.
  • Right area: This can show either the Fragment Editor, the Previewer or the Error Report panel. Again, you can already click through these to get a feeling for how they look. And again, we will explain later what they are for.
Tip: Set the Default Preview File

You can configure the default Preview File that is opened when you open the Mannequin Editor in the general preferences panel.

Creating and Editing FragmentIDs

When the game wants to play an animation it will never request the animation file directly. The game will always request it through another name which we call a FragmentID. In this tutorial we start the setup from scratch so no FragmentIDs have been set up yet. Let's create one.

  1. We do this in the Fragments Panel (sometimes also called the Fragment Browser), so make sure you have this panel open by clicking the Fragments tab on the bottom left.
  2. Press the "New ID..." button to start creating a new FragmentID.

Next we need to enter a name. For this tutorial we pick the name "Idle":

In a real production scenario there might already be lots of FragmentIDs defined and you won't need to create them yourself anymore. Your technical colleagues will inform you whether you need to create FragmentIDs yourself or not and which naming convention to use.

Now the FragmentID Editor will open up. Most of the settings are already correct in here:

  1. Select "FullBody" as the default scope.

    If you forget to select a scope the fragment will not work in the editor - we might change the default setting of this tool in the future to prevent these kinds of mistakes

  2. Press OK

In this simple tutorial we have only one of these "scopes", but in a real example your character will likely contain many different ones. Each of these can represent a different 'part' of the mannequin character. It could even be an attachment like a weapon you want to animate alongside the main skeleton. Which ones you need to select will depend heavily on the case and whoever set up the character will give you this information. Here is an example how this can look like from the SDK example:

You will now notice that there is a new item in the Fragment Browser called Idle.

You can always access the editor you just closed again using the Edit Id... button (you can open and close it now to try it out).
And next to it is the "Delete Id..." button to delete a FragmentID (including all fragments inside it, though in this tutorial we didn't add any yet).

Creating and Editing Fragments

A FragmentID alone isn't much use if it doesn't refer to your animations somehow. And this is where Fragments come into play. A fragment is a small sequence of animations; let's create some to get a feeling for what we mean by that and how it ties into this FragmentID.

Creating a Fragment Using Drag and Drop

There are many ways to create fragments, but possibly the simplest is just dragging an animation on a FragmentID.
First let's find the animation we want to refer to in the Character Editor.

Keep the CryMannequin Editor opened.

Open Character Editor by clicking the icon for it on the main toolbar:

Now we look for the animation.

  1. Make sure you have objects/characters/human/sdk_player/sdk_player.cdf open (if not, open it through File/Open...)
  2. If you want you can use the Filter to filter down the list of animations. In this example we just type 'idle'
  3. Look for 'stand_tac_idle_rifle_3p_01' (in the "stand" folder, the folders here correspond to the animation name prefixes)

Next drag and drop this animation onto the Idle FragmentID we just created.

The result will be:

  1. We created a new fragment that shows up as 'option 1' in the Fragment Browser. The elements in the fragment browser with the movie icons in front of them are the Fragments. It is placed in the '<default>' subfolder of the FragmentID. This basically means that this fragment is the default option for this FragmentID: whenever the game requests Idle the system will play this fragment. We will create more options, more variations, later.
  2. The fragment is automatically opened up in one of the panels on the right side: the CryMannequin Editor
  3. We see that there is an animlayer (animation layer) inside the FullBody scope – indeed this is the scope we selected as default scope when we created the Idle FragmentID before.
  4. The animation clip we dragged in is placed on the timeline for this layer.

Playback Control

Here is a quick overview of how you can review the fragment's animation:

  1. Press here to play/pause the fragment, as well as change the playback speed by clicking on the little downwards pointing arrow.
  2. Scrub by dragging/moving the pink marker using the left mouse button. With the right mouse button you can define the playback range by dragging two red triangles around on the timeline.
  3. Press here to enable looping playback (the loop will be over the playback range you selected in 2).
  4. Press here to toggle the time display from seconds to frames (30 fps) and back.

Adding more clips to a Fragment

Now we can make this fragment more complicated if we wanted to. For example let's drag another animation clip into the fragment:

Your timeline now looks like this, and you notice the animation clip got added:

Clip Zones

You can identify the following zones on the timeline now:

  1. Blend-in period of the first clip (this is currently ignored and might seem useless, but it will be used when you start to sequence this fragment after another fragment).
  2. The period where the first clip is playing fully.
  3. This is after the first clip has finished, but it will repeat its last key by default.
  4. Blend-in period of the second clip. This is where the transition happens between the repeating last key from the first clip and the second clip.
  5. The period where the second clip is playing fully.

Feel free to play around and dragging these clips around on the timeline and seeing how this looks when playing back the resulting animation.

Typically you'd want the second clip to be nicely aligned to the end of the first clip so you don't see any repeating frames. You might also want to increase or decrease the blend-in time. You can do that by dragging the vertical bars marked below:

Creating a Fragment Without Drag and Drop

As remarked above this was just one of the simplest ways of adding fragments. There is also a way that doesn't use drag and drop at all which is good to know about. Let's add another fragment to try this out.

Press the New button in the Fragment Browser to add a new fragment under the currently selected FragmentID:

Notice that the new fragment you just created automatically became another default option for the Idle FragmentID:

This means that whenever the game requests to play Idle, it will now randomly pick one of the two options we have.

The new fragment is also automatically selected into the Fragment Editor (it's a bit hard to see but note that the currently previewed fragment is the one in boldface; you can change the currently previewed fragment by double clicking on a fragment).

Now contrary to above this new fragment will be completely empty. It will not even have an animlayer:

But we can now add an animlayer in the Fullbody scope manually from the right click menu:

Now we have an animlayer we can add an animation clip to it by double clicking on the layer's timeline:

But we're not there yet, now we have a clip but it's empty, which is called a 'None' clip. To add an animation we need to have it selected and then we can set an animation in its properties to the right:

An animation browser window will open and you can now select an animation by double clicking on it:

Animation Clip Properties

Now might be a good time to experiment with the other properties of animation clips. One of the most important ones is the 'looping' property. Check it to make the animation clip looping forever:

Note how the clip now takes up the whole timeline and vertical markings appear to show where the animation loops.

Here is a list of the other properties available:

Animation Clip Property

Description

Animation

The animation played by the clip. Empty for 'None' clips.

Playback Weight

With this value between 0 and 1 you can control how much of the clip is blended onto the previous layers.

Start Time

Time (in seconds) to skip at the beginning of the animation.

Looping

Whether or not this clip will loop (as opposed to repeating the last key).

Time Warping

(Advanced) Enable time warping during the blend-in. Maps to low level animation flag CA_TRANSITION_TIMEWARPING.

Idle2Move

<deprecated - use mannequin transitions instead> Maps to low level animation flag CA_IDLE2MOVE.

Blend

Blend-in duration (can also be edited visually by dragging the narrow vertical mark at the left of the clip).

Use Joint Masking

<prototype - do not use>

Align to Previous

Adding Multiple Layers

Now we can also show how to add multiple layers of animation within one fragment. Add another layer by using the same right click menu item as before:

The number of layers you can add might be limited. In this case you can create 3 layers within the FullBody scope (this is configurable by the person maintaining the scopes).

In these new layers you can put additive or override animations to add extra variation on top of the base layer's animation. Try to recreate something like the following for example. Note how the 'None' on the second layer is used to stop the looping 'melee' clip:

Procedural Clips

Next to animation we can also sequence 'procedural' clips in a fragment. These can do anything from control alignment or aiming to playing sound. New types can be added easily by programmers when needed.

You cannot just put those procedural clips on animlayers though; you need to create a proclayer (procedural layer) as follows:

Now you can add a procedural clip to the newly created layer by double clicking (just like you did to create an animation clip above)

A "None" proceduralclip gets added. Now you can edit its properties and make it do something useful, for example play a sound:

And as before you can add "None" clip to stop a procedural clip. The procedural clip code can, if it wants to, use the blend-in and blend-out time (blend-out time is given by the length of the "None" clip).

Here is how it might look if you stop the sound playing with a None clip:

Moving Clips & Snapping

Clicking and dragging on a key allows you to move it along the timeline.

Attached keys on other tracks will move to the keys new position, or update when you stop moving the key for a short period of time.

However the default dragging behavior is to snap to the beginning, end or blend time of keys on other tracks (see the Clip Zones). Sometimes you might want to snap it to a specific time-step on the timeline, or to completely disable the snapping behavior.

To snap the key to a time step marker begin dragging the key as usual and then hold down the "Shift" key, this will now clip to the timeline markers and ignore the other keys.

Be aware that "Dragging+Shift" is different to "Shift+Dragging" which will clone a key.

To completely disable snapping behavior begin dragging and then hold down the "Ctrl" key. The key can now be dragged to any point on the timeline without snapping either to other keys or the timeline allowing for much finer adjustments.

Copying a Fragment

To copy a fragment, drag and drop the fragment using the right mouse button.

Deleting a Fragment

To delete a fragment, for example the one you just created by copying, use the Delete button while you have the fragment selected.

In the screenshot above note the difference between the selected item (Option 3) and the boldface item which is the one currently displayed in the Fragment Editor (Option 1). Pressing Delete will delete the selected item, Option 3. In any case the action will ask for a confirmation so you can check the name before deleting.

File Manager: Saving & Perforce Integration

At any time you can save your changes with the Save Changes menu item:

This will open up the Mannequin File Manager.

Here it lists all the files which were modified. You will notice that the changes you did affected more than one file and pressing Save would save all of them.

If you don't want to save a certain file you can select that file in question and press Undo Changes to Selected Files.

To be more correct: the file manager lists all files that look different in memory than on disk. So for example if somebody manually edits one of the CryMannequin files (which is strongly discouraged though!) it is possible that the file will suddenly show up in the file manager. This can be very confusing but it also helps to detect subtle editing errors. Simply save the file again when this happens. This also means that, whenever you manually edit a mannequin file - maybe you merged the file in a version control system? - you have to open up the mannequin editor and load a preview file that uses it to verify your edit. Save without changing anything. If the file you edited shows up simply overwrite it.

If you have the Perforce plugin installed there is some (limited) Perforce integration.

  1. Read-only files are marked with a lock icon.
  2. You can check files out inside the file manager when needed. You are only allowed to save when all files are writable.
  3. Press refresh to update the file status (for example when you manually removed the read-only flag from a file).

If you forget to save before closing the editor or when files change on disk outside of the editor you will still be reminded and the file manager will pop up.

Tags

Assigning Tags to Fragments

Load up the preview file for the second tutorial, it is called "sdk_tutorial2preview.xml". See Loading the Preview File (but this time the file is called "sdk_tutorial2preview.xml").

If the file manager pops up you can press "Undo Changes to Selected Files" to ignore your previous changes.

You will notice that this time we create 2 fragments (one under the FragmentID "Idle" and one under the FragmentID "Moving").

The bit under the fragment browser now displays something new: you can now assign what are called Tags to the fragments. What does this mean? In the previous tutorial we just made a couple of variations for a FragmentID. When the game requests that FragmentID, which fragment plays is basically randomly chosen from those variations. Now we can start adding "tags" to the fragment to limit the cases in which certain fragments get picked. For example, we can mark a fragment with the tag "tired" so it only gets selected when the character is "tired". Or we can mark certain fragments with either "kneeling" or "standing" so we can create different stance variations for the same animation.

Let's try this last example now. Currently the fragment inside "Idle" has an animation where the character is standing. Let's make a variation that is kneeling. The simplest way to do this is by first copying the old fragment using right-mouse-button drag-and-drop:

Next we modify the animation in this fragment to point to the kneel_tac_idle_01 animation:
For example like this:

  1. Select option 2 (should already be selected).
  2. Select the animation clip (should already be selected).
  3. Open up the animation browser.
  4. Optionally use a filter.
  5. Find the animation in the kneel section.
  6. Select the animation into the clip by double-clicking.

Now we tag this fragment with the tag "kneeling".

First make sure you have the fragment selected in boldface (just selected is not enough, it also has to be selected into the fragment editor - you can do this by double-clicking).

Next select "kneeling" from the "stance" combobox:

Note how this change affects the fragment browser. What used to be "option 2" in the "default" section now became "option 1" in the "kneeling" section.

Now whenever the game requests "Idle" with tag "kneeling", it will get the new fragment. But if the game requests "Idle" with tag "standing" instead, it will take the default option.

Why do you need these "<default>" options? If we know the only options are "standing" and "kneeling", can't we simply tag that other fragment as "standing" and get rid of the default option? It's a matter of style but it might be a good idea to have some kind of "default" to fall back to. For example whenever a new stance gets added it's useful to have some good fallback behavior. If the system cannot find a matching fragment you might get T-poses. It depends on your production philosophy whether you want to enforce T-poses for missing fragments (which forces bugs to be found) or want to "sweep it under the carpet" with a default option and only fix it up when needed.

We call "stance" a Tag Group. Some tags are inside tag groups, some other tags, like "tired", are not. Putting tags in a group like that makes it only possible to select one of the options in the group at the same time.

So you cannot be both "standing" and "kneeling" at the same time in this setup, but you can be both "kneeling" and "tired". Let's see what happens when we do that, let's also select "tired":

And this is how this shows up in the fragment browser:

Our fragment now became an option within "tired", and that sits within "kneeling" (this gives you a hint that "kneeling" is in some sense more important than "tired", which is the case, "kneeling" has higher priority than "tired" in this setup).

If you find the folders for the tags confusing and just want to see the whole list of fragments you can use the "Sub Folders" checkbox:

Note how our fragment with the tags "kneeling" and "tired" now shows up as "kneeling+tired".

The order in which the fragments are listed reflects the order in which they get selected. If there are multiple equivalent matches the first one in the list that matches gets chosen. For example, say there is a tag called "tired" and a tag called "scared". You have one fragment that is tagged "tired", and another fragment is tagged "scared". Now the game looks for a fragment for a character that is both "tired" and "scared". If "tired" and "scared" have the same priority it's pretty much undefined which fragment will get chosen (it's currently related to the order in which they are defined), but the editor will show you the fragments in the selection order. Fragments that are first in the list get selected first.

Selecting the empty option within the tag group "Stance" means "I do not care which stance it is for, it's a default, a fallback". Similarly, leaving the "tired" tag unchecked means "I do not care whether or not you are tired". It specifically does not mean "not tired". If you want to be able to specify fragments specifically for a "not tired" state you need to add a new tag for this "not tired" state.

Editing Tag Definitions

Though we will not explain this in this tutorial, you can edit the tags in the Tag Definition Editor which can be found in the File menu:

Previewing Sequences

What are Preview Sequences

Up until now we just worked on little 'fragments' of your game's animation (literally). These will be sequenced together by the game code, but the CryMannequin editor also provides a way to preview how this sequencing would look even without running the game. Actually the previewer sequences are not used in the game at all! This is useful for all kinds of things:

  • Working out 'what if' scenarios. e.g. "How would it look if the game would request the Move after Idle while kneeling?".
  • Analyzing Bugs: You can record a real sequence from the game and load it up in the previewer. Or you can set up a sequence yourself to mimic what the game code does and see if it works outside of the game.
  • Testing: Setting up little test scenarios and reloading them later on to see if they still work.
  • Editing transitions: currently editing transitions is also done in the Previewer (see #Transitions).

Creating a preview sequence

To try out and preview how your fragments will look in the game the editor has the Previewer. You can find this one as a tab on the right side of the CryMannequin editor, please select it:

This is how it will look:

Note that it looks quite similar to the Fragment Editor we worked in before. But there are a couple of details that give it away (apart from the tab at the bottom that says "Previewer").

Instead of the name of the fragment on a yellow background it now simply says "Preview" and instead of having animation & procedural layers we now have a track labeled "FragmentID".

Let's see if we can set up a little sequence where we play our default "Idle" followed by our default "Move".

To do this we drag both fragments onto the FragmentID track:

  1. Drag the default "Idle" fragment onto the beginning of the FragmentID track.
  2. Drag the default "Move" fragment a bit further on the FragmentID track.

A lot happened automatically while you were dragging, let's explain what happened:

  1. You added "Idle" and "Move" on the FragmentID track. This mimics what the game does to play animation: it just requests "Idle" and then "Move". The previewer mimics the selection process, and as we are not requesting any specific tags (we'll do that later) it just picks the default fragments for both FragmentIDs. This shows up in a slightly cryptic way as "<default> - 0". The 0 means it's the first option.
  2. The system shows which actual animation clips those fragments translate into and shows that on an animation layer.
  3. When we dropped the fragments this also created two dots (keys) on the TagState track. What they mean should become clear in the next step...

Now let's drag the special fragment that has both kneeling and tired tags onto the track too:

The fragment appears, and notice:

  1. The fragment is now labeled "kneeling+tired - 0", as we would expect.
  2. The TagState track now contains a key that is labeled "kneeling+tired". This mimics the fact that the game has to somehow request those tags too, along with the FragmentID.

Option Index

If you select a fragmentID key you can change the option index (OptionIdx) in case you want to select a different option:

Here we have OptionIdx = 1, so the first option is selected. And as noted before this shows up as "0" on the FragmentID key.

If you set OptionIdx = 0 the system will pick an option randomly and the FragmentID key will not display a number at all.

If you use an option index which is higher than the number of options it is divided by the number of options and the remainder determines the actual option. For example if you have 3 options and you set OptionIdx=5, option 2 gets chosen.

In case you are wondering, we'll talk about the "trump previous fragment" option in a later section.

TagState Keys

Let's play a bit with this TagState to get a feeling of how it works.

  1. Select this key .
  2. Toggle the "tired" tag off.

The result is:

  1. The key is now called simply "kneeling" (that is the only tag that is still set inside the key).
  2. The fragment that is selected is now the default one again, "<default> - 0". This fragment now is the 'best match' for the game's request.

Let's play some more. Turn the "tired" tag back on inside that key:

Move the key a bit to the right:

This simulates a situation in which the game requests those tags ("kneeling+tired") after requesting the FragmentID "Idle". This means that at the moment "Idle" is requested the tags are not set, and the default fragment will be chosen:

It is very important to keep this in mind when you start dragging the keys around on the FragmentID or TagState track. The order in which requests come into the system has an influence on which fragments get selected eventually. For example if you want to move a certain fragment around, you need to select both the FragmentID and the TagState key above it (to select both at the same time you can use regular multi-selection: drag a box around both with the left mouse button or use CTRL+left mouse click to select more objects while keeping the old ones selected).

This is not part of the tutorial, but instead of using drag-and-drop you can also create keys on FragmentID or TagState tracks manually. Use double-click on a track to create empty keys, and fill in the properties of the key on the right.

You can delete keys by pressing DEL (or picking "Delete" from the right-click menu) while the key is selected. Delete both the TagState key we were playing with and the corresponding FragmentID:

Undocking the Previewer

If you want you can pull out the Previewer from the mannequin editor and put it alongside the rest of the editor. This makes it possible to work on individual fragments and see immediately how this would change the sequence.

You can also dock the previewer somewhere else if you want to. For example here is the Previewer alongside the Fragment Editor:

Saving & Loading Preview Sequences

You can save the sequence we just set up using the "Previewer/Save Sequence..." menu item. Give it a nice name and save it, for example name it "my test sequence".

To load a sequence you can use the "Previewer/Load Sequence..." menu item or even easier: just open it from the Sequences tab on the left side.

  1. Select the Sequences tab.
  2. Double-click the folder icon to open the folder (the sequence you saved before should now show up).
  3. Double-click your sequence to load it (or select it and press the Open button below).

Default TagState

Describing the tagstate in detail while setting up a preview sequence with tagstate keys can get tedious. The drag and drop helps in setting up those keys, but there are cases where you just want the same tags to be set all the time. Or you'd like to set up a generic sequence and want to see how the sequence would look under different circumstances. For example you might want to set up a basic motion sequence like "Idle -> Move -> Idle" both for "standing" and "kneeling". Maintaining all those different sequences can get annoying when the number of stances gets higher and higher. It's easier if you could set up a generic sequence and then fill in the stance tag afterwards. This is where the Default TagState comes into play.

At this point you might have noticed that that there are 3 areas in the editor which look very similar. But don't let this confuse you, they all have different meanings! Two of them we already talked about, the third one is this Default TagState. Refer to the picture below:

  1. These are the tags associated with the Fragment we are currently editing (the boldface fragment in the Fragment Browser). See the section on Assigning Tags to Fragments.
  2. These are the tags set in a TagState key which we put on the TagState track in the Previewer. See the section on TagState Keys.
  3. This is the Default TagState.

Let's play with it. Let's select both "kneeling" and "tired" in it:

Now note how this change in the default tagstate changes the sequence in the previewer.

  1. Even though the first TagState key is set up to be empty, it is labeled "{}"...
  2. ...the kneeling+tired fragment gets selected.

What we did now is add "kneeling" and "tired" to the default TagState. So the tags that are set by default for the whole sequence are "kneeling" and "tired".

The TagState keys still override the default tags though. Say you have "standing" selected in the default tagstate you can still override it with a "kneeling" TagState Key. An empty tagstate key, in other words a key that is labeled "{}", overrides nothing at all.

Params Track

Work in progress

The game can set certain 'parameters' that get picked up by the clips.

By adding keys on the params track you can control these parameters in the previewer.

Parameters have names (eg. 'TargetPos')

Which parameters and how they are used depends on the specific clips.

For example a 'positioning' clip takes a parameter that is a location&orientation in space to slide towards.

Fill in the name needed by the procedural clip or game. For the procedural alignment clips (all the PositionAdjustXXX clips) this parameter name must be "TargetPos" as in the screenshot above.

Select the "Locator" option for the gizmo to appear.

Use the buttons on the toolbar below, or they keys "W" or "E", to select translation or rotation mode for the gizmo.

New Sequence

If you would like to clear a sequence you can use the "New Sequence..." menu item:

Trumping

There is a certain complication which we carefully avoided until now. When the game requests FragmentIDs, it is not guaranteed that the new fragment will immediately start. It is possible that the default transition between the previous fragment and the new fragment will delay the selection of the fragment. For example to finish an animation, or to wait until the correct foot is on the ground. In some cases this is fine, in other cases you really want to play the new fragment immediately. And this is what we call Trumping: basically just skipping the waiting period.

This can be simulated in the previewer too. Let's set up a little scenario where this happens.

Open the Idle (kneeling+tired) fragment up in the fragment editor.

  1. Just in case: Double check the fragmentID...
  2. ...and make sure you have the correct variation, kneeling+tired, selected.
  3. Select the first animation clip and uncheck the Looping setting.

Now go back to the previewer and look at a simple sequence (if you lost your sequence just drag the "Idle (Kneeling+Tired)" and "Moving" fragments into the previewer again as before.

You might need to move the "Move" FragmentID key a bit to get exactly what is shown in the screenshot below, but you should notice that now the move animation is delayed!

This means that the new animation only starts after the previous one has ended. This is the default behavior for non-looping fragments. Up til now we didn't set up sequences with non-looping fragments so it simply didn't show up yet.

It also means that this is the default behavior in the game. Whenever the game wants to skip this waiting period it sets things up in order to "trump". We can simulate this by:

  1. Selecting the Move fragmentID key.
  2. Checking the "Trump Previous Fragment" option.

The result is the following, where the animation starts immediately:

Transitions

Load up the preview file for the third tutorial, it is called "sdk_tutorial3preview.xml". See Loading the Preview File (but this time the file is called "sdk_tutorial3preview.xml"). If the file manager pops up you can press "Undo Changes to Selected Files" to ignore your previous changes.

Tutorial3 picks up from the end of tutorial2: you will notice that a small number of fragments with tags are already created for you.

We will now show how to set up a Transition between different fragments and where to find these transitions.

At any time in the tutorial feel free to play the current sequence using the playback controls.

Creating a New Transition (from the Transition Picker)

In this example we will create a special transition between the "Idle (standing)" and "Idle (kneeling)" fragments. Without the transition the character just snaps between the two fragments (using the default blend-in time which you specified at the beginning of the "Idle (kneeling)" fragment).

  1. Select the Transitions panel from the left side of the CryMannequin editor.
  2. Notice that there are no transitions yet.
  3. Press the New button.

Now we need to select the fragments & tags in between which we want to create a transition.

  1. Select the "Idle" FragmentID in the From field.
  2. Select the "standing" tag for the 'from' stance field.
  3. Select the "Idle" FragmentID in the To field.
  4. Select the "kneeling" tag for the 'to' stance field.
  5. Leave the tired tag unchecked, as we do not care about it.

You can create a more general transition by leaving fields blank. For example say you'd like a transition from Idle (kneeling) to any other fragment, you would leave the "To" FragmentID field blank. Similarly, if you keep all tags unchecked it means you don't care about which tags are set.

Opening a Transition

Next let us preview how this transition looks now. The transition we just created can be found by:

  1. Opening up the Idle to Idle folder.
  2. Opening up the standing to kneeling folder inside it.
  3. Selecting the entry in there.
  4. Pressing Open (or you could just as well doubleclick on the entry in step 3).

Now the Transition Picker pops open. This is a step we have to go through before the transition gets shown in the previewer. We need to tell the system which fragments we want to show as "From" and "To" fragments.

  1. In this simple example we created a specific transition, from a specific fragment to another specific fragment, which makes this step pretty much unnecessary. All the necessary fields are already filled in. In more advanced examples you might have set up a more general transition, for example from "Move" to Anything. But the previewer is unable to preview a general transition like that, you have to make it more specific. In that case you need to choose which fragment you want to use as a more specific example for the "To" field.
  2. Select OK.

The transition we just created now shows up in the previewer.

  1. A sequence is set up automatically that first starts the "Idle (standing)" fragment (which we picked in the transition picker before)...
  2. ...and that then starts "Idle (kneeling).
  3. An orange box appears on the FragmentID track that shows you the 'transition' region. By default it just uses the blend-in time we set up in the "Idle (kneeling)" fragment.

Changing a Transition

To get a better idea where this default transition time comes from let's open up the "Idle (kneeling)" fragment in the fragment editor by right-clicking on it to open up the context menu and then selecting "Edit Fragment".

  1. This automatically opens up the selected fragment inside the Fragment Editor.
  2. As before, the name of the FragmentID is displayed in the yellow area.
  3. The default blend-in time is specified by this area.
  4. Which is also specified here in the properties of this animation clip.

Now by making a transition we can override this default, which is why we created this specific transition in the first place.

  1. Let's go back to the previewer.
  2. Make the transition period bigger by dragging vertical divider to the right:

What did we do now? By dragging this divider we override the default blend-time which we saw above (if you flip to the Fragment Editor at this very moment you will see that the blend-in time in the actual fragment is still the big one we set up before). So whenever the game requests this specific sequence of fragments the new blend-in time we just specified will be used instead.

Let's now try to use a specific transition animation instead of a pure blend. We need to insert this animation somewhere after the beginning of the transition period (as doing something special before the transition even started does not make sense) - so we first need to move the second animation a bit to the right to make space for the transition animation.

Drag the second clip to the right:

Double-click somewhere after the beginning of the orange Idle->Idle block to create a "None" animation clip:

  1. Select the None clip

    The clip is not automatically selected, but the property view unfortunately still seems to be updated, so you might be editing nothing if you forget this step...

  2. Start selecting an animation for this new clip.
  3. Type to_kn in the filter as we happen to know this is part of the name.
  4. Open up the "stand" section.
  5. Double-click on the stand_tac_to_kneel_01 animation to select it into the animation clip.

Now move the second clip and its blend-in time around until you get something like this, where the blend-in of the second clip overlaps with the end of the transition clip.

Congratulations, you set up your first transition!

Creating a New Transition (from the Previewer)

There is another way to create transitions which is good to know about: you can create them directly from Previewer, you don't need to go to the Transition Picker.

Let's use this other method to set up the transition to stand up again from kneeling pose.

First we drag the "Idle (standing)" fragment onto the previewer, somewhere in the "Idle (kneeling)" area:

Then:

  1. Right-click on the newly added key.
  2. Select "Insert Transition".

A Create Transition window pops up. It will automatically fill in parameters to create a transition from the previous fragment to the currently selected one. In our case the automatically created settings are fine, so we just press the "Create" button:

Just like before, this creates an orange transition box. We can edit the transition as before.

Using the same steps as before, go ahead and try to create the transition to go from kneeling to standing yourself:

And there you go, second transition created!

We are aware that editing transitions inside the previewer is not ideal. Currently a lot of information is shown in a couple of tracks and we are planning spreading out the From, Transition and To parts on different tracks; possibly even showing transitions in a more specific transition editor.

There is an update bug here in the SDK that we will obviously fix; the new transition will not show up immediately in the transition picker.

Transition Picker Filters

In the transition picker you can look for transitions by specifying part of the name of either the FragmentIDs or the tags involved:

Transitions To and From Anything

As a side note, when you do not specify a From or To fragmentID the transition shows up as respectively an "<Any> to" or "to <Any>" transition.

In the example below we have:

  1. A transition from anything to Idle.
  2. That one shows up with "<Any> to" (note that even if there is nothing before the Idle fragmentID it still shows up; coming from nothing also counts as 'anything').
  3. A transition from Idle to anything.
  4. That one shows up with "to <Any>" (in this example we set up going from "Idle" to "Move").

When there is both a transition from and to <Any> transition available, both will play: first the "to <Any>", then the "<Any> to".

Transition Start Time - Delaying a Transition

As we saw in the section on Trumping sometimes a transition gets delayed to the end of the previous fragment. This is the default behavior if the previous fragment is not looping. Typically you want to start the new fragment a little bit before the previous one ended though. If we want to do this we need to create a CryMannequin transition and next move the "orange block" to the point where we want it to be. This changes what is called the Transition Start Time. This can be hard to envision, so let's work on an example.

Let's make a simple (contrived) example starting from a transition from "Move (standing)" to "Move (standing)" (this also shows that you can make transitions where From & To are the same fragment)
Make the transition from the transition picker:

Next open it up from the transition picker:

The previewer should open automatically and it should look like this:

Now we'll do a change similar to the one we did when we described Trumping, we edit the Move fragment:

And we turn it into a non-looping fragment by making the first clip non-looping:

This is how the transition will look now:

The transition doesn't start immediately after the end of the first Move fragment because we only request the second one after 3 seconds.

Let's move the second FragmentID request back in time as follows:

Now we see something like this, where the second request happens around 0.5 seconds but the actual transition starts at 1 second.

As before, this is because the default transition behavior when coming from a non-looping fragment is to wait until the end of the fragment.

Now we want to actually start the transition earlier, so we move the transition block, the orange block, back in time a bit:

And the result is that the transition starts earlier:

By doing this we have changed what is referred to elsewhere as the "Transition Start Time".

The Transition Start Time is stored as a value relative to the end of the previous fragment. In the advanced section on Cyclic Transitions we see an exception to this though.

Transition Select Time - Picking Different Transitions Based on Time

Work in progress

The editor interface for this is currently incomplete. As such we only give a brief overview of the feature here.

Sometimes you would like to select a different transition based on where you are in the previous fragment. For example you typically have a different "walk to idle" transition based on which part of the walk cycle you are in. To do this in CryMannequin you can create multiple transitions, each with a different "Select Time".

Here is an example of how this could look:

  1. There are 2 transitions. One has a select time of 0.00 (seconds) and the other a select time of 1.62. This means the first transition will only be selected when the previous fragment is at a time between 0.00 and 1.62. The second transition is only selected when the time is at or after 1.62.
  2. All select times are displayed at once when you select the transition ("the orange box") as orange triangles on top of the fragmentID track.
  3. Select time can be changed by moving the special divider around.
  4. To make sure you are dragging the correct divider, look for the word "Select" in its tooltip.

Currently you might need to dive into the .ADB file to hand edit the select time. The transitions are "Variants" of "Blends" near the end of the .ADB files. Look for sections like:

   <Variant from="stand" to="stand">
    <Fragment selectTime="0" enterTime="0">
      ...
    </Fragment>
   </Variant>

The selectTime value is the time in seconds from the beginning of the previous fragment.

Advanced Transition Properties

When you select a transition, two special options show up in the properties window:

Cyclic Transition

We saw that it is possible to delay transitions to a certain point in the animation in the section on the Transition Start Time. By default this 'start time' is relative to the end of the previous fragment; but this doesn't work when the fragment you are coming from has no clear ending, for example when it ends with a looping clip. You might want to set up a transition that comes from a run cycle and you only want to trigger this transition when the preceding animation is in the second half of the run cycle. To make this work you need to check the Cyclic Transition flag. From then on the start time is stored in a 'cyclic' way: the time restarts at 0 after each cycle.

When you use a cyclic transition the time is stored relative to the length of the cycle. So if the animation changes length the start time will move along in the proper proportion. This is useful when you are using parametric animations, animations that change length at run-time based on parameters like "walk speed".

Outro Transition
Deprecated feature

Outro transitions are deprecated and will be removed in a future release of the engine. We instead recommend that you use a dedicated intermediate fragment in the situations where you might have used an outro transition.

In many cases a transition to <Any> (see Transitions To and From Anything) in a certain sense 'belongs' to the fragment before it. For example transition from "Look Around Using Binoculars" to anything might stow the binoculars and go back to a normal idling pose. To the game code it might be useful to treat the stowing of the binoculars as part of the action that is "using binoculars" instead of as a part of the next action. If programmers ask for this, you will have to mark these kinds of transitions as "Outro". This won't change the behavior in the editor, but it will change the behavior of game code.

Outro transitions will be in a sense appended to the previous fragment. When they play the previous action will not be exited but IAction::OnTransitionOutStarted() will be called. Also, IAction::IsTransitioningOut() will return true while the Outro Transition is playing.

Scopes

Load up the preview file for "SDK_playerPreview1P.xml". See Loading the Preview File (but this time the file is called "SDK_playerPreview1P.xml"). If the file manager pops up you can press "Undo Changes to Selected Files" to ignore your previous changes.

This opens up a complete example for a first person shooter player setup. It might overwhelm at first because there is a lot going on. There are a lot more FragmentIDs and tags, but we already saw those, nothing new there. But notice all the new 'scopes' that became available in the previewer ("FullBody1P", "Torso1P", ...)

In a real game, just like in this example, there are typically many different parts of a character playing their own animation. This is where the scopes come into play. Each scope can play one fragment at a time, but as there are many scopes a lot of fragments can play at the same time. We can now start setting up fragments for each of those. Depending on the setup they either play independently or are synchronized among each other.