AssetReference

AssetReference は、Addressable アセットを参照できる型です。

AssetReference クラスは MonoBehaviour または ScriptableObject で使用します。これらのクラスのいずれかにシリアル化可能な AssetReference フィールドを追加すると、Inspector ウィンドウでそのフィールドに値を割り当てることができます。フィールドに割り当てることができるアセットは、タイプとラベルで制限できます。

画像の代替テキスト
複数の AssetReference フィールドが表示された Inspector ウィンドウ

値を割り当てるには、フィールドにアセットをドラッグするか、オブジェクトピッカーのアイコンをクリックしてダイアログを開き、そこで Addressable アセットを選択します。

Addressable でないアセットを AssetReference フィールドにドラッグすると、そのアセットは自動的に Addressable になり、デフォルトの Addressables グループに追加されます。Sprite アセットと Sprite Atlas アセットにはサブオブジェクトを含めることができます。これらのタイプのアセットが割り当てられた AssetReferences では、追加のオブジェクトピッカーが表示され、そこで参照先のサブオブジェクトを指定できます。

プロジェクトでの AssetReferences の使用例については、Addressables-Sample リポジトリの AssetReference、Component Reference、および Sprite Land プロジェクトを参照してください。

Important

グループのアセットを AssetReference フィールドに割り当てるには、グループの詳細設定で Include GUID in Catalog オプションが有効になっている必要があります。Include GUID in Catalog オプションはデフォルトで有効になっています。

AssetReference 型

Addressables API には、一般的なタイプのアセット向けの AssetReference サブクラスが用意されています。その他のタイプのアセットに AssetReference フィールドを制限するには、ジェネリックサブクラスである AssetReferenceT<TObject> を使用できます。

AssetReference 型には以下があります。

Note

ジェネリック AssetReferenceT で CustomPropertyDrawer を使用したい (または、2020.1 より前のバージョンの Unity を使用している) 場合、カスタムの AssetReference タイプをサポートするには、具体的なサブクラスを作成する必要があります。

クラスへ AssetReference フィールドを加える

クラスへシリアル化可能フィールドとして宣言することにより、AssetReference またはそのサブクラスの 1 つを MonoBehaviour または ScriptableObject に加えます。


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

2020.1 より前の Unity では、デフォルトで Inspector ウィンドウにジェネリックフィールドを表示できませんでした。以前のバージョンの Unity では、代わりに AssetReferenceT の非ジェネリックサブクラスを独自に作成する必要があります。[具体的なサブクラスの作成] を参照してください。

AssetReferences のロードと解放

AssetReference クラスには、参照されたアセットのロード、インスタンス化、解放を行う独自のメソッドが用意されています。また、AssetReference インスタンスを、アセットをロードするいずれかの Addressables クラスメソッドへのキーとして使用することもできます。

以下の例は、AssetReference を現在のゲームオブジェクトの子としてインスタンス化し、親が破棄されるときに解放します。


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();
    }
}

AssetReference を使用したアセットのロードの詳細と例については、[AssetReference のロード] を参照してください。

AssetReference への割り当てを特定ラベルを持つアセットに制限

AssetReference フィールドに割り当てることができるアセットを、特定のラベルを持つアセットに制限するには、AssetReferenceUILabelRestriction 属性を使用します。AssetReference のサブクラスに加えてこの属性参照を使用すると、タイプとラベルの両方によって割り当てを制限できます。

以下の例では、"animals" と "characters" ラベルのどちらも持たない参照に Addressable アセットを割り当てることができなくなります。


[AssetReferenceUILabelRestriction("animals", "characters")]
public AssetReference labelRestrictedReference;
Note
  • この属性で禁止されるのは、Unity エディターでインスペクターを使用して特定のラベルのないアセットを割り当てる操作だけです。スクリプトを使用すると、指定したラベルのないアセットでもフィールドに割り当てることができます。
  • Addressable でないアセットを AssetReferenceUILabelRestriction 属性を持つフィールドにドラッグすることはできません。

具体的なサブクラスの作成

ジェネリック形式の AssetReference クラスを直接使用できない場合 (Unity が 202.1 より前のバージョンである場合、または CustomPropertyDrawer 属性を使用している場合) は、具体的なサブクラスを作成できます。

具体的なサブクラスを作成するには、AssetReferenceT クラスから継承し、アセットタイプを指定します。さらに、GUID 文字列を基本クラスのコンストラクターに渡すことも必要です。


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

作成したカスタム AssetReference サブクラスは、別のスクリプトで、他の AssetReference 型と同様に使用できます。


// Custom asset reference class
public AssetReferenceMaterial materialReference;