Location: Assets/Plugins/Animancer/Examples/10 Animation Jobs/02 Damping

Recommended After: Two Bone IK

Learning Outcomes: in this example you will learn:

How to apply physics based drag to some of a character's bones.

How to use the DampingJob from the Animation Jobs Samples.

This example demonstrates how the DampingJob from the Animation Jobs Samples can be used with Animancer to apply physics based drag to some of a character's bones. That would normally be useful for things like hair or a tail, but since we don't have a character with those this example will just apply the effect to an arm of the DefaultHumanoid and the legs of the SpiderBot.

Pro-Only Features are used in this example: Animation Jobs. Animancer Lite allows you to try out these features in the Unity Editor, but they're not available in runtime builds unless you purchase Animancer Pro.

Summary

• Jobs can't use reference types such as arrays, but if you need them you can use NativeArrays instead.
• You need to Dispose any NativeArrays you create when you're done with them.
• You can add any IDisposable objects to the animancerComponent.Playable.Disposables list and Animancer will Dispose them when that object is destroyed.
• The job in this example could be used in a real project, however the Animation Rigging package contains a much better Damped Transform system which also uses Animation Jobs and can be used alongside Animancer without any modification.

Overview

This example uses two new scripts:

• The Damping component applies drag to one limb, so the SpiderBot has 4 of them.
• Each Damping adds a DampingJob to Animancer's PlayableGraph, which is where the actual drag algorithm is implemented.

It also reuses the MouseDrag script from the Puppet example.

Job Script

using Unity.Collections;
using UnityEngine;
#if UNITY_2019_3_OR_NEWER
using UnityEngine.Animations;
#else
using UnityEngine.Experimental.Animations;
#endif

public struct DampingJob : IAnimationJob
{
    public TransformStreamHandle rootHandle;
    public NativeArray<TransformStreamHandle> jointHandles;
    public NativeArray<Vector3> localPositions;
    public NativeArray<Quaternion> localRotations;
    public NativeArray<Vector3> positions;
    public NativeArray<Vector3> velocities;

    /// <summary>
    /// Transfer the root position and rotation through the graph.
    /// </summary>
    /// <param name="stream">The animation stream</param>
    public void ProcessRootMotion(AnimationStream stream)
    {
        // This was in the original sample, but it causes problems if the character is a child of a moving object.
        // There is no need for this method to do anything in order to support root motion.

        //// Get root position and rotation.
        //var rootPosition = rootHandle.GetPosition(stream);
        //var rootRotation = rootHandle.GetRotation(stream);

        //// The root always follow the given position and rotation.
        //rootHandle.SetPosition(stream, rootPosition);
        //rootHandle.SetRotation(stream, rootRotation);
    }

    /// <summary>
    /// Procedurally generate the joints rotation.
    /// </summary>
    /// <param name="stream">The animation stream</param>
    public void ProcessAnimation(AnimationStream stream)
    {
        if (jointHandles.Length < 2)
            return;

        ComputeDampedPositions(stream);
        ComputeJointLocalRotations(stream);
    }

    /// <summary>
    /// Compute the new global positions of the joints.
    ///
    /// The position of the first joint is driven by the root's position, and
    /// then the other joints positions are recomputed in order to follow their
    /// initial local positions, smoothly.
    ///
    /// Algorithm breakdown:
    ///     1. Compute the target position;
    ///     2. Damp this target position based on the current position;
    ///     3. Constrain the damped position to the joint initial length;
    ///     4. Iterate on the next joint.
    /// </summary>
    /// <param name="stream">The animation stream</param>
    private void ComputeDampedPositions(AnimationStream stream)
    {
        // Get root position and rotation.
        var rootPosition = rootHandle.GetPosition(stream);
        var rootRotation = rootHandle.GetRotation(stream);

        // The first non-root joint follows the root position,
        // but its rotation is damped (see ComputeJointLocalRotations).
        var parentPosition = rootPosition + rootRotation * localPositions[0];
        var parentRotation = rootRotation * localRotations[0];
        positions[0] = parentPosition;
        for (var i = 1; i < jointHandles.Length; ++i)
        {
            // The target position is the global position, without damping.
            var newPosition = parentPosition + (parentRotation * localPositions[i]);

            // Apply damping on this target.
            var velocity = velocities[i];
            newPosition = Vector3.SmoothDamp(positions[i], newPosition, ref velocity, 0.15f, Mathf.Infinity,stream.deltaTime);

            // Apply constraint: keep original length between joints.
            newPosition = parentPosition + (newPosition - parentPosition).normalized * localPositions[i].magnitude;

            // Save new velocity and position for next frame.
            velocities[i] = velocity;
            positions[i] = newPosition;

            // Current joint is now the parent of the next joint.
            parentPosition = newPosition;
            parentRotation = parentRotation * localRotations[i];
        }
    }

    /// <summary>
    /// Compute the new local rotations of the joints.
    ///
    /// Based on the global positions computed in ComputeDampedPositions,
    /// recompute the local rotation of each joint.
    ///
    /// Algorithm breakdown:
    ///     1. Compute the rotation between the current and new directions of the joint;
    ///     2. Apply this rotation on the current joint rotation;
    ///     3. Compute the local rotation and set it in the stream;
    ///     4. Iterate on the next joint.
    /// </summary>
    /// <param name="stream">The animation stream</param>
    private void ComputeJointLocalRotations(AnimationStream stream)
    {
        var parentRotation = rootHandle.GetRotation(stream);
        for (var i = 0; i < jointHandles.Length - 1; ++i)
        {
            // Get the current joint rotation.
            var rotation = parentRotation * localRotations[i];

            // Get the current joint direction.
            var direction = (rotation * localPositions[i + 1]).normalized;

            // Get the wanted joint direction.
            var newDirection = (positions[i + 1] - positions[i]).normalized;

            // Compute the rotation from the current direction to the new direction.
            var currentToNewRotation = Quaternion.FromToRotation(direction, newDirection);

            // Pre-rotate the current rotation, to get the new global rotation.
            rotation = currentToNewRotation * rotation;

            // Set the new local rotation.
            var newLocalRotation = Quaternion.Inverse(parentRotation) * rotation;
            jointHandles[i].SetLocalRotation(stream, newLocalRotation);

            // Set the new parent for the next joint.
            parentRotation = rotation;
        }
    }
}

Responsibilities

Since the original Damping script was just a sample, it had most of the same problems with Responsibilities as the Two Bone IK example which are again fixed in this example's implementation. The following table compares the differences between the original and the Damping script used in this example, excluding any that were already covered by the Two Bone IK example:

Fields

As with the Two Bone IK example, inserting the job into Animancer's PlayableGraph allows multiple instances to be applied to the same character so we are applying one to the DefaultHumanoid's LeftHand and one to each of the SpiderBot's 4 legs. Their Bone Counts are all set to 3 since we want to affect the Hand, Elbow, and Shoulder of the DefaultHumanoid and the corresponding leg bones on the SpiderBot.

Code	Inspector
[SerializeField] private AnimancerComponent _Animancer; [SerializeField] private Transform _EndBone; [SerializeField] private int _BoneCount = 1;

Initialization

Unity's Animation Job system allows you to write high performance multithreaded code to access low-level data in the animation stream, but to do so it has to enforce several restrictions on the type of code you can use. One of the restrictions is that you can't use Reference Types in them. That means two things for this example:

• Instead of using regular arrays (Vector3[]) we need to use Unity's native arrays (NativeArray<Vector3>).
• Instead of being able to directly reference the bone Transforms we want to apply the damping effect to, we need to use TransformStreamHandle.

A NativeArray needs to be allocated with a specific length (_BoneCount) just like a regular array, but also has two additional parameters:

1. The Allocator parameter can be used to allocate a temporary array which Unity will automatically clean up and reuse after a few frames. But in this case, we want Persistent arrays that will last for the entire lifetime of the job. This also means we will need to Dispose the arrays to avoid leaking memory.
2. The NativeArrayOptions parameter determines if the allocated memory needs to be cleared or not. Most of them can use UninitializedMemory which is faster because we will be immediately filling them, but the velocities need to use the default ClearMemory to make sure all the values start at zero.

Since we are about to use those values several times, we can shorten the following lines a bit by using constants for them:

private void Awake()
{
    const Allocator Persistent = Allocator.Persistent;
    const NativeArrayOptions UninitializedMemory = NativeArrayOptions.UninitializedMemory;

    var job = new DampingJob()
    {
        jointHandles = new NativeArray<TransformStreamHandle>(_BoneCount, Persistent, UninitializedMemory),
        localPositions = new NativeArray<Vector3>(_BoneCount, Persistent, UninitializedMemory),
        localRotations = new NativeArray<Quaternion>(_BoneCount, Persistent, UninitializedMemory),
        positions = new NativeArray<Vector3>(_BoneCount, Persistent, UninitializedMemory),
        velocities = new NativeArray<Vector3>(_BoneCount, Persistent),
    };

The above syntax is called an Object Initializer which is simply a neater way of initializing an object. We could have done the exact same thing using:

var job = new DampingJob();
job.jointHandles = ...;
job.localPositions = ...;
// Etc.

Once the arrays are allocated, we can fill all their values for each bone starting at the _EndBone and going up each of their parents in the Hierarchy up to the specified _BoneCount. As mentioned earlier, we can't use direct Transform references so we use the AnimatorJobExtensions.BindStreamTransform extension method to get a TransformStreamHandle to allow the job to access them.

    var animator = _Animancer.Animator;
    var bone = _EndBone;
    for (int i = _BoneCount - 1; i >= 0; i--)
    {
        job.jointHandles[i] = animator.BindStreamTransform(bone);
        job.localPositions[i] = bone.localPosition;
        job.localRotations[i] = bone.localRotation;
        job.positions[i] = bone.position;

        bone = bone.parent;
    }

After the last bone, the job also needs a handle for its parent to use as the root:

    job.rootHandle = animator.BindStreamTransform(bone);

And now that the job has everything it needs, we can give it to Animancer:

    _Animancer.Playable.InsertOutputJob(job);

Disposal

As mentioned earlier, using Allocator.Persistent for the NativeArrays means we need to Dispose them when we are done with them to free up the memory that was allocated for them so we don't leak memory (and Unity will give you a warning if you fail to do so). The original sample used an OnDisable method to Dispose its arrays, but with Animancer you can simply add them to the AnimancerPlayable.Disposables list and it will Dispose them for you.

    _Animancer.Playable.Disposables.Add(job.jointHandles);
    _Animancer.Playable.Disposables.Add(job.localPositions);
    _Animancer.Playable.Disposables.Add(job.localRotations);
    _Animancer.Playable.Disposables.Add(job.positions);
    _Animancer.Playable.Disposables.Add(job.velocities);
}

Note that NativeArrays will cause an error if you Dispose them multiple times, so if we were writing our own job (rather than just using the sample) and we wanted to be able to disable it separately from the destruction of Animancer's PlayableGraph, we could have the job implement the IDisposable interface to dispose its arrays so that we would only have to call ...Add(_Job); here. Then inside the job's Dispose method, we could check the IsCreated property of each array before destroying it to avoid that error.

Validation

As noted in the Responsibilities table, replacing the original sample's array of Transforms with a single _EndBone makes the script easier to use and ensures that you can't assign an invalid set of objects. We can make the script even safer by adding an OnValidate method which the Unity Editor will call whenever any of its fields are modified in the Inspector:

private void OnValidate()
{

The first thing we want to do is ensure that the _BoneCount is at least 1 (the _EndBone itself):

    if (_BoneCount < 1)
    {
        _BoneCount = 1;
    }

Then if we have all the references properly configured we can iterate up the hierarchy from the _EndBone to ensure that the _BoneCount is smaller than the number of bones between there and the root Animator:

    else if (_EndBone != null && _Animancer != null && _Animancer.Animator != null)
    {
        var root = _Animancer.Animator.transform;

        var bone = _EndBone;
        for (int i = 0; i < _BoneCount; i++)
        {
            bone = bone.parent;
            if (bone == root)
            {
                _BoneCount = i + 1;
                break;
            }

If we reach the top of the Hierarchy without finding the root Animator, then the _EndBone is not a child of it and won't work with the DampingJob so we just clear it and log a warning:

            else if (bone == null)
            {
                _EndBone = null;
                Debug.LogWarning("The End Bone must be a child of the Animator.");
                break;
            }
        }
    }
}

Conclusion

As noted earlier, this system could be used in a real project, however the Animation Rigging package contains a much better Damped Transform system which also uses Animation Jobs and can be used alongside Animancer without any modification.