The Animation Graph 1.0

General Information

The function of the animation graph is to define the order in which animations can be played and the rules when and how some transition between different animations may happen. The animation graph is a directed graph in which each node represents an animation. Nodes of this graph are called animation graph states. Graph links between animation graph states define available transitions between animations. Links are unidirectional.

At any moment only one animation graph state can be active and that state is called current state. Usually this state is defining which animation is currently playing.

An additional functionality of the animation graph is to choose the most appropriate state to be the current one. The chosen state is called queried state. This decision is based on requests coming from outside as values assigned to animation graph inputs. Animation graph inputs are a set of values (maximum 32), each of which is defined by its unique name, type and range of values as well as some other properties. Various systems, like animated character, movement controller, game logic, vehicle system, item system, flow graph, smart objects and AI can set input values. Whenever the inputs change a different state can potentially be selected as the queried state. State selection works by comparing actual input values with selection criteria for states in the graph. Only states that are marked as selectable can be selected as the queried state.

Whenever the queried state is different from the graph's current state, the built in pathfinder will find the cheapest path from the current state to the queried state by following existing links between states. Then each state on that path will be traversed - the current state will change and pass through each of the states on its path to the queried state.

The main views of the Animation Graph Editor are shown here:

• 1. States: This lists all the states that are created.
• 2. Views: "View" is a categorizing utility for states. This is especially useful when there are many different states and links.
• 3. Inputs: This lists all the defined inputs that can be used for the selection criteria of each state.
• 4. Properties: Here you can specify the detailed properties of each state, input, or view.
• 5. State Query: An essential tool to test whether or not the animation graph is working as expected.

For tutorials on performing specific actions in the Animation Graph, please refer to the following pages:

• Conditional Playback
• Transition Sequencing
• Event Notification
• Randomized Motion
• Tips and Pitfalls

Creating an Animation Graph

• Create states, as needed.
  • Specify the general properties.
  • Specify a template and its properties.
  • Specify extra properties, if needed.
  • Specify the selection criteria of the state.
• Create inputs, as required.
• If you want a randomized motion, create it with ForceFollow links, in a view that you will create.
• If you want a specific transition sequence, create it with links, in a view that you will create.
• Check the behavior of the animation graph by using State Query.

Using Animation Graph Files

Animation graph files are stored as .xml files in folder Game/Animations/graphs. By saving the file, its content is additionally preprocessed and stored in a binary format file with extension .ag. If this file is present in the same directory it will be used by the game instead of .xml file to reduce loading time. A significant difference in loading speed is noticeable for large animation graphs only.

Some characters need just one animation graph, but other need two - one for the full body animations and one for the upper body animations. Each character entity class can specify the animation graph files to be used with that character. There are two Lua table entries in the entity scripts that specify the animation graph .xml files:

• AnimationGraph - defines the file name of the full body animation graph
  and
• UpperBodyGraph - defines the upper body animation graph, or if the upper body graph is not needed it has to be set to nil or to an empty string.
  This is an example script taken from Player.lua:

Player =
{
  AnimationGraph = "PlayerFullBody.xml",
  UpperBodyGraph = "PlayerUpperBody.xml",
  ...
}

Main Components

The animation graph consists of four main components:

States

The nodes of the animation graph are called animation graph states.

Current State and Queried State

The active state is called current state, while the state towards which the current state transitions from one state to another by following the available links is called queried state. Queried state is chosen by comparing the selection criteria of all selectable states against the actual input values.

Animations

Animations in the animation graph are represented as states. One animation can be associated with one state (or less common but still possible, the same animation can be associated with multiple states). Whenever a transition from state A to a directly linked state B begins the animation of state B is added at the end of the animation queue. Transition ends when the animation starts playing, which depending on various setting for both states may happen immediately or may happen later. Even though the state A will be left its animation will remain in the queue until the blending to animation B is done.

States Types

Animation Graph Nodes

Each state consists of several animation graph nodes. Each node has its own function defined by its type. Some node types control the animation queue, some control the physical proxy of the character entity, and some control the movement... Set of nodes used to build a state is defined by the selected template for that state and eventually by adding optional nodes (see Extra Properties in UI).

General Properties

This is the list of general properties of the animation graph states:

Inputs

Definition

For each animation graph there is a set of values controllable from various external systems used to place animation requests. These values are called animation graph inputs. Each input is defined by its unique name, type and range of values, etc.

Value Types

There are three value types available for the inputs: floats, integers and keyed values. The values for each input are limited to a certain range for inputs of type float, integer or to the list of defined keyed values for inputs of the type key. When setting a float or integer value which is out of range, the value will be clamped. Setting an undefined key value for keyed inputs will set the input to its default value if specified, or to special value <not set> when the default value is not specified.

Initial Values

Initially each input regardless of its type is set to a special value <not set> . Hopefully all inputs will be set by different program modules before the first update of the animation graph when the inputs get used to find the queried state. However, all inputs set to this special value will be ignored when looking for the queried state.

Input Priorities

When looking for the queried state the inputs are evaluated by their priority. Inputs with higher priority are evaluated before other inputs. The order of evaluation of inputs with equal priority is undefined.

Properties

This is the list of properties of the animation graph inputs:

In addition for the inputs of type integer and float there are properties to define the minimum and the maximum values. For the inputs of keyed type there is a list of available keys. Note that the default value for keyed inputs must be defined as one of the keys for that input.

List of Existing Inputs

In the current implementation of the engine, most of the animation graph inputs are generic and used by all character types. These inputs are controlled by different code modules. However, not all of these inputs are needed for each character type. In this case the inputs should not be defined in the animation graph for those characters. Setting a value for a non-existing input does not induce any error or warning. There are also a few character-specific inputs controlled by game-specific code.

This is the list of generic animation graph inputs:

Setting Input Values

Values of the animation graph inputs can be modified by any module of the engine, as well as from Lua scripts.

Using C++ code

A pointer to the character's IAnimationGraphState object (which is the interface to the dynamic part of the animation graph) will be needed and then one of these methods can be called on it:

bool SetInput( InputID, float, TAnimationGraphQueryID * pQueryID = 0 );<br />bool SetInput( InputID, int, TAnimationGraphQueryID * pQueryID = 0 );<br />bool SetInput( InputID, const char *, TAnimationGraphQueryID * pQueryID = 0 );

The first parameter is the ID of the input, the second is the value to be set on it (the value will be converted to match the type of the input). The third parameter is optional and used to obtain a query id - used in case of additional feedback about this operation is needed (e.g. when the animation matching that input value begins).

The return value will be true if the operation has succeeded.

The following is same as SetInput except that it will not set the default input value in case a non-existing value is passed. So this might be useful when you want to change only an upper body animation without affecting the current full body animation.

bool SetInputOptional( InputID, const char *, TAnimationGraphQueryID * pQueryID = 0 );

Inputs can also be set by specifying their name instead of the ID, using this method:

template <class T> inline bool SetInput( const char * name, T value, TAnimationGraphQueryID * pQueryID = 0 );

However, using the ID saves one string lookup. Therefore the preferred way to reference inputs is to store their IDs in variables, to be used later. Input names can be converted to input IDs using this method:

InputID GetInputId( const char * input ) = 0;

Using Lua Scripting

Changing animation graph input values from scripts is not recommended but still possible. To do so, this Lua script function can be used:

entity.actor:SetAnimationInput( name, value );

... where entity is the entity script table, name is the name of the input and value is the value to be set on it.

Selection Criteria

Definition

The selection criteria of an animation graph state are a set of rules (one rule per input) that define the valid values for each input to select a state as a queried state, if the state is a selectable one. On non-selectable states, the rules define which values of the guarded inputs are valid for the state to be available for the pathfinder and allow passing through it. Rules for non-guarded inputs are ignored. Having a no selection criterion for a guarded input makes the state available for the pathfinder regardless of current input value.

Rules

There is one rule for each input and for each state. Each rule can either be inherited from its parent state or defined in one of these three forms:

• Any value is valid
• Only one specified value is valid
• Only values within a specified range are valid (not available on keyed inputs)

If no rule is defined for an input and there are no rules defined for the input in any of the parent states, the system acts equal to having a rule which validates any value for the input.

Finding the Queried State

The state which the animation graph tends to reach is called the queried state. Finding that state is a complex process which happens in several steps:

Step 1: Creating the 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: 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, since all the remaining states are equally suitable to be selected, one of them will randomly be chosen to be the queried state.

There is one exception – if there is more than one available state and some of the states are locomotion states, the queried state will be selected to be one of the available states. In this case the selection is not on a random base, but on a more complex selection method which works by comparing the motion capabilities of each of the available locomotion states and the predicted movement for that animated character. The animation whose capabilities match the most with the prediction, will be selected as the queried state.

Obviously to use the benefits of this method, the animation graph needs to be set up in a certain way – all locomotion states need to be equally selectable. The easiest way to achieve this is to set the selection criteria to be exactly the same for all of the locomotion states. Note that locomotion states can only play LMG animations which are tagged with an additional information to logically describe the animations they play, so the animation graph can distinguish eight different types of LMG's: walk, run, idle step, idle turn, idle to walk, walk to idle, idle to run, and run to idle. This information is also used to choose the queried state besides the check of how much the prediction fits within the range of motion capabilities for each LMG. Idle is the ninth special type of a locomotion state which also needs to use the same selection criteria. To make it recognizable to the animation graph as an idle state, it needs to be a selectable null state without an animation associated to it. Instead, the animations are played by following a 'force followed' link from the idle state.

Step 3: Force Follow

If the state that was selected as the queried state in step number two is also the current state of the animation graph and the state has at least one link with 'Force follow chance' property set to non-zero value and leads from that state to some other state, then within this step the queried state will be changed to be one of the 'force followed' states. Usually the force followed states are non-selectable and as such not part of the list of available states. Still that does not mean they cannot be selected as the queried state – they can, but only in this special case.

The values of 'Force follow chance' properties of the links are used as weighting values that define the probability to follow a link. A higher force follow chance value means that the link will be more likely force followed, compared to other links with non-zero force follow chance.

Nodes

Each state of the animation graph consists of a number of functional units called animation graph nodes.

There are different types of nodes, where each type controls something specific only for that type of nodes. For example nodes may play an animation, control the animation properties, play facial animations, etc... With only a few exceptions, there can only be one node of a type in one single state.

Set of nodes used to build an animation graph state is defined by the state template on which that state is based eventually extended with one or more of the optional nodes. States are based on only one template, but each template usually defines several nodes at once. Only some types of nodes are optional, and also they can be used as parts of the templates. The only way to make a non-optional node be part of a state is to base the state on a template in which that node is specified as one of the template's nodes.

Each node has a set of properties which is defined by its type. Properties of the optional nodes can be directly edited in the Animation Graph Editor, while the properties of the non-optional nodes can only be accessed through the template. The template can expose some of the properties of its nodes in the Editor.

List of Existing Types

This is the list of currently implemented animation graph node types:

Node Factories

For each type of animation graph, nodes a factory class needs to be registered in the animation graph manager (class =CAnimationGraphManager=).

For each state the animation graph holds a list of pointers to already created instances of registered factories. Each of those factories will be initialized with properties read from the state template, template properties or extra properties. Factories of same type with exactly the same properties will be instantiated only once and then their single instance will be referenced from multiple states.

Nodes need to be created before entering a state and destroyed after leaving it. As memory allocation, initializing and releasing of memory while the game is running is a very expensive operation, most of the animation graph nodes are implemented in a way that allows one single node instance to be shared between multiple states, multiple animation graphs or even multiple characters. In this case the node cannot store any dynamic data in member variables but instead all dynamic data must be stored in the character entity or in the dynamic part of the animation graph (=CAnimationGraphState=). In such a case a single C++ class can serve as a factory and as a node at same time. Of course, one object instance will be created for each different set of values for node properties.

Runtime Functionality

All of the nodes of the current state are kept by the animation graph in a list. Some of these nodes will be updated on each frame.

Whenever a transition to another state is needed, the list of node factories of the current state is compared with the list of node factories of the next state. Node factory instances that are in both of these lists will be ignored during this transition and nodes created by those factories will be reused with the next state. All other nodes from the list of current state nodes will be marked as nodes to be exited.

The transition to the next state does not always begin immediately. All of the nodes marked to be exited will be queried, weather a transition is applied or not. Each node has the right to 'veto' the transition to the next state. Querying will continue on each frame until all of the nodes 'agree' to begin the transition to the next state. Once that happens the transition begins.

At the beginning of a transition to the next state, a notification about the intention to leave will be sent to all of the nodes of the current state first (except to the nodes meant to be reused). Then the list of nodes for the next state will be created using their factories. Each newly created node in that list is notified about the intention to be entered.

At this point the transition is considered as started. On each frame the nodes of the next state will be queried to check if the transition is done. The transition is usually done when the requested animation starts playing or if no animation was requested. In the first case the transition is done when one of the nodes are entered, while in the second case the transition is done, if there are no nodes waiting to be immediately entered.

Once the transition is done (because at least one of the nodes of the next state was entered), the nodes of the current state are notified that to have been 'exited' and nodes of the next state are notified to have been 'entered'. If the transition is done, but none of the nodes of the next state was entered, the nodes of the current state will remain semi-active until a state is entered.

Finally the next state becomes the current state and the list of nodes of the old state is replaced with the new one.

Templates

State templates are simple data structures defined in .xml files. Each animation graph state is based on one state template. All templates are uniquely named and global for all animation graphs. Each state specifies the template on which it is based.

The templates allow easy setup of an animation graph state and control of a group of nodes and their properties by encapsulating common sets of nodes, setting values for most of the node properties and exposing the remaining small number of user controllable properties in the UI as Template Properties.

In addition to definition of nodes the templates can also define guards on some of the inputs and add selection criteria rules. Here again the template properties can be used to expose some of the guard or selection criteria values in the UI. Note that while selection criteria rules can also be manipulated directly from the UI, the only way to add a guard to a state (besides the inputs that are always auto-guarded) is by using the template.

Template Files

The state templates defined in .xml files, are all located in folder Game\Libs\AnimationGraphTemplates. The template called 'Default' is the only built-in template and does not have to be defined as an .xml file. The 'Default' template is actually completely empty (defines no template properties, nodes, guards or selection criteria rules) and is used to create so called null states.

The root node of the .xml file is the only mandatory node. It is named AGTemplate and must specify the name of the template as value of its attribute 'name' .xml file names (without the extension) must match the state template name they are defining. Template names must be unique. There is also one optional attribute named 'extend' , used to implement a template based on one or more parent templates, by inheriting all of their child XML nodes. The child nodes can be overridden.

The child nodes of the root node can be specified using one of these XML tags:

Specifying node properties

Animation graph nodes used to assemble an animation graph state are defined in the template xml files using their type names as xml tags, and the node properties are defined as xml attributes. Each attribute value can be a constant value, one of the parameters defined for that template, or a short Lua script expression which gets evaluated only once and the result is stored as a value for that node property.

These tables explain the properties for each node type:

AnimationLayer1, AnimationLayer2... AnimationLayer9

AttachmentEffect

ColliderMode

Event

FacialEffector

FallAndPlay

This node has no parameters.

FreeFall

This node has no parameters.

LookIk

MovementControlMethod

Output

ParamsLayer1, ParamsLayer2... ParamsLayer9

SetInput

Sound

TransitionParamsLayer1, TransitionParamsLayer2... TransitionParamsLayer9

WaitForUBAllowed

This node has no parameters.

State Parameterization

Very often it is necessary to replicate an animation graph state multiple times and to add only a tiny difference in few properties of each copy. Moreover the differences in properties often seem to follow some pattern, or having to be replicated in a different dimension (the tiny difference is in some other set of properties). The number of states and the complexity of the animation graph grows rapidly in a case like this. Sooner or later it can reach the state where no further changes can be made, without spending a lot of time to replicate changes made on the original state to all of the replicated states, or to look for the bugs introduced while copying.

All of these problems can be avoided by using state parameterization – an easy way to create multiple copies of a state. One or more state parameters can be added to each state. For each parameter there is a list of literal values used to define patterns for those tiny differences in some of the properties of replicated states.

The number of states after the replication depends of the number of parameters and the number of values for each of those parameters. The state will be replicated once for each state parameter value if there is only one parameter or once for each possible combination of parameter values if there is more than one parameter. The total number of states after the replication can be calculated as N {{ =N1 � N2 � ... � NP}} , where N is the total number of states, Ni is the number of values for parameter number i and P is the number of parameters for that state.

Parameter values can be used in any of the state properties, namely all strings of form [parameter_name] will be replaced with different parameter values in each replicated state. If for example for the parameter named StateParam1 there are two values defined – valueA and valueB then in each property value:

• the string [StateParam1] will be replaced with strings valueA or valueB ,
• the string [stateparam1] will be replaced with strings valuea or valueb , and
• the string [STATEPARAM1] will be replaced with strings VALUEA or VALUEB

While the game is running, no information about state parameterization is known. Before the game starts, all parameterized states are replicated with states with same characteristics as they would be created without use of state parameterization. Therefore each of the replicated states needs a unique name and the only way to achieve this requirement is to embed each of the state parameters in the name of the parameterized state, so that all of the replicated states do not contain the parameter values as part of their names. For example the 'walk' state after adding the parameters 'Stance' and 'Item' has to be renamed into something similar to 'walk_[stance][item]'. If there were two values for the 'Stance' parameter – 'Combat' and 'Crouch', and for the 'Item' parameter there are two values as well – 'Pistol' and 'Rifle', then there will be four states present in the graph after the replication, with following names: _walk_combat_pistol, walk_combat_rifle, walk_crouch_pistol and walk_crouch_rifle.

Some combinations of parameter values might need to be skipped during replication of parameterized states. For this purpose there is an 'Exclude from graph' option.

Sometimes the differences in property values do not follow a pattern, neither for all nor only for some of the replicated states. In this case Template Properties and Selection Criteria properties can be individually set for any possible combination of parameter values.

Linking Parameterized States

Links in a simpler animation graph without any parameterized states are easy to understand as they simply connect exactly two different states and define only one transition between only those two states. However, in a graph where state parameterization is used, things are more complicated. Parameterized states actually represent multiple individual states. Therefore a link between two of such states does not necessary connect only two states. Depending on actual needs a link can connect:

• all states of a parameterized state to all states of another parameterized state
• all states of a parameterized state to only one state of another parameterized state
• one state of a parameterized state to all states of another parameterized state
• one state of a parameterized state to only one state of another parameterized state
• all states of a parameterized state to one non-parameterized state
• only one state of a parameterized state to one non-parameterized state
• a non-parameterized state to all states of a parameterized state
• a non-parameterized state to only one state of a parameterized state

There can even be more possibilities, if there is more than one parameter for parameterized states in the examples above...

These options are called Parameters Mapping and are part of the link properties in case of at least one of the states being connected by a link is parameterized. In such case the link can be limited, to connect only some of the source states to only some of the destination states. Limiting can be defined for each parameter of both source and destination states. There are three possible limiting options for each parameter:

• not limited – the link connects all state variations created by that parameter
• single value – the link connects only states matching a specified parameter value
• opposite side parameter – the link connects only states where the value of this parameter is equal to the value of a specified parameter of the state on the opposite side of the link

Note that the last option is only available for links connecting two parameterized states.

By default when a new link is created the link is not limited on any of the parameters and connects all possible variations of the source to all possible variations of the destination state, except in case when both source and destination states are parameterized with a parameter named with the same name. In this case the link will be limited to connect only source states where the value of that parameter is equal with the value of the same parameter of the destination state.

Variational Inputs

The variational input system is useful in case that you want to variate the animation played in a single state according to the game context. So you don't have to create many states for the same effect. A simple animation graph and less run-time overhead also. You can specify which animation should be played in a context on the code.

Somewhat similar to the state parameterization, you can use this by some formatting on the state name, but in this time use {} instead of []. For example, a state name can be 'x_Idle{ContextualAction}nw'_. And you can specify an *'idle{ContextualAction}_nw'\ as its animation.

And in some game code, you can specify the real value for the {} part using a following method on an IAnimationGraphState object.

bool SetVariationInput( const char* name, const char* value );

Views

Views are used by the UI to present the states and links between them in some visual order. Multiple views per animation graph can exist. Each state can appear in any number of views, but not more than once per view.

Additionally, views are used to manipulate the links between states. Adding, removing and editing of the links can only be done in a view.

Only links between the states shown within the same view will be visible - links coming from or going to states not shown in the view will be invisible unless the connected state is being added to the same view.

UI Reference

Overview

The main application menu option View > Open View Pane > Animation Graph opens the animation graph editor in a popup window. The position and arrangement of the window just before closing will be remembered and used when the window is opened again.

The animation graph editor consists of the main view (big gray area in the middle of the window), a short menu bar, a status line and several tool windows listed in this table:

Each of these windows can be arranged within the Animation Graph editor. Closed windows can be reopened using the View menu.

Menus

Main Menu

Context Menus

Note: This context menu is displayed only by right-clicking the small circle in the middle of a link line. Cursor shape changes to indicate that the mouse pointer is inside the circle.

Main View

The main view displays the contents of the selected animation graph view – the states added to that view and all the links between them.

Animation graph states are represented as rectangular bars filled with states' names. Bar's background is colored green, yellow or red depending on state type or cyan when selected in UI. This is the description of all colors sorted by priority (highest on top):

• Cyan – a state selected in UI
• Red – a disabled state (a non-'Included in game' state)
• Green – a selectable state
• Yellow – a non-selectable state

The states associated with an animation additionally can be displayed (depending on chosen toolbar option) with an icon next to the bar showing the middle frame of the animation.

Links are displayed as curved lines connecting two different states, with an arrow at one of its ends. The arrow is pointing towards the destination state. At the middle of the line a small circle shows the place where the link can be right-clicked to open the context menu. Links with Force-follow chance property set to a non-zero value will display that value next to the circle.

Using the Main View

Only one view can be displayed at a time. To display a view its name should be selected either in the list of existing views in the States window ( Views section), or by choosing one of the views listed under Find in Views context menu of the selected state. Any newly created view gets activated and shown automatically. Initially the views are empty – they contain no states.

Drag-dropping a state from the list of existing states into the main view would include that state in the selected view. It can be removed from the view using state's context menu.

Clicking on a state in the view with the left mouse button selects that state. Dragging the left mouse button starting from some empty area within the view would show the selection rectangle and releasing the button would select all states within the rectangle.

Clicking left mouse button anywhere in the empty area of the view deselects all selected states.

When selecting a state (or multiple states) all previously selected states get unselected unless the user had pressed the Control key when the other state(s) is/are selected.

The position of the state can be adjusted by dragging it with the left mouse button to any other location within the view.

Dragging a state with the left mouse button and Shift key pressed would show a link line leading from that state to the mouse pointer. Releasing the button over some other state in the view creates a new link from the source to the destination state. Doing the same but with the Alt key pressed instead of the Shift key, creates a link with force-follow chance already set to 1.

Animation graph view contents displayed in the main view can be zoomed in and out using the mouse wheel. The contents can also be scrolled in all directions by dragging the mouse using the middle or the right mouse button.

States Window

All states, views and inputs defined in the opened animation graph are listed by name in the States window. It's a tree view UI control where States, Views and Inputs are three main branches in it.

States are represented with three different icon types:

• Red – used for non-'Included in game' states,
• Yellow – used for non-selectable states,
• Green – used for selectable states. Additionally the state's icon contains a star if the state is not a null state.

The names of states used as parents for any other state are displayed in bold font.

The views are displayed always with the same icon.

The inputs are displayed with three different icons depending on their type:

• Green – used for inputs of type integer,
• Blue – used for input of type float,
• Red – used for inputs of type key.

Using the States Window

The states listed in the window can be selected by selecting their name from the list. The state will be highlighted in the main view if the state is present in the selected animation graph view. Also if the state isn't visible the view will automatically scroll showing the state in the center. The properties of the selected state will be displayed in the State Editor window and its parameterization options in the State Params window. If there's an animation associated with the selected state it will be played in the Preview window.

The states can be drag-dropped into the main view in order to add them in the selected view.

Selecting a view from the list activates that view in the main view and shows its properties in the State Editor window.

Selecting an input from the list shows its properties in the State Editor window.

There's a context menu for the states in the list, but not for the views and inputs.

States Editor Window

States Editor window shows the context sensitive common commands and the properties of a selected state (or multiple states), link, view or input.

Property values that contain the name of a parameter enclosed in brackets will get modified for different state variations. The brackets and the name will be replaced with actual values at loading time, while the rest of the string value remains unmodified. Multiple parameters can be used in one single property value. Most important is to use all parameters in the name of the state so each state variation can have a unique name. Each parameter can be used in three different forms. Here's the list of the available parameter strings used for replacement in property values (assuming the parameter name is ExampleName):

• [ExampleName] – will be replaced with unchanged values.
• [EXAMPLENAME] – will be replaced with values converted to uppercase.
• [examplename] – will be replaced with values converted to lowercase.

For a parameterized state the State Editor window shows customized values for properties of a single or multiple parameter values and combinations (depending on selected parameter values in the State Params window). If multiple state variations are selected at same time and not all property values are equal for each of them then the text Different Values Selected is displayed. Only the Template Properties and the Selection Criteria can be customized for a specific or a range of parameter values.

States Editor window shows additional properties for the links connecting at least one parameterized state. For each parameter of the parameterized states one property defines how the link is restricted in respect of that parameter. There are basically three different options for these properties:

• Empty – the link is unrestricted by that parameter. The link connects all existing state variations on this side with the available state variations on the other side of the link. The other side may or may not be restricted.
• A parameter value – the link on this side is restricted to connect only state variations matching one particular parameter value.
• A parameter name of the state on the other side in brackets – the link is restricted to connect state variations only when the value of this parameter matches the value of one particular parameter of the state on the other side of the link.

When a new links is created between two parameterized states and one or more of their parameters parameters are named same in both states then the link will be by default restricted to connect state variations only when the values of those parameters are equal. Regarding all other parameters the link will be unrestricted.

State Params Window

Parameters of the selected state are displayed in the State Params window. The window allows easy manipulation of parameters and their values. It also serves as state variation selector so that properties of each state variation can be customized, or the animation for a state variation previewed.

Each parameter of the selected state is displayed with its name and a list of defined values for that parameter. There's also one additional entry in the list of values – [All], which is highlighted by default indicating that the State Editor window is showing the properties for all state variations, at least regarding that parameter.

The State Params window displays no parameters when a non-parameterized state is selected.

Using the State Params Window

The Add Param button can be used to add a new parameter to the selected state. The user must enter a unique parameter name. After that the parameter will be displayed in the window with an empty list of values. The list has a context menu which can be used to add new (unique) values and to rename or delete the values. The rename value dialog box also appears on double-clicking a value.

The parameters can be renamed by simply typing their new name in the edit box where their name is displayed. Parameters can be removed by deleting their name.

Any particular state variation can be excluded by selecting that combination of parameter values and marking the check box 'Exclude from Graph'. The check box also shows is the selected state variation excluded or not. In case when more than one variation is selected it might be grayed out which indicates that some but not all of the selected state variations are excluded from the graph.