集成 Asset Delivery 时,Unity 游戏可以使用 Addressables 或 AssetBundle 访问资源包。Addressables 是最近推出且推荐使用的 Asset Delivery 解决方案,适用于使用 Unity 2019.4 或更高版本构建的游戏;AssetBundle 则支持 Unity 2017.4 和 2018.4 中的资源包。
Unity Addressables
使用 Unity 2019.4 或更高版本构建的游戏应将 Addressables 用于 Android 设备上的 Asset Delivery。Unity 会提供 Play Asset Delivery (PAD) API,以便使用 Addressables 来处理 Android 资源包。如需了解如何使用 Addressables,请参阅以下资源:
- Android 软件包的地址
- Unity 的 PAD 指南
- 适用于 Unity 的 PAD API 的参考文档
使用 AssetBundle 文件
使用 Unity 2017.4 和 2018.4 构建的游戏可以将 AssetBundle 文件用于 Android 设备上的资源传送。Unity AssetBundle 文件包含可在应用运行时由 Unity 引擎加载的序列化资源。这些文件是平台专用的(例如,针对 Android 构建),并且可与资源包结合使用。最常见的情况是,将一个 AssetBundle 文件打包成单个资源包,并且资源包与 AssetBundle 使用相同的名称。如果您希望更灵活地创建资源包,请使用 API 配置资源包。
在运行时,可使用 Play Asset Delivery for Unity 类来检索打包在资源包中的 AssetBundle。
前提条件
- 设置开发环境:
OpenUPM-CLI
如果您已安装 OpenUPM CLI,则可以使用以下命令安装 OpenUPM 注册表:
openupm add com.google.play.assetdelivery
OpenUPM
依次选择 Unity 菜单选项 Edit > Project Settings > Package Manager,打开软件包管理器设置。
将 OpenUPM 作为受限注册表添加到 Package Manager 窗口:
Name: package.openupm.com URL: https://package.openupm.com Scopes: com.google.external-dependency-manager com.google.play.common com.google.play.core com.google.play.assetdelivery com.google.android.appbundle
依次选择 Unity 菜单选项 Window > Package Manager,打开软件包管理器菜单。
将经理范围下拉菜单设置为选择我的注册库。
从软件包列表中选择 Google Play Integrity plugin for Unity 软件包,然后按 Install。
从 GitHub 导入
从 GitHub 下载最新的
.unitypackage
版本。导入
.unitypackage
文件,方法是依次选择 Unity 菜单选项 Assets > Import package > Custom Package,然后导入所有项目。
使用界面配置 AssetBundle
配置资源包中的每个 AssetBundle:
- 依次选择 Google > Android App Bundle > Asset Delivery Settings。
- 如需选择直接包含 AssetBundle 文件的文件夹,请点击 Add Folder。
针对每个 Bundle,将 Delivery Mode 更改为 Install Time、Fast Follow 或 On Demand。解决所有错误或依赖项,然后关闭窗口。
依次选择 Google > Build Android App Bundle 以构建 App Bundle。
(可选)配置 App Bundle 以支持不同的纹理压缩格式。
使用 API 配置资源包
您可以通过能作为自动化构建系统的一部分运行的编辑器脚本配置 Asset Delivery。
使用 AssetPackConfig
类定义需要包含在 Android App Bundle build 中的资源,以及这些资源的分发模式。这些资源包无需包含 AssetBundle。
public void ConfigureAssetPacks { // Creates an AssetPackConfig with a single asset pack, named // examplePackName, containing all the files in path/to/exampleFolder. var assetPackConfig = new AssetPackConfig(); assetPackConfig.AddAssetsFolder("examplePackName", "path/to/exampleFolder", AssetPackDeliveryMode.OnDemand); // Configures the build system to use the newly created assetPackConfig when // calling Google > Build and Run or Google > Build Android App Bundle. AssetPackConfigSerializer.SaveConfig(assetPackConfig); // Alternatively, use BundleTool.BuildBundle to build an App Bundle from script. BuildBundle(new buildPlayerOptions(), assetPackConfig); }
在给定 BuildPlayerOptions 和 AssetPackConfig
的情况下,您还可以在 Bundletool
类中使用静态 BuildBundle
方法生成具有资源包的 Android App Bundle。
如需指导教程,请参阅“在 Unity 游戏中使用 Play Asset Delivery”Codelab。
与 Play Asset Delivery Unity API 集成
Play Asset Delivery Unity API 提供了用于请求资源包、管理下载内容和获取资产的功能。请务必先将 Unity 插件添加到您的项目中。
您在该 API 中使用的函数取决于您创建资源包的方式。
如果您使用插件界面创建资源包,请选择插件配置的资源包。
如果您使用 API(或插件界面)创建资源包,请选择 API 配置的资源包。
根据您希望获取的资源包的分发类型实现该 API。这些步骤如以下流程图所示。
图 1. 获取资源包流程图
检索 AssetBundle
导入 Play Asset Delivery 库,然后调用 RetrieveAssetBundleAsync()
方法检索 AssetBundle。
using Google.Play.AssetDelivery; // Loads the AssetBundle from disk, downloading the asset pack containing it if necessary. PlayAssetBundleRequest bundleRequest = PlayAssetDelivery.RetrieveAssetBundleAsync(asset-bundle-name);
安装时分发
配置为 install-time
的资源包可以在应用启动后立即使用。您可以使用以下代码加载 AssetBundle 中的场景:
AssetBundle assetBundle = bundleRequest.AssetBundle; // You may choose to load scenes from the AssetBundle. For example: string[] scenePaths = assetBundle.GetAllScenePaths(); SceneManager.LoadScene(scenePaths[path-index]);
快速跟进式分发和按需分发
以下几部分适用于 fast-follow
和 on-demand
资源包。
查看状态
每个资源包都存储于应用的内部存储空间内单独的文件夹中。使用 isDownloaded()
方法确定资源包是否已下载。
监控下载
查询 PlayAssetBundleRequest
对象以监控请求的状态:
// Download progress of request, between 0.0f and 1.0f. The value will always be // 1.0 for assets delivered as install-time. // NOTE: A value of 1.0 will only signify the download is complete. It will still need to be loaded. float progress = bundleRequest.DownloadProgress; // Returns true if: // * it had either completed the download, installing, and loading of the AssetBundle, // * OR if it has encountered an error. bool done = bundleRequest.IsDone; // Returns status of retrieval request. AssetDeliveryStatus status = bundleRequest.Status; switch(status) { case AssetDeliveryStatus.Pending: // Asset pack download is pending - N/A for install-time assets. case AssetDeliveryStatus.Retrieving: // Asset pack is being downloaded and transferred to app storage. // N/A for install-time assets. case AssetDeliveryStatus.Available: // Asset pack is downloaded on disk but NOT loaded into memory. // For PlayAssetPackRequest(), this indicates that the request is complete. case AssetDeliveryStatus.Loading: // Asset pack is being loaded. case AssetDeliveryStatus.Loaded: // Asset pack has finished loading, assets can now be loaded. // For PlayAssetBundleRequest(), this indicates that the request is complete. case AssetDeliveryStatus.Failed: // Asset pack retrieval has failed. case AssetDeliveryStatus.WaitingForWifi: // Asset pack retrieval paused until either the device connects via Wi-Fi, // or the user accepts the PlayAssetDelivery.ShowConfirmationDialog dialog. case AssetDeliveryStatus.RequiresUserConfirmation: // Asset pack retrieval paused until the user accepts the // PlayAssetDelivery.ShowConfirmationDialog dialog. default: break; }
下载内容较大
超过 200MB 的资源包可以自动下载,但前提是必须已连接到 WLAN。如果用户未连接到 WLAN,PlayAssetBundleRequest
状态会设置为 AssetDeliveryStatus.WaitingForWifi
,下载也会暂停。在这种情况下,要么等到设备连接到 WLAN 再恢复下载,要么提示用户批准通过移动网络连接下载资源包。
需要用户确认
如果软件包的状态为 AssetDeliveryStatus.RequiresUserConfirmation
,则在用户接受显示 PlayAssetDelivery.ShowConfirmationDialog()
的对话框之前,下载不会继续。如果 Play 无法识别应用,可能会出现此状态。请注意,在这种情况下,调用 PlayAssetDelivery.ShowConfirmationDialog()
会导致应用更新。更新后,请重新请求资源。
if(request.Status == AssetDeliveryStatus.RequiresUserConfirmation || request.Status == AssetDeliveryStatus.WaitingForWifi) { var userConfirmationOperation = PlayAssetDelivery.ShowConfirmationDialog(); yield return userConfirmationOperation; switch(userConfirmationOperation.GetResult()) { case ConfirmationDialogResult.Unknown: // userConfirmationOperation finished with an error. Something went // wrong when displaying the prompt to the user, and they weren't // able to interact with the dialog. case ConfirmationDialogResult.Accepted: // User accepted the confirmation dialog--an update will start. case ConfirmationDialogResult.Declined: // User canceled or declined the dialog. It can be shown again. default: break; } }
取消请求(仅限按需)
如果您在 AssetBundle 加载到内存中之前需要取消请求,请对 PlayAssetBundleRequest
对象调用 AttemptCancel()
方法:
// Will only attempt if the status is Pending, Retrieving, or Available - otherwise // it will be a no-op. bundleRequest.AttemptCancel(); // Check to see if the request was successful by checking if the error code is Canceled. if(bundleRequest.Error == AssetDeliveryErrorCode.Canceled) { // Request was successfully canceled. }
异步请求资源包
在大多数情况下,您应使用协程异步请求资源包并监控进度,如下所示:
private IEnumerator LoadAssetBundleCoroutine(string assetBundleName) { PlayAssetBundleRequest bundleRequest = PlayAssetDelivery.RetrieveAssetBundleAsync(assetBundleName); while (!bundleRequest.IsDone) { if(bundleRequest.Status == AssetDeliveryStatus.WaitingForWifi) { var userConfirmationOperation = PlayAssetDelivery.ShowCellularDataConfirmation(); // Wait for confirmation dialog action. yield return userConfirmationOperation; if((userConfirmationOperation.Error != AssetDeliveryErrorCode.NoError) || (userConfirmationOperation.GetResult() != ConfirmationDialogResult.Accepted)) { // The user did not accept the confirmation. Handle as needed. } // Wait for Wi-Fi connection OR confirmation dialog acceptance before moving on. yield return new WaitUntil(() => bundleRequest.Status != AssetDeliveryStatus.WaitingForWifi); } // Use bundleRequest.DownloadProgress to track download progress. // Use bundleRequest.Status to track the status of request. yield return null; } if (bundleRequest.Error != AssetDeliveryErrorCode.NoError) { // There was an error retrieving the bundle. For error codes NetworkError // and InsufficientStorage, you may prompt the user to check their // connection settings or check their storage space, respectively, then // try again. yield return null; } // Request was successful. Retrieve AssetBundle from request.AssetBundle. AssetBundle assetBundle = bundleRequest.AssetBundle;
如需详细了解如何处理错误,请参阅 AssetDeliveryErrorCodes
列表。
其他 Play Core API 方法
以下是您可能希望在应用中使用的一些其他 API 方法。
检查下载内容大小
向 Google Play 发出异步调用并针对操作何时完成设置回调方法,从而检查 AssetBundle 的大小:
public IEnumerator GetDownloadSize() { PlayAsyncOperation<long> getSizeOperation = PlayAssetDelivery.GetDownloadSize(assetPackName); yield return getSizeOperation; if(operation.Error != AssetDeliveryErrorCode.NoError) { // Error while retrieving download size. } else { // Download size is given in bytes. long downloadSize = operation.GetResult(); } }
移除 AssetBundle
您可以移除当前未加载到内存中的快速跟进式分发和按需分发 AssetBundle。发出以下异步调用,并针对何时完成设置回调方法:
PlayAsyncOperation<string> removeOperation = PlayAssetDelivery.RemoveAssetPack(assetBundleName); removeOperation.Completed += (operation) => { if(operation.Error != AssetDeliveryErrorCode.NoError) { // Error while attempting to remove AssetBundles. } else { // Files were deleted OR files did not exist to begin with. } };
后续步骤
在本地和通过 Google Play 测试 Asset Delivery 情况。