Custom Playables

Important: The Playables API is included in Unity 5.2 as an “experimental” feature, which means that we do not guarantee that the API won’t change in future versions.

Creating custom playables

The Playable API allows you to create custom playables by deriving from any of the base types. The following example shows how you can derive from the AnimationMixerPlayable to create a special kind of mixer that plays clips one after the other.

By overloading the PrepareFrame method, you can handle the nodes as desired. In this example, the goal is to have animation clips play one after the other. We change the weight of the nodes so that only one clip plays at a time, and we adjust the local time of the clips so that they start at the moment they get activated.

Similarly, Custom Playables can also implement the OnSetPlayState and OnSetTime methods, to implement custom behaviours when a playable’s state or local time has changed.

using UnityEngine;
using UnityEngine.Experimental.Director;
 
public class PlayQueuePlayable : AnimationMixerPlayable
{
    public int m_CurrentClipIndex = -1;
    public float m_TimeToNextClip;
 
    public void PrepareFrame(FrameData info)
    {
        Playable[] inputs = GetInputs();
 
        // Advance to next clip if necessary
        m_TimeToNextClip -= (float)info.deltaTime;
        if (m_TimeToNextClip <= 0.0f)
        {
            m_CurrentClipIndex++;
            if (m_CurrentClipIndex < inputs.Length)
            {
                var currentClip = inputs[m_CurrentClipIndex] as AnimationClipPlayable;
 
                // Reset the time so that the next clip starts at the correct position
                inputs[m_CurrentClipIndex].time = 0;
                m_TimeToNextClip = currentClip.clip.length;
            }
            else
            {
                // Pause when queue is complete
                state = PlayState.Paused;
            }
        }
 
        // Adjust the weight of the inputs
        for (int a = 0; a < inputs.Length; a++)
        {
            if (a == m_CurrentClipIndex)
                SetInputWeight(a, 1.0f);
            else
                SetInputWeight(a, 0.0f);
        }
    }
}

[RequireComponent (typeof (Animator))]
public class PlayQueue : MonoBehaviour
{
    public AnimationClip[] clipsToPlay;
 
    void Start ()
    {
        var playQueue = new PlayQueuePlayable();
        playQueue.SetInputs(clipsToPlay);
 
        // Bind the queue to the player
        GetComponent<Animator>().Play(playQueue);
    }
}

Playable Lifetime

When a Playable is created via the API, Unity must internally keep track of connections made to that Playable. When a new scene is loaded Unity will automatically release the resources allocated for all Playables for you.

However it is a good practice to call Playable.Dispose() explicitly when you are done with a particular Playable to ensure Unity can reuse internal resources. Playable.Dispose is analogous to managing objects via Object.Destroy();