初めに

Unity プロジェクトに [Addressables パッケージをインストール] したら、使用を開始できます。

Addressables を使用する基本的なステップは、次のとおりです。

• アセットを Addressable (アドレス指定可能) にする
• Addressables API を使用してアセットをコードで参照し、ロードする
• Addressable アセットをビルドする

Addressable アセットを使用するためのプロジェクトの設定例については、Addressables-Sample リポジトリにある [Space Shooter プロジェクト] を参照してください。

Note

この使用開始トピックでは、Addressable コンテンツを編成する方法については説明しません。そのトピックについては、[Addressable アセットの編成] を参照してください。

インストール

プロジェクトに Addressables パッケージをインストールするには、Unity Package Manager を使用します。

1. Package Manager (メニュー: Window > Package Manager) を開きます。
2. Unity Registry からパッケージを表示するようにパッケージリストを設定します。
   
   
3. リストで Addressables パッケージを選択します。
4. Install (Package Manager ウィンドウの下部の右側) をクリックします。

インストール後にプロジェクトで Addressables システムを設定するには、Addressables Groups ウィンドウを開き、Create Addressables Settings をクリックします。

プロジェクトで Addressables システムを初期化する前

Create Addressables Settings コマンドを実行すると、AddressableAssetsData というフォルダーが Addressables システムによって作成されます。ここに、設定ファイルや、Addressables 設定の管理に使用する他のアセットが格納されます。このフォルダー内のファイルをソースコントロールシステムに追加する必要があります。Addressables の設定を変更すると、Addressables によって追加のファイルが作成される可能性があります。設定自体の詳細については、[Addressables の設定] を参照してください。

Note

特定のバージョンの Addressables のインストール手順、またはプロジェクトでのパッケージの管理に関する一般情報については、[パッケージと機能セット] を参照してください。

アセットの Addressable 指定

アセットを Addressable としてマークするには、以下の方法のいずれかを使用できます。

• アセットのインスペクターで Addressable ボックスをオンにします。
  
  

• インスペクターで AssetReference フィールドにアセットをドラッグするか割り当てます。
  
  

• Addressables Groups ウィンドウでアセットをグループにドラッグします。
  
  

• Addressable としてマークされている Project フォルダーにアセットを配置します。
  
  

アセットを Addressable にすると、Addressables システムはそれをデフォルトグループに加えます (手動で特定のグループに配置した場合は除きます)。[コンテンツビルド] を作成する場合、グループのアセットはグループ設定に従って AssetBundle にパックされます。これらのアセットは、Addressables API を使用してロードできます。

Note

[Resources フォルダー] 内のアセットを Addressable にすると、Unity はアセットを Resources フォルダーから移動します。このアセットはプロジェクト内の別のフォルダーに移動可能ですが、Addressable アセットを Resources フォルダーに格納することはできません。

Addressable アセットの使用

Addressable アセットをロードする方法は、次のとおりです。

• [アセットを参照する AssetReference を使用する]
• [アセットのアドレス文字列を使用する]
• [アセットに割り当てられたラベルを使用する]

Addressable アセットのロードの詳細については、[アセットのロード] を参照してください。

Addressable アセットのロードでは、非同期操作を使用します。Unity スクリプトで非同期プログラミングを実行するさまざまな方法の詳細については、[操作] を参照してください。

Tip

[Addressables-Sample リポジトリ] には、Addressable アセットの使用の複雑な例があります。

AssetReference の使用

AssetReference を使用するには、MonoBehaviour または ScriptableObject に AssetReference フィールドを追加します。この型のオブジェクトを作成したら、オブジェクトの Inspector ウィンドウでフィールドにアセットを割り当てることができます。

Note

Addressable でないアセットを AssetReference フィールドに割り当てると、そのアセットは自動的に Addressable になり、デフォルトの Addressables グループに追加されます。AssetReference を使用すると、Addressable でないシーンで Addressable アセットを使用することもできます。

Unity では、参照先アセットが自動的にロードされることも、解放されることもありません。Addressables API を使用してアセットをロードし、解放する必要があります。

using UnityEngine;
using UnityEngine.AddressableAssets;
using UnityEngine.ResourceManagement.AsyncOperations;

internal class LoadWithReference : MonoBehaviour
{
    // Assign in Editor
    public AssetReference reference;

    // Start the load operation on start
    void Start()
    {
        AsyncOperationHandle handle = reference.LoadAssetAsync<GameObject>();
        handle.Completed += Handle_Completed;
    }

    // Instantiate the loaded prefab on complete
    private void Handle_Completed(AsyncOperationHandle obj)
    {
        if (obj.Status == AsyncOperationStatus.Succeeded)
        {
            Instantiate(reference.Asset, transform);
        }
        else
        {
            Debug.LogError($"AssetReference {reference.RuntimeKey} failed to load.");
        }
    }

    // Release asset when parent object is destroyed
    private void OnDestroy()
    {
        reference.ReleaseAsset();
    }
}

AssetReference のロードの詳細については、[AssetReference のロード] を参照してください。

アドレスによるロード

アドレス文字列を使用してアセットをロードすることができます。

using UnityEngine;
using UnityEngine.AddressableAssets;
using UnityEngine.ResourceManagement.AsyncOperations;

internal class LoadWithAddress : MonoBehaviour
{
    // Assign in Editor or in code
    public string address;

    // Retain handle to release asset and operation
    private AsyncOperationHandle<GameObject> handle;

    // Start the load operation on start
    void Start()
    {
        handle = Addressables.LoadAssetAsync<GameObject>(address);
        handle.Completed += Handle_Completed;
    }

    // Instantiate the loaded prefab on complete
    private void Handle_Completed(AsyncOperationHandle<GameObject> operation)
    {
        if (operation.Status == AsyncOperationStatus.Succeeded)
        {
            Instantiate(operation.Result, transform);
        }
        else
        {
            Debug.LogError($"Asset for {address} failed to load.");
        }
    }

    // Release asset when parent object is destroyed
    private void OnDestroy()
    {
        Addressables.Release(handle);
    }
}

アセットをロードしたら、毎回忘れずに解放する必要があります。

詳細については、[単一のアセットのロード] を参照してください。

ラベルによるロード

同じラベルを持つ複数のアセットのセットを、1 回の操作でロードできます。

using System.Collections.Generic;
using UnityEngine;
using UnityEngine.AddressableAssets;
using UnityEngine.ResourceManagement.AsyncOperations;

internal class LoadWithLabels : MonoBehaviour
{
    // Label strings to load
    public List<string> keys = new List<string>() {"characters", "animals"};

    // Operation handle used to load and release assets
    AsyncOperationHandle<IList<GameObject>> loadHandle;

    // Load Addressables by Label
    void Start()
    {
        float x = 0, z = 0;
        loadHandle = Addressables.LoadAssetsAsync<GameObject>(
            keys, // Either a single key or a List of keys 
            addressable =>
            {
                //Gets called for every loaded asset
                if (addressable != null)
                {
                    Instantiate<GameObject>(addressable,
                        new Vector3(x++ * 2.0f, 0, z * 2.0f),
                        Quaternion.identity,
                        transform);
                    if (x > 9)
                    {
                        x = 0;
                        z++;
                    }
                }
            }, Addressables.MergeMode.Union, // How to combine multiple labels 
            false); // Whether to fail if any asset fails to load
        loadHandle.Completed += LoadHandle_Completed;
    }

    private void LoadHandle_Completed(AsyncOperationHandle<IList<GameObject>> operation)
    {
        if (operation.Status != AsyncOperationStatus.Succeeded)
            Debug.LogWarning("Some assets did not load.");
    }

    private void OnDestroy()
    {
        // Release all the loaded assets associated with loadHandle
        Addressables.Release(loadHandle);
    }
}

詳細については、[複数のアセットのロード] を参照してください。

Addressable アセットの管理

Addressable アセットを管理するには、Addressables Groups ウィンドウを使用します。このウィンドウを使用して、Addressables グループを作成し、グループ間でアセットを移動し、ドレスとラベルをアセットに割り当てます。

初めて Addressables パッケージをインストールして設定するときには、Addressable アセット用のデフォルトグループが作成されます。Addressables システムでは、Addressable とマークしたすべてのアセットが、このグループにデフォルトで割り当てられます。プロジェクトの初期の段階では、この 1 つのグループにアセットを保管することに問題はないと思われるかもしれませんが、コンテンツを追加するにつれて、追加のグループの作成を検討することが必要になります。グループを分けることで、特定の時点でアプリケーションがどのリソースをロードし、メモリに保持するかを制御しやすくなります。

主なグループ設定を以下に示します。

• Build Path: コンテンツのビルド後にコンテンツを保存する場所。
• Load Path: アプリケーションまたはゲームが、ビルド済みのコンテンツをランタイムに探す場所。

Note

これらのパスを設定するには、プロファイル変数を使用できます (通常はこの方法をお勧めします)。詳細については、[プロファイル] を参照してください。

• Bundle Mode: グループ内のコンテンツをバンドルにパッケージ化する方法を指定します。以下のオプションを選択できます。
  • 1 つのバンドルにすべてのグループアセットを含める
  • グループ内のエントリーごとに 1 つのバンドルを作成する (フォルダー全体を Addressable とマークし、そのコンテンツをまとめてビルドする場合に特に便利です)
  • グループアセットに割り当てられたラベルの一意の組み合わせごとに 1 つのバンドルを作成する
• Content Update Restriction: この値を適切に設定すると、公開するコンテンツ更新のサイズを削減できます。詳細については、[コンテンツ更新のビルド] を参照してください。アプリケーションの更新時に常にフルビルドを公開し、リモートリソースからコンテンツをダウンロードしない場合は、この設定を無視できます。

アセットの編成方法を決定するときに考慮すべき戦略の詳細については、[Addressable アセットの編成] を参照してください。

Addressables Groups ウィンドウの使用の詳細については、[グループ] を参照してください。

Addressable アセットのビルド

Addressables コンテンツのビルドのステップでは、[グループ設定] およびエディターで設定されている現在のプラットフォームに基づいて、Addressables グループ内のアセットが AssetBundle に変換されます。

Unity 2021.2 以降では、各プレイヤービルドの一部として Addressables コンテンツをビルドするように Addressables システムを設定するか、または、プレイヤービルドの作成前にコンテンツを個別にビルドすることができます。これらのオプションの設定の詳細については、[プレイヤービルドによる Addressables コンテンツのビルド] を参照してください。

プレイヤービルドの一部としてコンテンツをビルドするように Unity を設定した場合は、エディターの Build Settings ウィンドウで、通常の Build ボタンまたは Build and Run ボタンを使用してビルドを開始します。Unity は、プレイヤーをビルドする前に、ビルド前ステップとして Addressables コンテンツをビルドします。

Unity が初期のバージョンである場合、またはコンテンツを個別にビルドするように Unity を設定した場合は、[ビルドの作成] で説明しているように、Addressables Groups ウィンドウの Build メニューを使用して Addressables ビルドを作成する必要があります。プロジェクトのプレイヤーの次回のビルド時には、現在のプラットフォーム用に最後に実行された Addressables コンテンツビルドで作成されたアーティファクトが使用されます。Addressables ビルドプロセスの自動化の詳細については、[ビルドスクリプトの作成] を参照してください。

Addressables Groups ウィンドウでコンテンツのビルドを開始するには、以下を実行します。

1. Addressables Groups ウィンドウ (メニュー: Windows > Asset Management > Addressables > Groups) を開きます。
2. Build メニューから、いずれかのオプションを選択します。
   • New Build: 特定のビルドスクリプトでビルドを実行します。独自のカスタムスクリプトがない場合は、Default Build Script を使用します。
   • Update a Previous Build: 既存のビルドに基づいて更新をビルドします。以前のビルドを更新するには、Addressables システムに、以前のビルドで作成された addressables_content_state.bin ファイルが必要です。このファイルは、Unity プロジェクトの Assets/AddressableAssetsData/Platform フォルダーにあります。コンテンツの更新の詳細については、[コンテンツの更新] を参照してください。
   • Clean Build: キャッシュされたビルドファイルを削除します。

デフォルトでは、ビルドによって、[プロファイル] 設定で定義された LocalBuildPath および RemoteBuildPath 変数の指す場所にファイルが作成されます。Unity がプレイヤービルドに使用するファイルには、AssetBundle (.bundle)、catalog JSON、ハッシュファイル、設定ファイルなどがあります。

Warning

ほとんどの場合、ローカルビルドパスやローカルロードパスのデフォルト値は変更するべきではありません。変更する場合は、プレイヤービルドを作成する前に、ローカルビルドのアーティファクトをカスタムのビルドの場所からプロジェクトの StreamingAssets フォルダーにコピーする必要があります。これらのパスを変更すると、プレイヤービルドの一部として Addressables をビルドすることもできなくなります。

RemoteBuildPath にビルドしたグループがある場合は、それらの AssetBundle、カタログ、ハッシュファイルをホスティングサーバーに手動でアップロードする必要があります (プロジェクトでリモートコンテンツを使用しない場合は、すべてのグループを、ローカルビルドとロードパスを使用するように設定します)。

コンテンツのビルドによって以下のファイルも作成されますが、これらが Addressables によってプレイヤービルドで直接使用されることはありません。

• addressables_content_state.bin: コンテンツ更新ビルドの作成に使用されます。コンテンツの動的更新をサポートする場合は、各コンテンツリリースの後に、このファイルを保存する必要があります。サポートしない場合は、このファイルを無視できます。
• AddressablesBuildTEP.json: ビルドのパフォーマンスデータのログを作成します。[ビルドプロファイリング] を参照してください。

コンテンツビルドの設定方法と実行方法の詳細については、[Addressable コンテンツのビルド] を参照してください。

フルコンテンツビルドの開始

フルコンテンツビルドを作成するには、以下を実行します。

1. Build Settings ウィンドウで、目的の Platform Target (プラットフォームターゲット) を設定します。
2. Addressables Groups ウィンドウ (メニュー: Asset Management > Addressables > Groups) を開きます。
3. Groups ウィンドウの Build メニューから ** New Build > Default Build Script** コマンドを選択します。

ビルドプロセスが開始されます。

ビルドが完了したら、プレイヤービルドを実行し、RemoteBuildPath からホスティングサーバーにリモートファイルをアップロードすることができます。

Important

アプリケーションを再ビルドせずにリモートコンテンツ更新を公開する予定である場合は、公開するビルドごとに addressables_content_state.bin ファイルを保存しておく必要があります。このファイルがないと、作成できるのは更新ではなく、フルコンテンツビルドとプレイヤービルドのみになります。詳細については、[コンテンツ更新のビルド] を参照してください。

リモートコンテンツの配布

Addressables を使用して、コンテンツデリバリネットワーク (CDN) または他のホスティングサービスを介した、コンテンツのリモート配布をサポートすることができます。Unity には、この目的のための Unity Cloud Content Delivery (クラウドコンテンツ配信、CCD) サービスが用意されていますが、任意の CDN またはホストを使用できます。

リモート配布用のコンテンツをビルドする前に、以下を行う必要があります。

• AddressableAssetSettings (メニュー: Windows > Asset Management > Addressables > Settings) で Build Remote Catalog オプションを有効にします。
• コンテンツの公開に使用する [プロファイル] で RemoteLoadPath を設定して、コンテンツにアクセスするためのリモート URL を反映させます。
• リモート配信するアセットを含む Addressables グループごとに、Build Path を RemoteBuildPath に設定し、Load Path を RemoteLoadPath に設定します。
• Unity の Build Settings ウィンドウで、目的の Platform Target を設定します。

コンテンツビルド (Addressables Groups ウィンドウを使用) とプレイヤービルド (Build Settings ウィンドウを使用) を作成した後は、プロファイルの RemoteBuildPath で指定されたフォルダーに作成されたファイルをホスティングサービスにアップロードする必要があります。アップロードするファイルは、次のとおりです。

• AssetBundle (name.bundle)
• カタログ (catalog_timestamp.json)
• ハッシュ (catalog_timestamp.hash)

詳細については、[リモートコンテンツの配布] を参照してください。

コンテンツの差分更新

コンテンツをリモート配布するときは、コンテンツの差分更新ビルドを公開することで、更新のためにユーザーがダウンロードする必要のあるデータの量を削減できます。差分更新ビルドによって、最後に公開した更新以降に変更されたアセットのみを含むリモートバンドルを公開できるため、全体を再公開する必要がなくなります。より小さいサイズの、この更新されたバンドルは、既存のアセットをオーバーライドします。

Important

差分更新の公開を選択できるようにする場合は、プレイヤービルドを公開する前に Build Remote Catalog オプションをオンにする必要があります。リモートカタログがないと、インストールしたアプリケーションは、更新を確認しません。

コンテンツの更新の詳細と例については、[コンテンツ更新ビルド] を参照してください。

コンテンツ更新ビルドの開始

フルビルドではなくコンテンツ更新を作成するには、以下を実行します。

1. Build Settings ウィンドウで、更新しようとしている以前のコンテンツビルドのターゲットと一致するように Platform Target を設定します。
2. Addressables Groups ウィンドウ (メニュー: Asset Management > Addressables > Groups) を開きます。
3. Tools メニューから Check for Content Update Restrictions コマンドを実行します。 Build Data File ブラウザーウィンドウが開きます。
4. 以前のビルドで作成された addressables_content_state.bin ファイルを見つけます。このファイルは、ターゲットプラットフォーム用の名前の付いた Assets/AddressableAssestsData のサブフォルダーにあります。
5. Open をクリックします。 Content Update Preview ウィンドウで変更が検索され、新しいグループに移動して更新する必要のあるアセットが特定されます。"Cannot Change Post Release" に設定されたグループ内のどのアセットも変更されていない場合、プレビューに表示される変更はありません ("Can Change Post Release" に設定されたグループ内のアセットを変更した場合は、そのグループのすべての AssetBundle が Addressables で再ビルドされます。この場合、変更されたアセットは新しいグループに移動されません)。
6. Apply Changes をクリックして変更を適用します。
7. Build メニューから Update a Previous Build コマンドを実行します。
8. 以前のビルドで作成された addressables_content_state.bin ファイルを開きます。

ビルドプロセスが開始されます。

ビルドが完了したら、RemoteBuildPath からホスティングサーバーにファイルをアップロードできます。

Important

Addressables は、変更されたアセットを特定するために addressables_content_state.bin ファイルを使用します。公開されたビルドごとに、このファイルのコピーを保存しておく必要があります。このファイルがないと、作成できるのは更新ではなく、フルコンテンツビルドのみになります。