Loadable<T>
Serialized reference that loads a specific T asset from registered built content on demand instead of pulling it in with direct references.
Read time 3 minutesLast updated 7 days ago
Definition
- Type: Class
- Namespace: Unity.Loading
- Assembly: UnityEngine.ContentLoadModule
public sealed class Loadable<T> where T : Object
Remarks
Add a Loadable<T> field to a ScriptableObject or MonoBehaviour to reference an asset without loading it immediately. The reference is stored as a Loadable<T>.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<T>.Load or Loadable<T>.LoadAsync to load the asset on demand, read it from Loadable<T>.Target, and call Loadable<T>.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<T> fields on those root assets or on any asset or scene they reference. A Loadable<T> 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<T> 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<T>.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<T> 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<T>.LoadableObjectId, LoadableObjectIdEditorUtility, BuildPipeline.BuildContentDirectory, ContentLoadManager
Examples
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(); } }}
Constructors
Constructor | Description |
|---|---|
| Loadable`1(Unity.Loading.LoadableObjectId@) | Creates a new Loadable with the specified loadable object id. |
Properties
Property | Description |
|---|---|
| LoadableObjectId | The underlying loadable object id. |
| Status | The current status of the loading operation. |
| Target | The result of the load operation. If the operation is not complete or has failed, this returns null. Use Loadable<T>.Load to force the operation to complete synchronously. |
Methods
Method | Description |
|---|---|
| Load | Loads the object synchronously. Blocks until loading is complete. |
| LoadAsync | Loads the object asynchronously. Returns an awaitable that completes when loading is finished. |
| Release | Releases the loaded object so that Unity can unload it. |
| ToString | Returns a string representation of the loadable object id. |