Animation clip (AtomsUnreal)

Animation clip in Unreal are defined as Animation Sequence Assets.

Usually Animation clip files can be exported with Atoms Crowd with the provided tools. These files can be imported into Unreal later.

Alternatively you can use native Animation Sequence Assets and add an "Atoms Anim Clip User Data" to your Animation Sequence.

Users can edit their Animation Sequences normally, but they will need to edit the "Atoms Anim Clip User Data":

Clip Name, the name of the animation clip.
Additive Mode, the additive mode for this clip. The additive mode can be: "None", "Bind" or "Reference". If None, this clip plays has a normal clip. If Bind, this clip will be evaluated as the difference of the animation values of the given file and the bind pose. If Reference, you will have to provide a reference clip file, this clip will be evaluated as the difference of the two clip files. Additive clips are used only within a state machine.
Blend Frames After foot up, the number of frames used for blending after the foot leaves the down state.
Loop, if the clip is a loopable clip. When this is off the animation clip becomes a "one-shot clip". This will affect the behaviour of any state (state machine) using this clip.
Loop Start and Loop End frames of your clips.
Loop Blend, the number of frames used to blend when looping.
Disable Foot Lock, If this option is on, the foot lock system will be disabled when playing this clip.
Direction type: static, pelvis, joints or clip. Static: the clip will use as direction to the vector specified in the Direction field. Pelvis: the clip will use the pelvis velocity as direction. Joints: the direction of the clip will be the vector travelling from the first joint to the second joint (the joint ids are selected with the Direction Joints field). Clip: the direction is taken from the "clipDirection" metadata stored on the root pelvis joint. Local: stores the input direction (provided in the Direction field) in pelvis space (useful when blending clips oriented in different directions)
Direction, the direction used when the direction type is set to static.
Direction Joints, the two joints ids used for defining the direction vector when the direction type is set to joints. The button on the right will show a pop up dialog to help you find the right joints id for a given agent type.
Clip velocity offset, This add some velocity to the root. This is useful with clips that have only in place animation. Atoms need real root motion, so use this vector to add motion to your in-place clip.
Compatible Agent Type, the agent type compatible with this clip. This field is mandatory if you wish to retarget this clip onto a non-compatible agent type.
Virtual root motion, (only visible when the compatible agent type has a virtual root). The axis used for transferring the motion from the skeleton root to the virtual root.
Override virtual root position (only visible when the compatible agent type has a virtual root), enables the override of the virtual root position configured in the agent type.
Virtual root position (only visible when “Override virtual root position“ is on and the compatible agent type has a virtual root), the virtual root position for this clip. It overrides the virtual root position defined in the agent type.
Transitions Frames, for long clips you might have different transition frames.
Values can be entered manually by the user. If you don't specify transition frames only the loop end frame of the clip will be used. If you add an entry and set it to -1 then every frame is used as a valid transition frame. Transition Frames are used by state machines only.
Foot down data, contains a map of elements containing the foot down state for each foot.
Override Ground Height: if enabled, the feet and pelvis height will be evaluated when the asset is saved or loaded.
Ground Height: The ground height value used to calculate the pelvis and feet heights if "Override Ground Height" is on.
Joint Metadata: Use this map to add custom static metadata to some joints.
Reverse: when this option is on the animation is reversed.
Mirror: if this option is on, the clip is mirrored.
Mirror Anim Plane: the plane used to mirror all the joints without a match.
Mirror Bind Plane: the plane used to find the mirror joint pairs. It is also used to mirror the joints matched in a pair.
Side Joints Search: the method to find joint pairs. Auto: automatic search. By Name: the joint search will be based on a string replacement.
String Replacement: the string replacement when "Side Joints Search" is set to “By Name“. (i.e. "Left" "Right").
Mirror String Repl Type: specifies where to apply the string replace for the joint search: Any (any part of the name), Prefix (at the beginning of the name), Postfix (at the end of the name)
Enable Sitting, if this option is on, the sitting factor on this clip is enabled.
Sitting Factor, the sitting factor used by sit adaptation for the pelvis operator. The sit adaptation can be enabled on state machine and clip reader modules.
Enable Perching: Enable the perching feature for this clip. The perching factor can be stored as a curve on this animation sequence with the following naming convention: ROOT_NAME@12@jointPerchingFactor. The value should be between 0 and 1 and do the frame range should be the same as the animation sequence range.
Global IK, the retargeting global IK defines how to calculate the target point for the IK of the selected chain end joint. When the value is 0, the target is the default target point used by the retargeting; when the value is 1, a different method is used. The compatible agent type must be set on this clip, and it needs to have a characterization.

Evaluating foot down states

You can open the "Atoms Compute Foot Down Data" tool from the menu: Asset > Compute Atoms Foot Down

The foot down curves can be computed automatically using a foot velocity or a ground height value, after the values have been computed users can still edit the curves from within the Asset property window.

Evaluating transition frames

You can open the "Atoms Compute Transition Frames" tool from the menu: Asset > Compute Atoms Transition Frames

You can let Atoms guess the transition frames by providing a reference frame number and a threshold value. After the process is complete the Transition Frames property will be populated if any frame with a similar pose is found.

Clip Velocity

When clips are exported with Atoms Crowd supported apps, each pelvis contains metadata named "atoms_pelvisVelocity" (3D vector) which describes the velocity of each pelvis in the 3D space.

This because Atoms does not work with in-place clips, but with clips that move in the 3D space.

If you are using your own Animation Sequence assets you will have to set the "Clip Velocity Offset" attribute to add motion to your in-place clip.

Animated Joint Metadata

You can add custom animated joint metadata adding curves to your anim sequence asset. You need to follow this naming convention for the curve name: JointName__metadataType__metadataName

For example:

Spine1__INTMETADATA__foo - Adds an int metadata named foo on the joint Spine1
Spine1__DOUBLEMETADATA__foo or Spine1@float@foo- Adds a double metadata named foo on the joint Spine1
Spine1__BOOLMETADATA__foo - Adds a bool metadata named foo on the joint Spine1

For Vector2/3/4 and quaternion metadata you need to add one curve per axis

To add a vector 3 metadata you need to add these curves:

Spine1__VEC3METADATA__foo__X
Spine1__VEC3METADATA__foo__Y
Spine1__VEC3METADATA__foo__Z

The clip direction

You might wonder why you need to set a direction for your clips. This is actually quite important, in fact if you set a wrong static direction for a clip you might end up having your agents going in the wrong direction.
Also, it's important to understand that clips for a character should all share the same direction when used in a state machine, except few particular cases.

Your clip direction tells Atoms how your clip moves in space.
Atoms uses the clip direction to rotate your agent and match the actual agent direction (travelling direction) which is computed at each frame. For instance, if your clip is travelling mainly on the Z axis and you set the direction to be the X axis, you will see your agents rotated of 90 degrees on the Y axis later and they will move in the wrong direction.
Please check the Animation Clip chapter to understand better how to set up your agent direction.