Animation Editor: Nodes

From Bohemia Interactive Community
Jump to navigation Jump to search

An animation node is a fundamental block of an animation engine. Each node has a single (and simple) purpose. By connecting these nodes to one big hierarchy, complex behaviour can be achieved. Usually the hierarchy is organized top to bottom, connecting parent nodes to child nodes.

Each node is displayed as a small rectangle, first line tells us the node type, second line contains node name. The name has to be unique, which is used as a reference when linking to it from other nodes. Naming is case sensitive.

Slots, which can be found at the bottom of some node types, serve to connect a node to any child node.


Animation Graph Evaluation

Imagine the evaluation as a process happening in two phases.

DOWN. Animator and character programmer agree on "master" (main, topmost) node. The animation graph evaluation starts at this node and continues to child nodes. Logic in animation nodes affects which child paths are evaluated and which are ignored. This way the evaluation traverses from topmost node to bottom of the graph.

UP. Once there are no valid child nodes where to continue the search, the evaluation returns back, carrying an animation pose as a result. This pose can be blended with other poses returned from different child paths or for example.

(SIMPLIFIED. Logic is evaluated from top to bottom, left to right. Results (animation poses) are passed to parent node until they reach the topmost node.)

Order of evaluation is important, because it affects values used in conditions and other expressions. For example, when using tags, remaining time or events in an expression, it must be checked after all child nodes are evaluated, otherwise these values are still unknown.


Time and Timing

One of the inputs of an animation node is a time. Time is for advancing animations, essentially - playing the animations. The node usually passes this time to linked child nodes, however, some node hold their own clock. There are two ways to measure time:

  • Real time. Time as we know it, it advances forward.
  • Normal time. Time used to synchronise animations. It scales between synchronization points, so multiple animations can be blended nicely.
Read more about Syncing Animation: Animation Editor: Sync Tutorial.


Node Types

Common Properties

Property Description
Node Name Unique node name, case sensitive.
Tags User defined tags. Tags are returned together with resulting pose. Game code can read the returned tags and react to them.
Child Link to child node/multiple children

Source InLoopOut

Used to play animations. Samples a pose from the linked animation. This pose is passed to parent node as a result.

Animation is composed of three parts.

  • Intro
  • Loop (surrounded by In Event and Out Event)
  • Outro

Loop part keeps repeating until a condition is satisfied.

Property Description
Source Source id selecting an animation from Anim Set (Group.Column.Line or Group.Line when relying on a Group Select node)
In Event Marks the start of the loop
Out Event Marks the end of the loop
End Expr Condition which interrupts the loop and continues to outro.

Source

Used to play animations. Samples a pose from the linked animation. This pose is passed to parent node as a result.

Property Description
Source Source id selecting an animation from Anim Set (Group.Column.Line or Group.Line when relying on a Group Select node)
Loop loop: Loops the animation

noloop: Doesn't loop the animation

Source Sync

Used to play synced animations. Samples a pose from the linked animation. This pose is passed to parent node as a result. Normalized times are used for synchronization, read more in Animation Editor: Sync Tutorial.

Property Description
Source Source id selecting an animation from Anim Set (Group.Column.Line or Group.Line when relying on a Group Select node)
Loop loop: Loops the animation

noloop: Doesn't loop the animation

Sync See Animation Editor: Sync Tutorial.

Pose

Used to sample a pose from an animation. Unlike Source node, Pose node does not play the animation. Animation frame is computed from variables.

Pose node can blend between two closest frames when the variable value falls between them.

Example usage: steering in a vehicle, having all steering poses in one animation and using a variable to select a pose to be played.

Property Description
Source Source id selecting an animation from Anim Set (Group.Column.Line or Group.Line when relying on a Group Select node)
Time 0 to 1, where 0 maps to the first frame of animation, and 1 maps to the last frame of animation

Pose 2

Pose 2 node is similar to Pose node, but it works in two dimensional space.

Example usage: Aim Spaces and Look Animations - mapping horizontal and vertical direction to a pose.

Property Description
Source Source id selecting an animation from Anim Set (Group.Column.Line or Group.Line when relying on a Group Select node)
Value Y Expression for the Y direction
Value X Expression for the X direction
Table Table which maps X and Y values to frames, details here

State Machine

State machines contain multiple state nodes and transitions between them. Only one state per state machine is active in any frame unless a transition with a duration attribute bigger than 0.0 has been fulfilled. State machine tries to switch to new state on every frame, if any condition on transition is fulfilled.

Blend

Used to blend between two child nodes. Blend node supports both "normal" and "additive" blending and required no further setup for that manner, since every animation track already contains information whether it is additive.

Blending is immediate - based on a value or variables. Blending weight can change rapidly between frames, no time-based blending is done.

Property Description
Weight Expression (0.0 - 1.0)

0: 100% 1st child

0.5: 50% 1st, 50% 2nd child

1: 100% 2nd child

If this needs to be dynamic and controllable, create a float variable and use it in this expression.

For example or even bit more complicated usage is possible

Optimize Min/Max If Min is unticked, 1st Node will always play

If Max is unticked, 2nd Node will always play

This also makes the unchecked side multiplied,

so a 2 will make 2nd Node play multiplied

(as 1 is maximum, normally)

Note: If the main pose is set as 1st Node and an additive animation as 2nd Node, simply untick Optimize Max and set Weight to 1.0.

This will always play the main pose, but additively play the second node.

Blend N

Used when blending between multiple child nodes. Each child node corresponds to one threshold value.

Can be useful for example when blending between different directions of walking animations (0-360).

Blending is immediate - based on a value or variables. Blending weight can change rapidly between frames, no time-based blending is done.

Property Description
Blend Weight Expression. Value which controls the blending between two thresholds (=two child nodes).
Blend Fn Shape of blending curves between particular thresholds. Use Lin in order to avoid curves.
Is Cyclic Enable cyclic behavior (first threshold is identical to last, even with different values). Tick and add another Threshold at the end of Thresholds

that corresponds to the first Input Link (for example, threshold would be -180,-90,0,90,180 when doing directional animations)

Children Links to child nodes.
Thresholds Each child nodes corresponds to one threshold, thresholds must go from lower to higher values.

Blend T

Blend T Add

Used to blend between two child nodes over time - unlike other blend nodes. When a condition is met, Blend T starts blending towards the other child node over time.

Blend T Add always plays the main child node and the second child pose is blended with it. Condition in Blend T Add is always evaluated after main child node but before second child node.

Property Description
Blend Time Blending time between child nodes in seconds.
Blend Fn Shape of blending curves between particular thresholds. Use Lin in order to avoid curves.
Trigger OnTrigger Off Trigger On switches from first to second, Trigger Off switches back to first. Both have to be filled, otherwise Condition is used.
Condition If Triggers are empty, condition serves as a switch between child nodes. When false, first child node is active, when false, second child node is active.
Post Eval If Post-Eval is set to true, triggers or conditions are evaluated after child nodes. This is required when expressions refer to tags or events returned by child nodes.

Condition in Blend T Add is always evaluated after main child node but before second child node.

Group Select

Used to select a Column in a Group in Anim Set. If any Source Node below selects an animation by source id in following format:

Locomotion.WalkF

Then the Column is injected and new animation source id is formed by the Group Select between these, to form:

Locomotion.Erc.WalkF

Property Description
Group Defines in which anim set group the column is selected
Column Defines which column of the Group should be selected

Queue Node

Queue node provides solution when queueing up animations and playing them on top of main animation, such as a gestures or other actions.

This can be used for both additive and full body animations, where the full body will override the main link, and the additive animation will play on top of the main link.

Property Description
Main Link Link to "main" child node which is played (evaluated) all time
Items Press + to add new items, - to remove.

Each item links to a child node and has the following properties:

Property Description
Start Condition Condition to start playing this item
Interrupt condition (optional) Interrupt (stopping) condition for this item
Start Time (optional) Starting time to be pushed to child node when this item becomes active
In Time Time it takes to blend into this item (default 0.3 sec)
Out Time Time it takes to blend out of this item (default 0.3 sec)
Interruptible Tick to make other queue items in this node

able to interrupt this specific item

Buffer Save

Buffer Use

Buffer Save stores current animation buffer aside under chosen name. Stashed buffer can be used (loaded) later.

Buffer Use loads a stashed buffer with matching name, replacing current animation buffer.

This node might be slightly more complex than it seems. Please refer to the Absolute & Differential Animations and Buffer Nodes article for further details.

Var Update Node

Var Update node is able to remember values of chosen variables and can keep their values fixed for child nodes below. Updates of remembered values can be turned on/off in different situations:

  • On Init: Update remembered values when the Var Update node becomes active
  • On Main Path: Update remembered values when the Var Update node lies on main path (is active)
  • On Blend Out: Update remembered values when blending out.

Unticked situations keep the values fixed.

Example Usage:

This node is used when are blending from one state to another that is using the same internal variable, such as direction or speed.

Say, the character is moving towards left (-90) and wants to switch to going right (-90). Normally the Direction variable would go from -90 to 90 immediately, and the character would then do an unnatural skip between these two.

The game could gradually blend from -90 to 0 to 90, but then the character would be forced to interpolated direction for a short time.

This Var Update Node can bypass that by saving the old variable value (-90) to the old state and pass new variable value (90) to new state while the states are blending from one into another.

Rotation Node

Rotation node provides procedural rotation (or even translation) of bones according to expression.

Property Description
Expression This is the expression the node will use to evaluate the bones listed below
Bones Each item affects one bone.
Property Description
Bone What bone to manipulate
Axis Which axis to rotate around
Space This defines which space the manipulation will happen in:
  • Local - Rotate in local space of a bone = use axes of the bone
  • Model - Rotate in a model space = use axes of character
  • Parent - Rotate in a space of parent bone = use axes of parent bone
Op This defines what operation will be used for the manipulation:
  • Rotate - rotate the bone around its origin
  • RotateAround - not implemented (???)
  • Translate - translate the bone, only local space manipulation is implemented
Amount Multiplier for the expression.

Example: Amount is 90 and Expression goes for example from -2 to 2. Rotation of this bone then goes from -180 to 180.

IK2 Target

IK2 Target saves transforms of end effectors for later use by IK2 node.

Property Description
Chains For each chain, model space positions and rotations of their end effectors are computed. Then, end-effector transform is saved under Ik Target identifier.

Ik Target can be used later in IK2 nodes.

Property Description
Ik Target identifier of transform
Ik Chain Selects the chain of bones (chains are defined for entire graph in anim workspace).

Position and rotation are set from current transform of end effector of this chain. Additional offsets are applied (see below).

Parent Offset Pos Offset applied to chain in model space (parent to chain, not affected by chain hierarchy)
Target Offset Pose Source id of an animation pose. This pose is used to set the local offset from chain's end effector. Serves probably better than guessing transform numbers.

Note: column/group selects apply here same way as in source nodes.

Example: constraining the left hand to first person camera, a pose with two bones in world space got exported - bones were head and left hand. These two bones then describe the offset where to place an IK target.

Target Offset Pose From Bone Measured offset from bone of this name...
Target Offset Pose To Bone ...to bone of this name.
Target Offset Pose In Model Space When checked, the pose is in model space and does not need to accumulate bones from local space. When possible, try to have this turned on, it helps performance.
Target Offset Pos Child offset applied to end effector of chain (this offset is affected by chain hierarchy)
Target Offset Rot Rotation offset applied to end effector of chain, in euler angles (this offset is affected by chain hierarchy)

IK2

IK2 computes inverse kinematics on a chain of bones to reach a specific target.

Property Description
Weight Weight, 0-1. When zero, no IK is applied, when one, IK is fully applied.
Snap Rotation Snap the rotation of end effector to be the same as ik target rotation.
Chains List of chains and their IK targets.
Property Description
Ik Target identifier of target transform, supplied by IK2 Target or by game code
Ik Chain selects the chain of bones (chains are defined for entire graph in anim workspace)

IK2 Plane

IK2 computes inverse kinematics on a chain of bones to reach a specific target plane. Target planes are set by application (character/gameplay programmers).

Property Description
Weight Weight, 0-1. When zero, no IK is applied, when one, IK is fully applied.
Active Distance Distance which the IK is applied from. If the chain of bones is further, no IK is applied even when weight is one. In meters.
Threshold smoothness Smoothing the "edge" of active distance to turn on IK continuously. In meters.
Custom Rotation When zero, IK2 Plane pushes the end effector along the normal of plane. In some situations it may be feasible to move it in a custom direction, for example pushing up when correcting feet by IK.
Snap Rotation Snap the rotation of end effector to be the same as ik target rotation.
Chains List of chains and their IK targets.
Property Description
Ik Target identifier of target transform, supplied by game code
Ik Chain selects the chain of bones (chains are defined for entire graph in anim workspace)

IK Rotation

Animation node applying inverse kinematics to reach target rotation. Position is untouched. Useful for spine inverse kinematics instead of counter-animating hip rotations.

Property Description
Weight Weight, 0-1. When zero, no rotations are applied, when one, rotations are fully applied.
Chains List of chains and their IK targets.
Property Description
Ik Target identifier of target transform, supplied by IK2 Target or by game code
Ik Chain selects the chain of bones (chains are defined for entire graph in anim workspace)

Weapon IK

This node is used for weapon related pose corrections and inverse kinematics.

  • Compares current weapon direction with desired direction
  • Rotates weapon to correct direction
  • Snaps primary and secondary chain (arms) onto weapon
Property Description
Config Name This defines what the IK setup is called
Config Configuration of IK node.

Binding to names of joints of primary/secondary chain.

Select which joint axes match with chain orientation.

Aim On set to true when the character is aiming
  • then it aligns the weapon orientation with inputs Weapon Dir LR and Weapons Dir UD
  • it also force enables IK on primary chain
Prim On set to true to enable IK on primary chain

(usually right arm)

Sec On set to true to enable IK on secondary chain

(usually left arm)

Blend Time Blending time for changes of "Aim On", "Prim On"

and "Sec On".

(how long it takes to blend from/into aiming state

or primary state or secondary state)

Weapon Dir LR Angle Horizontal aiming angle, used for aligning the weapon

when Aim On is set to true.

Weapon Dir UD Angle Vertical aiming angle, used for aligning the weapon

when Aim On is set to true.

Switch Node

This node enables switching between multiple sources which variable chances between each source.

Property Description
Use NTime This defines whether to use normalized time when evaluating the sources
NTime Cycle
🚧
TODO: this must be updated.
Items
Property Description
Link This defines what node this item is connected to
Start Cond This defines what this item's start condition is
Next This defines what item should have a certain chance

at playing after this item has looped:

40%=0, 10%=1, 10%=2, 10%=3, 10%=4, 10%=5, 10%=6

The snippet is from item 0, where it has a 40% chance

of replaying the same source, and an equal 10%

to play another animation.

Attachment

Attachment node provides dynamic link to a different graph.

The attachment is provided by the game and attachment node picks it by the binding name. Link may lead to different animation graph with different animation instance.

Attachment nodes are useful for example for weapons, vehicles, animation modding...

Attachments can be inserted for debugging in the animation editor through Attachments Debug window:

Property Description
Binding name Name of the attachment.
Fixed Attached animation graph and instance are bound once the node starts playing. The binding is reset only when the node stops playing.

Event

Event node fires a set of animation events once the node becomes active.

This is useful when we need to signal other parts of engine or game code that a branch in animation graph became active. (for example, audio engine can react to stance changes)

  • Fill in the expression to limit when the event is triggered.
  • Empty expression means that the event is triggered every time.
  • Event can be triggered on node init only or on every time the node is updated.


See Also