Handling Dynamic Object References in Timelines

In this lesson, you will learn how to use Exposed References to link scene-specific objects to your Timeline assets so they function correctly even when your objects aren't part of the original Timeline asset file.

The Challenge of Prefabs and Scene Instances

When you create a TimelineAsset, it is a standalone file in your Project window. If you try to drag a game object from your current Hierarchy into a Track (like an Animation Track), Unity creates a reference. However, if that Timeline is used across different scenes or with dynamically spawned objects, the Timeline "loses" the connection because it cannot point directly to a specific object that might not exist yet.

Using Exposed References

Unity solves this via the ExposedReference<T> property. Instead of hard-coding a link, you provide a "placeholder" that the Timeline fills when it runs in a specific scene.

When you bind an object to a track, Unity creates an entry in the Exposed References list within your PlayableDirector component. At runtime, the PlayableDirector uses the IExposedPropertyTable to look up the object based on its unique key.

Scripting Example

If you are writing a custom track or managing references via code, you use ExposedReference like this:

[System.Serializable]
public class MyCustomBehavior : PlayableBehaviour
{
    // This allows the inspector to show a field for scene objects
    public ExposedReference<GameObject> targetObject;

    public override void ProcessFrame(Playable playable, FrameData info, object playerData)
    {
        // Resolve the reference using the current playable's context
        GameObject target = targetObject.Resolve(playable.GetGraph().GetResolver());

        if (target != null)
        {
            // Perform your logic here
            target.transform.position += Vector3.up * Time.deltaTime;
        }
    }
}

By using .Resolve(), the Timeline asks the PlayableDirector to find the specific instance of the object present in the current scene. This ensures your cinematic sequences remain modular—you can swap out the "Hero" or "Enemy" object in different scenes without needing to create a separate Timeline asset for every variation.

Key Takeaway: Exposed References decouple your Timeline logic from specific scene instances, allowing you to dynamically map objects to your tracks at runtime via the PlayableDirector’s resolver.