三、入门 Getting started

最新推荐文章于 2024-04-26 18:05:13 发布

幽满谷

最新推荐文章于 2024-04-26 18:05:13 发布

阅读量80

点赞数

分类专栏： Unity Addressables 手册文章标签： unity 游戏引擎

原文链接：https://docs.unity3d.com/Packages/[email protected]/manual/AddressableAssetsGettingStarted.html

版权

Unity Addressables 手册专栏收录该内容

9 篇文章 0 订阅

订阅专栏

在您的 Unity 项目中安装 Addressables 包后，您就可以开始了。

使用 Addressables 的基本步骤包括：

让您的资产可寻址
使用 Addressables API 在代码中引用和加载这些资产
构建您的可寻址资产

有关设置为使用可寻址资产的项目示例，请参阅Addressables-Sample存储库中的Space Shooter 项目。

笔记

本入门主题不讨论组织可寻址内容的各种方式。有关该主题的信息，请参阅组织可寻址资产。

安装

要在您的项目中安装 Addressables 包，请使用 Unity 包管理器：

打开包管理器（菜单：窗口 > 包管理器）。
设置包列表以显示来自Unity Registry 的包。
在列表中选择 Addressables 包。
单击“安装”（位于“程序包管理器”窗口的底部右侧）。

要在安装后在您的项目中设置 Addressables 系统，请打开Addressables Groups窗口并单击Create Addressables Settings。

在项目中初始化 Addressables 系统之前

当您运行Create Addressables Settings命令时，Addressables 系统会创建一个名为的文件夹，AddressableAssetsData其中存储设置文件和用于跟踪您的 Addressables 设置的其他资产。您应该将此文件夹中的文件添加到源代码管理系统。请注意，Addressables 可以在您更改 Addressables 配置时创建其他文件。有关设置本身的更多信息，请参阅可寻址设置。

笔记

有关安装特定版本的 Addressables 的说明或有关管理项目中包的一般信息，请参阅包。

使资产可寻址

您可以通过以下方式将资产标记为可寻址：

选中资产检查器中的 可寻址框：
将资产拖动或分配到检查器中的 AssetReference 字段：
将资产拖到可寻址组窗口中的一个组中：
将资产放入标记为可寻址的项目文件夹中：

一旦您使资产可寻址，Addressables 系统会将其添加到默认组（除非您将其放在特定组中）。Addressables 在您进行内容构建时，会根据您的群组设置将群组中的资产打包到AssetBundle中。您可以使用Addressables API加载这些资产。

笔记

如果您将Resources 文件夹中的资产设为可寻址，Unity 会将资产移出 Resources 文件夹。您可以将资产移动到项目中的不同文件夹，但不能将可寻址资产存储在资源文件夹中。

使用可寻址资产

要加载可寻址资产，您可以：

有关加载可寻址资产的更多详细信息，请参阅加载资产。

加载可寻址资产使用异步操作。有关在 Unity 脚本中处理异步编程的不同方法的信息，请参阅操作。

提示

您可以在Addressables-Sample 存储库中找到更多有关如何使用 Addressable 资产的示例。

使用 AssetReferences

要使用 AssetReference，请将 AssetReference 字段添加到 MonoBehaviour 或 ScriptableObject。创建该类型的对象后，您可以将资产分配给对象的检查器窗口中的字段。

笔记

如果您将不可寻址资产分配给 AssetReference 字段，Unity 会自动将该资产设为可寻址并将其添加到您的默认可寻址组中。AssetReferences 还允许您在本身不可寻址的场景中使用可寻址资产。

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

有关加载 AssetReferences 的更多信息，请参阅加载 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);
    }
}

请记住，每次加载资产时，还必须释放它。

有关详细信息，请参阅加载单个资产。

按标签加载

您可以在一次操作中加载具有相同标签的资产集：


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

有关详细信息，请参阅加载多个资产。

管理可寻址资产

要管理您的可寻址资产，请使用可寻址组窗口。使用此窗口可以创建可寻址组、在组之间移动资产以及为资产分配地址和标签。

当您第一次安装和设置 Addressables 包时，它会为 Addressable 资产创建一个默认组。默认情况下，可寻址系统会将您标记为可寻址的任何资产分配给该组。在项目的早期阶段，您可能会发现将资产保留在这个单独的组中是可以接受的，但是随着您添加更多内容，您应该考虑创建额外的组，以便更好地控制应用程序加载和保留的资源任何给定时间的记忆。

关键组设置包括：

构建路径：内容构建后保存内容的位置。
加载路径：您的应用程序或游戏在运行时查找构建内容的位置。

笔记

您可以（通常应该）使用 Profile 变量来设置这些路径。有关详细信息，请参阅配置文件。

Bundle模式：如何将组内的内容打包成一个bundle。您可以选择以下选项：
- 一个包含所有组资产的包
- 组中每个条目的捆绑包（如果您将整个文件夹标记为可寻址并希望将它们的内容构建在一起，则特别有用）
- 分配给组资产的每个唯一标签组合的包
内容更新限制：适当设置这个值可以让你发布更小的内容更新。有关详细信息，请参阅内容更新构建。如果您总是发布完整版本来更新您的应用程序并且不从远程源下载内容，则可以忽略此设置。

有关决定如何组织资产时要考虑的策略的更多信息，请参阅组织可寻址资产。

有关使用 Addressables Groups 窗口的更多信息，请参阅Groups。

构建可寻址资产

Addressables 内容构建步骤根据组设置和编辑器中设置的当前平台将 Addressables 组中的资产转换为 AssetBundle。

在 Unity 2021.2+ 中，您可以配置 Addressables 系统以构建您的 Addressables 内容作为每个 Player 构建的一部分，或者您可以在构建 Player 之前单独构建您的内容。有关配置这些选项的更多信息，请参阅使用播放器构建构建可寻址内容。

如果您将 Unity 配置为构建您的内容作为播放器构建的一部分，请使用编辑器构建设置窗口上的正常构建或构建和运行按钮来启动构建。Unity 在构建 Player 之前构建您的 Addressables 内容作为预构建步骤。

在早期版本的 Unity 中，或者如果您将 Unity 配置为单独构建内容，则必须使用Addressables Groups窗口中的Build菜单构建 Addressables，如[制作构建]中所述。下次您为您的项目构建 Player 时，它会使用上次针对当前平台运行的 Addressables 内容构建所生成的工件。有关自动化 Addressables 构建过程的信息，请参阅 [构建脚本]。

要从 Addressables Groups 窗口启动内容构建：

打开 Addressables Groups 窗口（菜单：Windows > Asset Management > Addressables > Groups）。
从构建菜单中选择一个选项：
- New Build：使用特定的构建脚本执行构建。如果您没有自己的自定义构建脚本，请使用默认构建脚本。
- 更新以前的版本：基于现有版本构建更新。要更新以前的构建，Addressables 系统需要addressables_content_state.bin早期构建生成的文件。Assets/AddressableAssetsData/Platform您可以在Unity 项目的文件夹中找到此文件。有关更新内容的更多信息，请参阅内容更新。
- Clean Build：删除缓存的构建文件。

默认情况下，构建会在您的配置文件设置中为LocalBuildPath和RemoteBuildPath变量定义的位置创建文件。Unity 用于播放器构建的文件包括 AssetBundles (.bundle)、目录 JSON 和哈希文件以及设置文件。

警告

在大多数情况下，您不应更改本地构建或加载路径的默认值。如果这样做，则必须在进行播放器构建之前将本地构建工件从自定义构建位置复制到项目的StreamingAssets文件夹。更改这些路径还会阻止将您的可寻址对象构建为 Player 构建的一部分。

如果您有构建到 RemoteBuildPath 的组，则您有责任将这些 AssetBundle、目录和哈希文件上传到您的托管服务器。（如果您的项目不使用远程内容，请将所有组设置为使用本地构建和加载路径。）

内容构建还会创建以下文件，Addressables 不会在播放器构建中直接使用这些文件：

addressables_content_state.bin：用于进行内容更新构建。如果您支持动态内容更新，则必须在每次内容发布后保存此文件。否则，您可以忽略此文件。
AddressablesBuildTEP.json：记录构建性能数据。请参阅构建分析。

有关如何设置和执行内容构建的更多信息，请参阅构建可寻址内容。

开始完整的内容构建

要进行完整的内容构建：

在构建设置窗口中设置所需的平台目标。
打开Addressables Groups窗口（菜单：Asset Management > Addressables > Groups）。
从“组”窗口的“构建”菜单中选择__New Build > Default Build Script__ 命令。

构建过程开始。

构建完成后，您可以执行播放器构建并将任何远程文件从您的RemoteBuildPath上传到您的托管服务器。

重要的

如果您计划在不重建应用程序的情况下发布远程内容更新，则必须addressables_content_state.bin为每个已发布的版本保留该文件。没有这个文件，你只能创建一个完整的内容构建和播放器构建，而不是更新。有关详细信息，请参阅内容更新构建。

远程内容分发

您可以使用 Addressables 支持通过内容分发网络 (CDN) 或其他托管服务远程分发内容。Unity 为此提供了 Unity Cloud Content Delivery (CCD) 服务，但您可以使用您喜欢的任何 CDN 或主机。

在构建用于远程分发的内容之前，您必须：

在 AddressableAssetSettings 中启用Build Remote Catalog选项（使用菜单访问： Windows > Asset Management > Addressables > Settings）。
在用于发布内容的配置文件中配置RemoteLoadPath ，以反映您计划访问内容的远程 URL。
对于包含要远程交付的资产的每个 Addressables 组，将构建路径设置为RemoteBuildPath并将加载路径设置为RemoteLoadPath。
在 Unity Build Settings窗口中设置所需的平台目标。

在您进行内容构建（使用 Addressables Groups窗口）和播放器构建（使用构建设置窗口）之后，您必须将在您的配置文件的RemoteBuildPath指定的文件夹中创建的文件上传到您的托管服务。要上传的文件包括：

资产包（名称.bundle）
目录 (catalog_timestamp.json)
哈希 (catalog_timestamp.hash)

有关详细信息，请参阅分发远程内容。

增量内容更新

当您远程分发内容时，您可以通过发布增量内容更新构建来减少用户为更新下载的数据量。增量更新构建允许您发布远程包，其中仅包含自上次发布更新以来发生更改的资产，而不是重新发布所有内容。这些较小的更新包中的资产会覆盖现有资产。

重要的

如果您想要发布增量更新的选项，则必须在发布播放器构建之前打开“构建远程目录”选项。如果没有远程目录，已安装的应用程序不会检查更新。

有关内容更新的更多详细信息（包括示例），请参阅内容更新构建。

开始内容更新构建

要进行内容更新，而不是完整构建：

在Build Settings窗口中，设置Platform Target以匹配您现在正在更新的先前内容构建的目标。
打开Addressables Groups窗口（菜单：Asset Management > Addressables > Groups）。
从“工具”菜单中，运行“检查内容更新限制”命令。构建数据文件浏览器窗口打开。
找到addressables_content_state.bin之前构建生成的文件。此文件位于Assets/AddressableAssestsData为目标平台命名的子文件夹中。
单击打开。内容更新预览窗口搜索更改并标识必须移动到新组以进行更新的资产。如果您没有更改设置为“无法更改发布后”的组中的任何资产，则预览中不会列出任何更改。（当您更改组中的资产设置为“可以更改发布后”时，Addressables 会重建该组的所有 AssetBundle；在这种情况下，Addressables 不会将更改的资产移动到新组。）
单击Apply Changes接受任何更改。
从“构建”菜单中，运行 __ Update a Previous Build__ 命令。
打开上一个addressables_content_state.bin构建生成的文件。