Animation Graph Reference

Documentation made for Animation Graph 1.5

Saving and Loading

There are two files associated with each AnimationGraph. One .xml file and one .ag file with the same name.
Both are located inside the Game\Animations\Graphs folder.

The .xml file is stores the Editor information for the Animation Graph. It is only needed inside the Editor and contains a lot of metadata like Views and Node positions for the Animation States which are irrelevant upon execution of the game. This file is uncompressed but it is not recommended to edit it by hand.

Upon saving in the AnimationGraph Editor, the .xml file is saved out and then loaded into the Engine implementation AnimationGraph which sits in CryAction.dll. In this steps all the parameterized states are expanded into separate states and the templates are integrated. Is the loading successful, all this information is saved out again into the.ag file, which is a binary xml file.

Ingame, the engine will always try to load the ag file directly - if it isn't present or the current ag file format is different from the one the file was saved in, it will load and convert the xml file instead, which takes longer.
The ag file does not depend on the template files to be present and it does not contain redundant metainformation. This file can not be opened with the AnimationGraph Editor.
For shipping, both the xml and the Template files can be removed.

The current ag file format version is defined as in CryAction in AnimationGraph.h. It needs to be updated if the serialization of any of the nodes change. See the Animation Graph Programming Reference for further information.

  const static int AG_VERSION = 50;

When the internal version number is increased, the graph will not load ag files that were saved with a lower version number. Instead it will load the corresponding xml files and convert them on-the-fly. This will take a long time and cost memory and is to be avoided expecially on consoles. Re-save each graph once to update the ag files and get rid of the stall at loading time. You will get a warning message in the log file about mismatching version in animation graphs. (also see Warnings and Error Messages)

Parameters of an Animation State

Animation Parameters

Graph Node Parameters

	Include In Game Unchecking this will prevent the graph from exporting this state to the binary file. It will not exist in the graph at runtime in the game. Doing so will color the state red. This is useful for states and setups which are no longer needed but are to be kept for reference, or in case it might be needed again at a later time in development.
	Allow Selection Checking this makes the state selectable (green state), meaning this state will be checked for how well the Selection Criteria match the current inputs when the graph searches for a new state. Unchecking it will mark the state as a transition or hub state (yellow), which can only be entered while pathing through the graph to a selected state.
	Allow Higher Layers If unchecked in Layer 0, no animations in layers higher than 0 are allowed (present ones will be blended out). This is useful if you need your animation to not be influenced by any other Additives or partial Body animations, but cannot be certain they are inactive - for example in climbing or contextual actions. Only works in layer 0. (Code: Sets the CA_DISABLE_MULTILAYER flag)
	Can be hurried If this checkbox is checked and an AI controlled character gets alerted (by being attacked or by seeing an enemy for example) while playing this animation --> then the animation will be skipped/interrupted. All subsequent directly linked animation graph states on the path to the queried state will also be directly skipped if they are also flagged as 'Can be hurried'. This is useful for skipping some of the relaxed style animations in order to start playing combat style animations faster for example - to circumvent long transitions if the game mechanic just simply doesn't give the time for it.
	Skip for Players If checked, the state will be valid/available for AI controlled characters only. For the player controlled characters it will be simply skipped if it is in the middle of the path and also while finding the queried state. It will be ignored if it is a selectable state or a state reachable by following a link with force-follow.

Common Parameters

	Loop Asset Checking this will make the asset looping and play repeatedly. (Code: Sets the CA_LOOP_ANIMATION flag)
	Manual Update Starts the animation but will not automatically update it (animation time will not be advanced). The code has to take care of this - useful for example for ladder climbing etc... (Code: Set the CA_MANUAL_UPDATE flag)
	Repeat Last Key On non-looping animations, this will freeze the last frame in the asset and repeat it endlessly. This prevents snapping when the transition time to the next animation is longer than the time left in the animation to play (Code: Sets the CA_REPEAT_LAST_KEY flag)
	Use Time Warp Blending If checked, this asset will always be time-aligned with the previous asset when blending in. Commonly this is not needed - use the Time Alignment Group Modifier for Locomotion Cycles instead. (Code: Sets the CA_TRANSITION_TIMEWARPING flag)
	Stop Current Animation Forcefully stops the previous animation and removes it from the queue. This will cause visible snapping if the last frame of the old and the first frame of the new animation are too different, but can greatly improve blending for example in combo-movements where the frames match.
	Partial Body Animation If checked, this animation will not run through the entire skeleton and update even those bones that are not defined in the asset itself. This should be true for all partial body animations and for all animations in an upperbody graph. (Code: Sets the CA_PARTIAL_SKELETON_UPDATE flag)
	Move2Idle Anim This enables a special blending to a Move2Idle animation, which tries to find a matching keyframe as it was being used in Crysis 1. It is recommended to not use this as it will give faster and equally good blending with a direct blend. (Code: Sets the CA_MOVE2IDLE flag)
	Exclusive Root Movement This animations root (locator) movement will be used 100% from the moment the animation has been started. The rest of the animation will be blended in according to the transition time, but the movement will not be influenced by previous animations. This is helpful for all animation driven movements that need to be exact, like climbing etc. This should be on for Smart Object animations. (Code: Sets the CA_FULL_ROOT_PRIORITY flag)
	Transition Time The blend-in time for the animation of this state. Once this state is entered, the animation will be blended in using this time value (in seconds). The previous animation will be blended out over the same time. This value can be overridden for specific transitions (when coming from specific other states for example) using the transition links.

Link Parameters

When creating a link between two states, the AnimationGraph allows to set a few parameter on this link to fine-tune the transition represented by it.
To edit these parameters, right click on the little circle in the middle of the link, and choose "Edit" from the popup menu.

Pathfind Cost	This parameter is for fine-tuning the pathfinding in the graph. When the graph switches from one state to another, it finds a path through the graph through some transition states (if these exist). It usually chooses the shortest path it can find. However, instead of calculating the number of states on the path and then choosing the shortest one by selecting the path with the lowest number of states in it, it actually calculates a "path cost". For each state and transition (link) on the way it adds a number to this cost. Usually this number is set to a default of 100, but you can manually increase or decrease it and thus make sure the graph will choose a certain path from A to B even if the number of states on this path is higher. It is not something you would need to use on a daily basis, it is merely used for fine-tuning in special cases.
Override Transition Time	The blending time from an animation currently playing to the next on is determined by the state that holds this next new animation. The time can be set in the state parameters. This blend time will be used for all incoming transitions to this state, regardless from where the transition is coming. Sometimes however it can be useful to set different blending times when coming from different states or animations. This parameter on the link allows to set up an override for the transition time, which will be used instead of the state's blending time. It can be set anywhere on a path, it doesn't have to be on the link leading into the next selected state, which makes it possible to use this override on a group of states instead of just single ones, which makes setting this up faster.
Force Follow Chance	Force-Following can be used for two things in the AnimationGraph: 1. Randomization 2. Forcing a state to be left Regarding 1: Randomization is now handled by the Randomizer in the AnimationGraph. Please see the documentation on how to use this. Regarding 2: See this documentation on explanation and an example: Creating Idle Turns in AnimationGraph

Animation Randomizer

Asset Randomization

The Animation Randomizer is available with CryENGINE 3.1.5 and up.

Double-Clicking on the Animation Name Edit field in a state or Additive Modifier will open the Randomizer dialog.
Instead of a single animation name, you can specify a list of animations here with a couple of options and parameters and the graph will pick on based on probability at runtime to play.

Note that the Animation Randomizer as the rest of the Animation Graph is not serialized over the network, as the game logic and animation logic are kept separate in CryENGINE. If you need randomized assets to be in synch over the network, please use an Input to select the asset instead and generate and serialize this inside the game dll instead.

Parameters of the Randomizer

General Parameters

	Switch Assets Over Time Switches to a new animation every once in a while. Note that the state or additive modifier must be set to looping for this to have an effect.
	Switch Probability Probability that a new animation is selected. Note that this will only be checked against if a new asset can be selected yet - if the current animation cannot be interrupted, it won't switch to a new one or run a test against the probability
	Time Align between Assets Sets the Time-Warping flag for all assets.
	Switch Immediately after non-looping asset finished Doesn't wait for the timer to randomly trigger but will immediately select a new animation once the previous one has finished (for non-looping assets only of course) Good for usage with fullbody animations where one animation should always play. Sets the Time-Warping flag for all assets.
	Initial Delay before first animation Doesn't start the animation directly when the state is entered but instead waits for a specified amount of time. Only useful on an Additive Modifier to delay animation start.
	Add Animation Adds a new animation slot.

Animation Parameters

	Loop Loop plays this animation. This prohibits the option of "Do not Interrupt".
	Do not Interrupt A new asset can not be started until this one has finished - if asset switching over time is enabled in the general parameters.
	Allow Reselection This asset can be selected twice in a row. If asset switching over time is enabled, but this option is not, the randomizer will select a different asset after this one.
	Transition Time Blending time from previous randomized animation to this one.
	Probability A number representing the relative chance that this asset will be selected over the others. The Selection probability in percent is automatically calculated and displayed above this edit field.
	Remove Slot Delete this animation from the Randomizer. This cannot be undone.

List of all Inputs automatically provided by the Engine

Action	usually used for all looping non-locomotion actions, like sitting, talking, etc, in SDK also for the loop while being on a ladder This Input is also used by the AI, Smart Objects and can be set directly from the console through ag_action <value>.
ActualMoveDir4LH	Simplified Movement Direction of the character: Bwd, Fwd, Lft, Rgt, Idle from within CryAction, based on the movement in the frame
RequestedMoveDir4LH	Simplified Movement Direction of the character: Bwd, Fwd, Lft, Rgt, Idle from within CryAction, based on the movement request
ActualMoveSpeed	movement speed in meters per second (m/s) set from CryAction, based on the movement in the frame
RequestedMoveSpeed	movement speed in meters per second (m/s) set from CryAction, based on the movement request
ActualMoveSpeedLH	flat ground (2D) movement speed in meters per second (m/s) only taking x and y movement into consideration, set from CryAction, based on the movement in the frame
RequestedMoveSpeedLH	flat ground (2D) movement speed in meters per second (m/s) only taking x and y movement into consideration, set from CryAction, based on the movement request
ActualMoveSpeedLX	movement speed on x axis (in m/s) set in CryAction, based on the movement in the frame
RequestedMoveSpeedLX	movement speed on x axis (in m/s) set in CryAction, based on the movement request
ActualMoveSpeedLY	movement speed on y axis (in m/s) set in CryAction, based on the movement in the frame
RequestedMoveSpeedLY	movement speed on y axis (in m/s) set in CryAction, based on the movement request
ActualMoveSpeedLZ	movement speed on z axis (in m/s) set in CryAction, based on the movement in the frame
RequestedMoveSpeedLZ	movement speed on z axis (in m/s) set in CryAction, based on the movement request
Aiming	0 or 1, whether Aiming is active or not set from Player, when setting Aim Targets, not dependant on active Aim Poses
AnimPhase	current normalized time of the active animation in layer 0 set from CryAction
DesiredTurnSpeed	desired turn speed of body direction set in Player, includes camera turning, used for Idle Turns
Firing	firing timer, when a bullet is shot, the counter goes to 10 seconds and starts counting down set from Actor, value is taking from the player stats
Health	integer health value of the character provided by Actor
Item	name of the item that the character has equipped string name is set up in the item config file, provided by several classes in the gamedll
PseudoSpeed	a form of normalized speed value provided by movementcontroller, calculation is based on AI and lua setup files
Signal	used for one-shot action, like reloading, melee punches etc used by Game, AI and Smart Objects, and can be set via console command ag_signal
Stance	used mostly for locomotion modifiers (relaxed, combat, crouch, prone,...) stances are set up in code as well as the characters' lua files
SwimControlX	desired velocity on the x axis set from PlayerMovement, only during swimming
SwimControlY	desired velocity on the y axis set from PlayerMovement, only during swimming
SwimControlZ	desired velocity on the z axis set from PlayerMovement, only during swimming
Vehicle	name of the vehicle the character is currently in, "none" if in no vehicle set by the vehicle system, the names are set up in the vehicle and must be present in the graph as well
VehicleSeat	Seat number the character is sitting on as set up in the vehicle setup
waterLevel	depth in the water that the player is submerged (in meters) used for deciding inside the graph whether to play swim or dive animations

State Selection Algorithm

Step 1: Creating a list of available States

The animation graph performs a database-like query over all selectable states by comparing current input values with the selection criteria of each state. The goal is to create the list of available states whose selection criteria match best with the current input values. Note that inputs, for which the value is set to its initial special value <not set> will be ignored during this process.

The process begins with the highest priority input first – all selectable states whose selection criterion is matching the current value of that input are stored in the list of available states. If there are no states in the list, the process stops with an error. If there is only one state in the list, the process is over – there is no need to further narrow the list since there is only one state in it.

Then the value of the second highest priority input is evaluated against all states from the list of available states. States whose selection criterion on that input does not match the current input value are removed from the list. If there is still more than one state left in the list, the process of removing states from the list continues with the next input in order of their priority. The process stops, if there is only one state left or if after some iteration, there are no states left in the list of available states. In the latter case the last iteration will be rolled back and the process stops, with the list of available states before processing the last input, even if there is more than one state left in the list.

Step 2: Ranking of the results

Each state has a ranking of how well he matches the current inputs - the ranking is determined by the priority each input has been assigned.
Some inputs have significantly higher priorities than others. For example if a state matches the Action input perfectly, but doesn't care about item, stance, speed or vehicle, then that state will still be chosen over one that matches the latter four, since it has a higher priority and the state will have a higher ranking.
Only the top ranking states in the list will be returned by the state query. Each state in the list has the same ranking value.
The ranking of each state can be seen in the AnimationGraph Editor using the State Query tool with a set of Input values.

Step 3: Selecting the Queried State

If there is only one state in the list of available states, it is being selected as the queried state.
Otherwise the graph will check whether the state it is currently in is among the available states. If so, it will just stay in this state. This avoid unnecessary jumping between states. If the current state is not in the list one of them will randomly be chosen to be the queried state, since all the remaining states are equally suitable to be selected.

Warnings and Error Messages

"Tried to read animation graph with different version! Filename=XXXX Current=YY File=ZZ"

Should this message appear on your console or the Editor/Game log file, you will need to re-export the Animation Graph.

+Explanation:+The file format of the binary file (AG File) changed and thus cannot be loaded. The graph detects the version mismatch and loads the xml file instead, converts it on the fly into an ag file and then loads the result. This takes a huge amount of time and costs memory during the time of conversion (same on consoles).
Simply opening the graph in the AnimationGraph editor and re-saving it will update the file format and solve the issue.
You do NOT have to convert your AG 1.0 graphs to AG 1.5 to fix this, re-saving with the old graph editor will also update the file format.

"Unable to create factory XXX; load aborted"

A node could not be created, it most likely doesn't exist or the data has been exported wrongfully. This needs a code fix.

+Explanation:+When working with nodes, either with Modifiers (in AG versions 1.5 and up) or Extra Properties (in AG 1.0) in the Editor, the graph will try to instance the implementation of this node/modifier upon loading the xml file in CryAction. If a graph includes a modifier/node that is not implemented and registered this warning will occur. It can also happen that the node itself exists, but it cannot make sense of the data in the xml file and cannot initialize itself. When working with customly added game specific noes, make sure everything is still in place after an integration.See the AnimationGraph programming reference about programming nodes.

Programming

See the Animation Graph Programming Reference for more information.

Conversion Issues from AG 1.0 to AG 1.5

Upon loading an animation graph saved with version 1.0 into the 1.5 (or higher versions) editor, the graph data will automatically be converted. It cannot be saved in the old format. It is recommended that you make a backup or change the file name. While backwards compatibility is kept to a maximum, there might occur conversion issues in special cases or when the graph has been custom modified.

The following lists all known issues that cannot be solved automatically upon conversion due to feature changes in the graph versions when converting from version 1.0 to version 1.5.

Transition Times and Playback Speed in parameterized states that are overridden in sub-parameterizations are not converted. Only one transition time and playback speed per state is supported.
Animations on multiple layers within one state are no longer supported for better flow control. Warning message will appear upon conversion. Use Additive Modifiers to start animations on multiple layers and restore functionality.
Custom Template Nodes added that were not shipped with AnimationGraph 1.0 (CryENGINE version 2.3.5) will not be automatically converted. You will need to create a modifier for each of them (just the Editor frontend, the node implementation have not changed).
WaitForKeyTime (CA_START_AT_KEYTIME flag) parameter has been deprecated. Not used in Crysis or any SDK build.
Custom additional Template Nodes defined in Parent states are not inherited by the child states.
ForceStartImmediately has been deprecated, since the flags affected by this parameter are obsolete no longer being used.
Events and other template nodes/extra parameters that read in custom template parameter values (such as $name) will not work. Conversion will create a dummy Modifier for these cases so you can replace them one by one. This is not valid for Outputs, which support custom template parameter names.
Custom Template: Animation Names using unusual template parameter names might not be found by the conversion code.
Selection Criteria that is filled by template parameters exposed in the Editor and differs for sub-parameterized states cannot be converted and must be put back manually.