Create asset reference fields

To add an AssetReference or one of its subclasses, to a MonoBehaviour or ScriptableObject, declare it as a serializable field in the class:

using System;
using UnityEngine;
using UnityEngine.AddressableAssets;

internal class DeclaringReferences : MonoBehaviour
{
    // Any asset type
    public AssetReference reference;

    // Prefab assets
    public AssetReferenceGameObject gameObjectReference;

    // Sprite asset types
    public AssetReferenceSprite spriteReference;
    public AssetReferenceAtlasedSprite atlasSpriteReference;

    // Texture asset types
    public AssetReferenceTexture textureReference;
    public AssetReferenceTexture2D texture2DReference;
    public AssetReferenceTexture3D texture3DReference;

    // Any asset type with the specified labels
    [AssetReferenceUILabelRestriction("animals", "characters")]
    public AssetReference labelRestrictedReference;

    // Generic asset type (Unity 2020.3+)
    public AssetReferenceT<AudioClip> typedReference;

    // Custom asset reference class
    public AssetReferenceMaterial materialReference;

    [Serializable]
    public class AssetReferenceMaterial : AssetReferenceT<Material>
    {
        public AssetReferenceMaterial(string guid) : base(guid)
        {
        }
    }

    private void Start()
    {
        // Load assets...
    }

    private void OnDestroy()
    {
        // Release assets...
    }
}

Note

Before Unity 2020.1, the Inspector window couldn't display generic fields by default. In earlier versions of Unity, you must make your own non-generic subclass of AssetReferenceT instead. For more information, refer to Create a concrete subclass.

Load and release asset references

The AssetReference class provides its own methods to load, instantiate, and release a referenced asset. You can also use an AssetReference instance as a key to any Addressables class method that loads assets.

The following example instantiates an AssetReference as a child of the current GameObject and releases it when the parent is destroyed:

using UnityEngine;
using UnityEngine.AddressableAssets;

internal class InstantiateReference : MonoBehaviour
{
    [SerializeField]
    private AssetReferenceGameObject reference;

    void Start()
    {
        if (reference != null)
            reference.InstantiateAsync(this.transform);
    }

    private void OnDestroy()
    {
        if (reference != null && reference.IsValid())
            reference.ReleaseAsset();
    }
}

Refer to Load an AssetReference for more information and examples about loading assets using AssetReferences.

Use labels with asset references

Use the AssetReferenceUILabelRestriction attribute to restrict the assets you can assign to an AssetReference field to those with specific labels. You can use this attribute reference and AssetReference subclasses to restrict assignment by both type and label.

The following example prevents someone from assigning an Addressable asset to a reference that doesn't have either the label, animals, or the label, characters:

[AssetReferenceUILabelRestriction("animals", "characters")]
public AssetReference labelRestrictedReference;

This attribute only prevents assigning assets without the specified label using an Inspector in the Unity Editor. You can still assign an asset without the label to the field using a script.

You can't drag non-Addressable assets to a field with the AssetReferenceUILabelRestriction attribute.

Create a concrete subclass

If you can't use the generic form of the AssetReference class directly, such as in versions of Unity prior to Unity 2020.1 or when using the CustomPropertyDrawer attribute, you can create a concrete subclass.

To create a concrete subclass, inherit from the AssetReferenceT class and specify the asset type. You must also pass the GUID string to the base class constructor:

[Serializable]
internal class AssetReferenceMaterial : AssetReferenceT<Material>
{
    public AssetReferenceMaterial(string guid) : base(guid)
    {
    }
}

You can use your custom AssetReference subclass in another script the same way as other AssetReference types:

// Custom asset reference class
public AssetReferenceMaterial materialReference;