// ============================================================================
|
// IYooAssetService.cs — YooAsset 资源加载服务接口
|
// 定义在 Main 程序集中，供所有业务系统使用
|
// ============================================================================
|
|
using System;
|
using System.Threading;
|
using Cysharp.Threading.Tasks;
|
using UnityEngine;
|
using UnityEngine.SceneManagement;
|
using YooAsset;
|
|
namespace ProjSG.Resource
|
{
|
/// <summary>
|
/// YooAsset 资源加载服务接口。
|
/// 封装 YooAsset ResourcePackage 的核心加载能力，提供 UniTask 异步 API。
|
/// </summary>
|
public interface IYooAssetService
|
{
|
/// <summary>
|
/// 服务是否已初始化完成
|
/// </summary>
|
bool IsInitialized { get; }
|
|
/// <summary>
|
/// 当前运行模式
|
/// </summary>
|
EPlayMode PlayMode { get; }
|
|
// ====================================================================
|
// 初始化
|
// ====================================================================
|
|
/// <summary>
|
/// 初始化 YooAsset 资源服务。
|
/// 在 Launch 阶段由 YooAssetInitializer 调用。
|
/// </summary>
|
/// <param name="playMode">运行模式</param>
|
/// <param name="remoteServices">CDN 远程服务（HostPlayMode/WebPlayMode 必需）</param>
|
/// <returns>初始化完成</returns>
|
UniTask InitializeAsync(EPlayMode playMode, IRemoteServices remoteServices = null);
|
|
// ====================================================================
|
// 资源加载 — Asset
|
// ====================================================================
|
|
/// <summary>
|
/// 异步加载指定类型的资源。
|
/// </summary>
|
/// <typeparam name="T">资源类型（GameObject, Sprite, AudioClip 等）</typeparam>
|
/// <param name="location">YooAsset 资源地址</param>
|
/// <param name="priority">加载优先级（0 = 默认）</param>
|
/// <param name="ct">取消令牌</param>
|
/// <returns>加载完成的资源对象，加载失败返回 null</returns>
|
UniTask<T> LoadAssetAsync<T>(string location, uint priority = 0,
|
CancellationToken ct = default) where T : UnityEngine.Object;
|
|
/// <summary>
|
/// 异步加载指定类型的资源（Type 参数版本）。
|
/// </summary>
|
UniTask<UnityEngine.Object> LoadAssetAsync(string location, Type type, uint priority = 0,
|
CancellationToken ct = default);
|
|
/// <summary>
|
/// 异步加载子资源（如 SpriteAtlas 中的 Sprite）。
|
/// </summary>
|
UniTask<SubAssetsHandle> LoadSubAssetsAsync<T>(string location, uint priority = 0,
|
CancellationToken ct = default) where T : UnityEngine.Object;
|
|
/// <summary>
|
/// 异步加载同一 Bundle 下的所有同类型资源。
|
/// </summary>
|
UniTask<AllAssetsHandle> LoadAllAssetsAsync<T>(string location, uint priority = 0,
|
CancellationToken ct = default) where T : UnityEngine.Object;
|
|
// ====================================================================
|
// 资源加载 — RawFile
|
// ====================================================================
|
|
/// <summary>
|
/// 异步加载原始文件并返回文本内容。
|
/// 用于配置文件（.txt, .json, .csv 等）加载。
|
/// </summary>
|
UniTask<string> LoadRawFileTextAsync(string location, CancellationToken ct = default);
|
|
/// <summary>
|
/// 异步加载原始文件并返回字节数组。
|
/// </summary>
|
UniTask<byte[]> LoadRawFileBytesAsync(string location, CancellationToken ct = default);
|
|
// ====================================================================
|
// 场景加载
|
// ====================================================================
|
|
/// <summary>
|
/// 异步加载场景。
|
/// </summary>
|
UniTask<SceneHandle> LoadSceneAsync(string location, LoadSceneMode sceneMode = LoadSceneMode.Single,
|
LocalPhysicsMode physicsMode = LocalPhysicsMode.None, bool suspendLoad = false, uint priority = 0, CancellationToken ct = default);
|
|
// ====================================================================
|
// 资源信息查询
|
// ====================================================================
|
|
/// <summary>
|
/// 检查资源地址是否有效。
|
/// </summary>
|
bool CheckLocationValid(string location);
|
|
/// <summary>
|
/// 获取指定标签的所有资源信息。
|
/// </summary>
|
YooAsset.AssetInfo[] GetAssetInfosByTag(string tag);
|
|
/// <summary>
|
/// 检查资源是否需要从远程下载。
|
/// </summary>
|
bool IsNeedDownloadFromRemote(string location);
|
|
// ====================================================================
|
// 资源下载
|
// ====================================================================
|
|
/// <summary>
|
/// 创建资源下载器并开始下载。
|
/// </summary>
|
UniTask DownloadByTagsAsync(string[] tags, int downloadingMaxNumber = 10,
|
int failedTryAgain = 3, IProgress<float> progress = null, CancellationToken ct = default);
|
|
// ====================================================================
|
// 版本管理
|
// ====================================================================
|
|
/// <summary>
|
/// 请求最新包裹版本。
|
/// </summary>
|
UniTask<string> RequestPackageVersionAsync(CancellationToken ct = default);
|
|
/// <summary>
|
/// 更新包裹 Manifest 到指定版本。
|
/// </summary>
|
UniTask UpdatePackageManifestAsync(string packageVersion, CancellationToken ct = default);
|
|
// ====================================================================
|
// 资源释放
|
// ====================================================================
|
|
/// <summary>
|
/// 释放资源句柄（引用计数 -1）。
|
/// </summary>
|
void ReleaseHandle(HandleBase handle);
|
|
/// <summary>
|
/// 卸载所有引用计数为零的资源。
|
/// </summary>
|
UniTask UnloadUnusedAssetsAsync();
|
|
/// <summary>
|
/// 强制卸载所有资源。
|
/// </summary>
|
UniTask UnloadAllAssetsAsync();
|
}
|
}
|
