Loadable<T0>

Description

Serialized reference that loads a specific T asset from registered built content on demand instead of pulling it in with direct references.

Add a Loadable<T0> field to a ScriptableObject or MonoBehaviour to reference an asset without loading it immediately. The reference is stored as a Loadable<T0>.LoadableObjectId, which you create in the Editor with LoadableObjectIdEditorUtility. When the containing object is built into a content directory with BuildPipeline.BuildContentDirectory, the referenced asset and its dependencies are pulled into the build output.

At runtime, call Loadable<T0>.Load or Loadable<T0>.LoadAsync to load the asset on demand, read it from Loadable<T0>.Target, and call Loadable<T0>.Release when it is no longer needed. The asset must belong to a content directory that has been registered with ContentLoadManager.RegisterContentDirectory.

In Play mode you can load built content with much the same code and behavior as in the Player. Register the content directory with ContentLoadManager.RegisterContentDirectory, get its root assets with ContentLoadManager.GetRootAssets, then read the Loadable<T0> fields on those root assets or on any asset or scene they reference. A Loadable<T0> reached from built content always loads its asset from that built content, never from the project.

In Play mode you can also load the live project version of an asset, such as a scene loaded by path with SceneManager.LoadSceneAsync or a ScriptableObject loaded through AssetDatabase. A Loadable<T0> field on an asset loaded this way always resolves to the latest project version of the referenced asset through the AssetDatabase, even when a registered content directory contains a built version of that asset.

Content loaded from the AssetDatabase in this way is not reference counted, so Loadable<T0>.Release does not unload it. It unloads through the same garbage collection that handles other AssetDatabase content in the Editor. The asset unloads when nothing references it and a collection runs. Call Resources.UnloadUnusedAssets to force a collection.

A Loadable<T0> field is only supported in content built with BuildPipeline.BuildContentDirectory. If a Loadable field is found in serialized data during a Player or AssetBundle build, the underlying reference is set to null in the build output and an error is logged. Suppress this error with BuildOptions.SuppressLoadableErrors for Player builds or BuildAssetBundleOptions.SuppressLoadableErrors for AssetBundle builds.

Additional resources: Loadable<T0>.LoadableObjectId, LoadableObjectIdEditorUtility, BuildPipeline.BuildContentDirectory, ContentLoadManager

using Unity.Loading;
using UnityEngine;

namespace BuildDocExamples
{
    // Synchronous example: a MonoBehaviour that references a prefab through a Loadable<T>
    // field, loads and instantiates it on demand, and releases it when the component is destroyed.
    public class Loadable_LoadAndReleaseExample : MonoBehaviour
    {
        // Assign this in the Editor. The referenced prefab is pulled into the content
        // directory when this component's GameObject is built with BuildContentDirectory.
        public Loadable<GameObject> hatLoadable;

        private GameObject equippedHat;

        public void EquipHat()
        {
            // Guard against a missing reference: if the field was never assigned in the
            // Editor, or its id is invalid, there is nothing to load.
            if (hatLoadable == null || !hatLoadable.LoadableObjectId.IsValid)
                return;

            // Destroy any previously equipped hat before loading a new one, so repeated
            // calls don't leave old instances behind in the scene.
            if (equippedHat != null)
                Destroy(equippedHat);

            // Load() blocks until the prefab is available, then Target returns it.
            // Skip the load if this Loadable was already loaded by an earlier call, since
            // the operation is cached until Release().
            if (hatLoadable.Status != LoadableStatus.Loaded)
                hatLoadable.Load();
            if (hatLoadable.Target != null)
                equippedHat = Instantiate(hatLoadable.Target);
        }

        private void OnDestroy()
        {
            // These free two separate things:
            // Release() frees the loaded prefab asset that backs the Loadable,
            // while Destroy() frees the instance that Instantiate() spawned into the scene.
            hatLoadable.Release();
            Destroy(equippedHat);
        }
    }
}

using Unity.Loading;
using UnityEngine;

namespace BuildDocExamples
{
    // Asynchronous example: a self-contained load -> use -> release flow. Loads an asset
    // through a Loadable<T> without blocking the main thread, uses it transiently, then
    // releases it in the same method. Because the whole lifecycle is contained here, this
    // method is safe to call repeatedly with the same Loadable.
    public class Loadable_LoadAndReleaseAsyncExample
    {
        // LoadAsync() returns an Awaitable that completes when loading finishes.
        // The content directory holding the asset must already be registered with
        // ContentLoadManager.RegisterContentDirectory before calling this.
        public async Awaitable LogIconSizeAsync(Loadable<Texture2D> icon)
        {
            // Await the load instead of blocking, so the game stays responsive while streaming.
            Texture2D texture = await icon.LoadAsync();

            // Use the asset transiently without retaining a reference to it, so it is safe
            // to release below. Reading a property is enough for this example.
            if (texture != null)
                Debug.Log($"Loaded icon is {texture.width}x{texture.height}.");

            // Release() completes the lifecycle: it frees the loaded asset and clears the
            // Loadable's cached load operation, so this method can be awaited again later.
            icon.Release();
        }
    }
}

Properties

Constructors

Public Methods