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 System.Threading.Tasks;
using Unity.Loading;
using UnityEngine;

namespace BuildDocExamples
{
    public class Loadable_LoadAndReleaseExample
    {
        public class HatPicker : MonoBehaviour
        {
            public Loadable<GameObject> hatPrefab;

            public void EquipDefault()
            {
                hatPrefab.Load();
                Instantiate(hatPrefab.Target);
            }
        }

        // Example showing async loading with status check
        public async Task LoadAsyncExample(Loadable<Texture2D> myLoadable)
        {
            await myLoadable.LoadAsync();
            if (myLoadable.Status == LoadableStatus.Loaded)
            {
                // Use myLoadable.Target
                Debug.Log($"Loaded: {myLoadable.Target.name}");
            }
            else
            {
                Debug.LogWarning($"Texture2D myLoadable failed to load. Loadable : {myLoadable.ToString()}");
            }
            myLoadable.Release();
        }
    }
}

Properties

Constructors

Public Methods