AlicizaX/Client/Assets/Books/Framework/Runtime/Resource.md

Resource

模块概述

Resource 模块基于 YooAsset 封装了资源包初始化、版本管理、资源查询、同步/异步加载、实例化、缓存回收与低内存处理能力。

它是多个模块的底层依赖：

• UI：加载窗口和 Widget 预制体
• Audio：加载音频资源
• Localization：加载语言表
• GameObjectPool：加载池对象原始 prefab
• Scene：主场景与附加场景的资源加载链路

从当前实现来看，ResourceService 还额外提供了：

• 多包管理
• 同一路径并发加载合并
• 资源对象池缓存
• 低内存时统一回收入口
• 下载、版本、清单更新能力

快速开始

最少步骤

1. 在场景中挂载 ResourceComponent
2. 配置 PlayMode、默认包名和解密服务名
3. 游戏启动时调用 InitPackageAsync
4. 通过 GameApp.Resource 或 AppServices.Require<IResourceService>() 加载资源

最小示例

using AlicizaX;
using UnityEngine;

public sealed class ResourceQuickStart : MonoBehaviour
{
    private async void Start()
    {
        await GameApp.Resource.InitPackageAsync();

        Texture2D icon = await GameApp.Resource.LoadAssetAsync<Texture2D>("UI/Common/Icon");
        Debug.Log(icon != null);
    }
}

架构说明

ResourceComponent
  └─ ResourceService
      ├─ YooAsset PackageMap
      ├─ AssetInfo Cache
      ├─ AssetObject Pool
      ├─ Loading Operation Map
      ├─ Download / Version / Manifest
      └─ ResourceExtComponent / AssetsReference

关键协作关系

• ResourceComponent：负责注册服务、配置运行模式并接管低内存回收节奏
• ResourceService：负责包初始化、加载、缓存和释放
• AssetsReference：负责把实例对象与源资源句柄关联起来，在对象销毁时自动释放源资源引用
• ResourceExtComponent：负责追踪资源绑定目标并分帧回收无引用资源

运行模式

当前实现支持以下 PlayMode：

• EditorSimulateMode
• OfflinePlayMode
• HostPlayMode
• WebPlayMode

不同模式决定初始化参数：

• EditorSimulateMode：编辑器模拟构建目录
• OfflinePlayMode：本地内置资源
• HostPlayMode：内置资源 + 缓存 + 远端下载
• WebPlayMode：Web 环境资源拉取方式

并发加载合并机制

ResourceService 内部使用 _assetLoadingOperations 合并同一路径的并发加载请求。

这意味着：

• 多个系统同时加载同一个资源时，不会重复发起多次底层加载
• 后来的请求会等待第一条加载链路完成，再复用结果

这对 UI 和公共图集资源特别有价值。

核心类与接口

IResourceService

该接口同时覆盖：

• 包初始化
• 包版本与清单管理
• 资源存在性检查
• 同步/异步加载
• 场景对象实例化
• 缓存清理
• 低内存回收

ResourceComponent

它是 Resource 模块在场景中的入口组件，主要职责：

• 注册 ResourceService
• 配置默认包名 PackageName
• 设置运行模式 PlayMode
• 设置解密服务名 decryptionServices
• 设置资源对象池参数
• 接管 Application.lowMemory 事件

ResourceService

从当前实现看，ResourceService 维护以下关键状态：

• DefaultPackageName
• PlayMode
• PackageMap
• _assetInfoMap
• _assetLoadingOperations
• _assetPool

AssetsReference

这是实例对象与源资源句柄的桥接组件。

作用：

• 当你通过 LoadGameObject / LoadGameObjectAsync 实例化资源时
• 框架会在实例对象上自动挂一个 AssetsReference
• 当该实例对象销毁时，对应源资源引用会自动 UnloadAsset

这就是为什么：

• LoadGameObject 返回的实例对象通常不需要你手动 UnloadAsset

ResourceExtComponent

主要用于：

• 追踪已绑定给 UI、Sprite 或其他目标对象的资源
• 自动清理已经失去引用的资源包装对象
• 以分帧方式做回收，降低一次性遍历成本

API 参考

以下内容按使用频率分组说明。

一、初始化与运行配置

void Initialize()

• 参数：无
• 返回值：无
• 说明：初始化 YooAsset、默认包与资产池
• 备注：通常由 ResourceComponent.Start() 自动调用

UniTask<bool> InitPackageAsync(string packageName = "", string hostServerURL = "", string fallbackHostServerURL = "")

• 可选参数：packageName
• 可选参数：hostServerURL
• 可选参数：fallbackHostServerURL
• 返回值：UniTask<bool>

说明：

• 初始化指定资源包
• 如果 packageName 为空，则使用 DefaultPackageName
• 在 Host/Web 模式下通常需要传入远端地址

异常与边界：

• 如果同一个包正在初始化或已成功初始化，会记录错误并直接返回失败结果
• 初始化失败时任务会抛出异常

string DefaultPackageName { get; set; }

• 说明：默认资源包名
• 推荐：整个项目统一默认包名约定

EPlayMode PlayMode { get; set; }

• 说明：资源系统运行模式
• 注意：Editor 与真机配置往往不同

string DecryptionServices { get; set; }

• 说明：解密服务类型名
• 注意：该值应是可被反射创建的类型全名

bool AutoUnloadBundleWhenUnused { get; set; }

• 说明：初始化参数中的自动卸载选项

二、版本与下载管理

string GetPackageVersion(string customPackageName = "")

• 可选参数：customPackageName
• 返回值：包版本字符串

RequestPackageVersionOperation RequestPackageVersionAsync(bool appendTimeTicks = false, int timeout = 60, string customPackageName = "")

• 可选参数：appendTimeTicks
• 可选参数：timeout
• 可选参数：customPackageName
• 返回值：RequestPackageVersionOperation

UpdatePackageManifestOperation UpdatePackageManifestAsync(string packageVersion, int timeout = 60, string customPackageName = "")

• 必填参数：packageVersion
• 可选参数：timeout
• 可选参数：customPackageName
• 返回值：UpdatePackageManifestOperation

ResourceDownloaderOperation CreateResourceDownloader(string customPackageName = "")

• 可选参数：customPackageName
• 返回值：ResourceDownloaderOperation

说明：

• 会使用当前 DownloadingMaxNum 和 FailedTryAgain

三、资源查询

HasAssetResult HasAsset(string location, string packageName = "")

• 必填参数：location
• 可选参数：packageName
• 返回值：HasAssetResult

说明：

• 用于判断资源是否存在、是否在本地、是否需要远端下载

注意：

• 如果 location 为空会抛异常

bool CheckLocationValid(string location, string packageName = "")

• 必填参数：location
• 可选参数：packageName
• 返回值：bool

AssetInfo GetAssetInfo(string location, string packageName = "")

• 必填参数：location
• 可选参数：packageName
• 返回值：AssetInfo

说明：

• 内部带有 _assetInfoMap 缓存
• 同一路径重复获取成本较低

四、同步加载

T LoadAsset<T>(string location, string packageName = "") where T : UnityEngine.Object

• 必填参数：location
• 可选参数：packageName
• 返回值：T
• 泛型约束：T : UnityEngine.Object

说明：

• 同步加载资源
• 首次加载会进入资源池缓存
• 重复获取相同资源时会优先从 _assetPool 中复用

GameObject LoadGameObject(string location, Transform parent = null, string packageName = "")

• 必填参数：location
• 可选参数：parent
• 可选参数：packageName
• 返回值：GameObject

说明：

• 同步加载 prefab 并实例化
• 实例对象会自动挂 AssetsReference
• 销毁实例时会自动释放源资源引用

五、异步加载

UniTask<T> LoadAssetAsync<T>(string location, CancellationToken cancellationToken = default, string packageName = "") where T : UnityEngine.Object

• 必填参数：location
• 可选参数：cancellationToken
• 可选参数：packageName
• 返回值：UniTask<T>

UniTask<GameObject> LoadGameObjectAsync(string location, Transform parent = null, CancellationToken cancellationToken = default, string packageName = "")

• 必填参数：location
• 可选参数：parent
• 可选参数：cancellationToken
• 可选参数：packageName
• 返回值：UniTask<GameObject>

六、回调式加载

UniTask LoadAssetAsync(string location, int priority, LoadAssetCallbacks loadAssetCallbacks, object userData, string packageName = "")

UniTask LoadAssetAsync(string location, Type assetType, int priority, LoadAssetCallbacks loadAssetCallbacks, object userData, string packageName = "")

LoadAssetCallbacks 中的回调签名：

• 成功：(string assetName, object asset, float duration, object userData)
• 失败：(string assetName, LoadResourceStatus status, string errorMessage, object userData)
• 进度：(string assetName, float progress, object userData)

适合：

• 旧式回调链
• 想同时观察进度与错误
• 不方便直接 await 的场景

七、句柄接口

AssetHandle LoadAssetSyncHandle<T>(string location, string packageName = "") where T : UnityEngine.Object

AssetHandle LoadAssetAsyncHandle<T>(string location, string packageName = "") where T : UnityEngine.Object

适合：

• 需要直接管理底层句柄
• 需要和 YooAsset 句柄 API 配合

八、释放与回收

void UnloadAsset(object asset)

• 必填参数：asset
• 返回值：无

说明：

• 本质上是把资源对象从 _assetPool 中 Unspawn

void UnloadUnusedAssets()

• 返回值：无

说明：

• 释放资源对象池中未使用的对象
• 并对所有已成功初始化的包执行 UnloadUnusedAssetsAsync

void ForceUnloadAllAssets()

• 返回值：无

说明：

• 强制卸载所有资源
• WebGL 下会直接警告并退出

void ForceUnloadUnusedAssets(bool performGCCollect)

• 必填参数：performGCCollect
• 返回值：无

说明：

• 委托给 ResourceComponent 控制实际的系统资源回收时机

常见用法

1. 初始化默认包

using AlicizaX;
using AlicizaX.Resource.Runtime;
using UnityEngine;

public sealed class ResourceInitExample : MonoBehaviour
{
    private async void Start()
    {
        bool ok = await GameApp.Resource.InitPackageAsync();
        Debug.Log($"Init default package success: {ok}");
    }
}

2. 初始化远端包

using AlicizaX;
using UnityEngine;

public sealed class HostModeInitExample : MonoBehaviour
{
    private async void Start()
    {
        await GameApp.Resource.InitPackageAsync(
            packageName: "DefaultPackage",
            hostServerURL: "https://cdn.example.com/game",
            fallbackHostServerURL: "https://backup.example.com/game");
    }
}

3. 同步加载配置资源

using AlicizaX;
using UnityEngine;

public sealed class SyncLoadExample : MonoBehaviour
{
    private void Start()
    {
        TextAsset config = GameApp.Resource.LoadAsset<TextAsset>("Config/GameBalance");
        Debug.Log(config != null ? config.text : "Config missing");
    }
}

4. 异步加载图片资源

using AlicizaX;
using UnityEngine;

public sealed class AsyncLoadExample : MonoBehaviour
{
    private async void Start()
    {
        Sprite sprite = await GameApp.Resource.LoadAssetAsync<Sprite>("UI/Common/Atlas/Icon_Star");
        Debug.Log(sprite != null);
    }
}

5. 加载并实例化 GameObject

using AlicizaX;
using UnityEngine;

public sealed class InstantiateExample : MonoBehaviour
{
    private GameObject _hero;

    private async void Start()
    {
        _hero = await GameApp.Resource.LoadGameObjectAsync("Character/Hero.prefab", transform);
    }

    private void OnDestroy()
    {
        if (_hero != null)
        {
            Destroy(_hero);
        }
    }
}

说明：

• 这里不需要对 _hero 再调用 UnloadAsset
• 销毁实例时 AssetsReference 会自动释放源资源引用

6. 使用回调式加载并监听进度

using AlicizaX;
using AlicizaX.Resource.Runtime;
using UnityEngine;

public sealed class CallbackLoadExample : MonoBehaviour
{
    private async void Start()
    {
        var callbacks = new LoadAssetCallbacks(
            (assetName, asset, duration, userData) =>
            {
                Debug.Log($"Load success: {assetName}, duration: {duration:F3}s");
            },
            (assetName, status, errorMessage, userData) =>
            {
                Debug.LogError($"Load failed: {assetName}, {status}, {errorMessage}");
            },
            (assetName, progress, userData) =>
            {
                Debug.Log($"Progress {assetName}: {progress:P0}");
            });

        await GameApp.Resource.LoadAssetAsync(
            "UI/Common/Icon",
            priority: 0,
            loadAssetCallbacks: callbacks,
            userData: null);
    }
}

7. 下载资源版本并更新清单

using AlicizaX;
using UnityEngine;

public sealed class UpdateManifestExample : MonoBehaviour
{
    private async void Start()
    {
        var versionOp = GameApp.Resource.RequestPackageVersionAsync();
        await versionOp.ToUniTask();

        if (versionOp.Status == YooAsset.EOperationStatus.Succeed)
        {
            string version = versionOp.PackageVersion;
            var manifestOp = GameApp.Resource.UpdatePackageManifestAsync(version);
            await manifestOp.ToUniTask();
            Debug.Log($"Manifest updated to: {version}");
        }
    }
}

8. 创建下载器

using AlicizaX;
using UnityEngine;

public sealed class DownloaderExample : MonoBehaviour
{
    private async void Start()
    {
        var downloader = GameApp.Resource.CreateResourceDownloader();
        downloader.BeginDownload();
        await downloader.ToUniTask();
        Debug.Log($"Download status: {downloader.Status}");
    }
}

运行行为细节

1. 重复加载同一路径会优先复用缓存

当前实现通过 _assetPool 保存 AssetObject，同一路径的资源会复用池内对象。

好处：

• 减少重复加载
• 降低频繁生成/销毁底层句柄的开销

2. 并发同路径加载会合并请求

如果同一路径资源正在加载中：

• 后续请求不会重复发起底层加载
• 会等待首个请求完成后再复用结果

3. LoadGameObject 与 LoadAsset<T> 的释放语义不同

LoadAsset<T>

• 返回的是资源对象本身
• 如有需要可以显式 UnloadAsset(asset)

LoadGameObject

• 返回的是实例化后的场景对象
• 源 prefab 资源句柄通过 AssetsReference 绑定到实例对象
• 通常直接 Destroy(instance) 即可

4. 低内存行为

触发 OnLowMemory() 时：

• 会调用 _forceUnloadUnusedAssetsAction
• 实际清理由 ResourceComponent 驱动

5. AssetInfo 有内部缓存

多次 GetAssetInfo 会命中 _assetInfoMap

适合：

• 频繁查询资源合法性
• UI 打开前做路径校验

6. 失败行为

以下情况通常会导致异常或错误日志：

• 资源路径为空
• 包不存在
• 资源定位无效
• 初始化失败

最佳实践

• 统一资源路径规范，避免大小写和目录命名混乱
• 默认优先异步加载
• 把“包初始化 / 版本更新 / 资源下载 / 资源使用”分成不同阶段处理
• UI、音频、图集等高复用资源尽量走缓存复用
• 对需要长期驻留的资源，业务层要明确生命周期，不要频繁反复加载

常见错误

1. 包未初始化就加载资源

现象：

• 资源查找失败
• 返回空对象或直接异常

规避：

• 确保启动流程中先执行 InitPackageAsync

2. 默认包名与实际包名不一致

现象：

• 路径正确但查不到资源

规避：

• 统一 DefaultPackageName
• 多包场景显式传入 packageName

3. 手动 UnloadAsset 已实例化场景对象

现象：

• 语义不清晰
• 可能导致资源生命周期混乱

规避：

• LoadGameObject 返回的实例优先 Destroy

4. 解密服务类型名错误

现象：

• 初始化时反射失败

规避：

• DecryptionServices 必须是可反射创建的完整类型名

性能注意事项

• 避免在主线程大量同步加载
• 常用资源优先缓存复用
• 合理设置：
  • AssetAutoReleaseInterval
  • AssetCapacity
  • AssetExpireTime
  • AssetPriority
• 高并发异步加载时，优先复用路径和包配置，发挥内部合并机制优势