175 lines
6.2 KiB
Markdown
175 lines
6.2 KiB
Markdown
# 资源管理使用指南
|
||
|
||
## 一、加载资源
|
||
|
||
业务统一通过 `HFFunCatalogue.Asset` 调用：
|
||
|
||
```csharp
|
||
HFFunCatalogue.Asset.LoadAsset(@"Perfabs\Tower\LavaGuard.prefab", (response, args) =>
|
||
{
|
||
GameObject prefab = response.GetAsset<GameObject>();
|
||
if (prefab == null)
|
||
{
|
||
SFP.Error("Load LavaGuard failed.");
|
||
return;
|
||
}
|
||
|
||
GameObject instance = GameObject.Instantiate(prefab);
|
||
});
|
||
```
|
||
|
||
资源路径仍按项目 `HFAssetBundlePathAttribute`、语言目录和 AssetBundle 配置解析。业务不要直接创建 `HFAssetLoader` 或依赖 assetBundleKey。
|
||
|
||
## 二、主动卸载
|
||
|
||
业务使用易读名称接口：
|
||
|
||
```csharp
|
||
bool prefabUnloaded = HFFunCatalogue.Asset.UnloadPrefabObject("LavaGuard");
|
||
bool assetUnloaded = HFFunCatalogue.Asset.UnloadAssetObject("common_icon");
|
||
```
|
||
|
||
调用前必须确认业务实例和窗口已经释放引用。框架会查找唯一 loader，并检查加载、请求和释放状态；未找到、重名或仍不可卸载时返回 `false`。
|
||
|
||
`AssetBundle.Unload(false)` 不会自动销毁已经实例化的 GameObject。业务仍应先关闭窗口或 Destroy 实例，再请求卸载 Bundle 内存。
|
||
|
||
同名资源存在多个 loader 时不要随机卸载；使用更完整的资源路径，或根据错误日志定位冲突来源。
|
||
|
||
## 三、内存查看
|
||
|
||
```csharp
|
||
long bytes = HFFunCatalogue.Asset.GetLoadedAssetBundleMemorySize();
|
||
float kb = HFFunCatalogue.Asset.GetLoadedAssetBundleMemorySizeKB();
|
||
float mb = HFFunCatalogue.Asset.GetLoadedAssetBundleMemorySizeMB();
|
||
string text = HFFunCatalogue.Asset.GetLoadedAssetBundleMemorySizeText();
|
||
HFFunCatalogue.Asset.LogLoadedAssetBundleMemorySize();
|
||
```
|
||
|
||
该数值是已完成 loader 的 AssetBundle 内存估算。`LoadFromFileAsync` 没有托管 byte[] 时使用文件长度估算，因此只用于调试面板和趋势观察。
|
||
|
||
## 四、AssetBundle CDN 保存路径
|
||
|
||
平台层可以在初始化时配置：
|
||
|
||
```csharp
|
||
HFFunCatalogue.Asset.SetCdnSaveRootPath(platformSaveRoot);
|
||
```
|
||
|
||
未配置或传入无效值时使用 PersistentData 资源根目录。平台专用目录由平台适配层传入，不在通用 ESF 逻辑中硬编码。
|
||
|
||
## 五、分包 V2 配置
|
||
|
||
非热更启动层使用：
|
||
|
||
```csharp
|
||
SFSubPackageRuntimeV2.Instance.SetDownloadConfig(
|
||
downloadSetting.WebBaseUrlBase,
|
||
downloadSetting.AppVersion,
|
||
downloadSetting.AppPartner);
|
||
```
|
||
|
||
如平台使用自定义文件系统，调用 `SetLocalStorage` 重载传入 exists、read、write 和 delete 回调。默认存储根目录为 PersistentData。
|
||
|
||
旧 `SetDownLoadUri(string)` 只作为单地址兼容入口，新代码优先使用 `SetDownloadConfig`。
|
||
|
||
## 六、启动代码更新
|
||
|
||
`GameDllManager` 负责调用：
|
||
|
||
```csharp
|
||
SFSubPackageRuntimeV2.Instance.CheckAndDownloadBootstrapFiles(
|
||
OnProgress,
|
||
OnBootstrapCompleted,
|
||
OnManifestFailed);
|
||
```
|
||
|
||
成功下载不等于启动完成。AOT、HotUpdate 和热更入口成功后，调用：
|
||
|
||
```csharp
|
||
SFSubPackageRuntimeV2.Instance.CommitBootstrapCodeLoaded(OnCommitted);
|
||
```
|
||
|
||
提交成功后普通资源 API 才可使用。失败时调用 `InvalidateBootstrapCode` 保持门禁关闭，并向业务展示重试或退出。
|
||
|
||
## 七、更新普通资源
|
||
|
||
### 更新基础、BuiltIn 和历史包
|
||
|
||
```csharp
|
||
HFSubPackageManager.Instance.CheckAndDownloadAllFiles(
|
||
progress => UpdateLoading(progress),
|
||
() => OnResourceUpdateCompleted(),
|
||
result => SFP.Error(SFDownloadResultLog.Format("普通资源下载失败", result)));
|
||
```
|
||
|
||
该接口会先完成差异扫描并回调差异结果，再开始删除旧遮挡文件和下载。它只处理基础文件、BuiltIn 包、历史已下载包及依赖闭包。
|
||
|
||
### 按枚举下载 Package
|
||
|
||
```csharp
|
||
HFSubPackageManager.Instance.CheckAndDownloadPackage(
|
||
enHFSubPackageId.PACKAGE_1001,
|
||
progress => UpdateLoading(progress),
|
||
() => OnPackageReady(),
|
||
result => SFP.Error(SFDownloadResultLog.Format("Package 下载失败", result)));
|
||
```
|
||
|
||
枚举由编辑器生成，成员注释来自 Package DisplayName。不要手改 `Generated/enHFSubPackageId.cs`。
|
||
|
||
字符串接口仍保留：
|
||
|
||
```csharp
|
||
HFSubPackageManager.Instance.CheckAndDownloadPackage(
|
||
packageId, progress, finish, failed);
|
||
```
|
||
|
||
### 查询 Package 状态
|
||
|
||
```csharp
|
||
bool ready = HFSubPackageManager.Instance.IsPackageDownloaded(
|
||
enHFSubPackageId.PACKAGE_1001);
|
||
```
|
||
|
||
返回 `true` 需要：Bootstrap 已提交、Package 存在于当前清单和 `DownloadedPackageIds`、依赖包已记录、全部文件状态符合当前 MD5。`BuiltIn = true` 本身不等于业务已经下载过。
|
||
|
||
### 按文件兜底
|
||
|
||
资源加载知道目标 AB 路径时可以使用 `CheckAndDownloadFile`。运行时会从 `Files[]` 找到目标文件，递归展开 Dependencies，下载差异后重试原加载流程。
|
||
|
||
## 八、进度和失败
|
||
|
||
进度对象包含：
|
||
|
||
- `Stage`、`Max`、`DownloadedCount`
|
||
- `TotalBytes`、`DownloadedBytes`
|
||
- `CurrentPath`、`CurrentFileSize`
|
||
- `CurrentFileDownloadedBytes`、`CurrentFileProgress`、`Progress`
|
||
|
||
失败结果包含：
|
||
|
||
- `DifferenceFiles`、`DeletedOldFiles`、`UpdatedFiles`
|
||
- `FailedFiles[].Path`
|
||
- `ExpectedMD5`、`Error`、`TriedUrls`
|
||
|
||
单文件只有写入完成且 MD5 通过后才增加完成计数。进程被结束后，下次启动会重新读取远端清单和本地状态，逐文件检查；已完成文件复用，未完成文件从文件头重新下载，不做单文件字节级续传。
|
||
|
||
## 九、验证清单
|
||
|
||
- PersistentData 文件正确时不访问 CDN。
|
||
- PersistentData 错误但 StreamingAssets 正确时使用母包文件并处理遮挡旧文件。
|
||
- 两处均无有效文件时从 CDN 下载到默认或外部保存路径。
|
||
- 差异日志在普通资源下载进度之前输出。
|
||
- 两个 Package 共享依赖时只建立一个 `Path + MD5` 任务。
|
||
- 远端 MD5 变化后历史 Package 会参与 `CheckAndDownloadAllFiles`。
|
||
- 下载失败释放进行中任务，下一次请求可以重试。
|
||
- Android/WebGL 的 StreamingAssets 失败会继续 fallback，不会阻塞主线程。
|
||
|
||
## 文档关联
|
||
|
||
| 文档 | 关联原因 |
|
||
|---|---|
|
||
| [资源管理入口](README.md) | 架构、来源顺序和 V2 数据流 |
|
||
| [UI 窗口系统](../UI窗口系统/README.md) | UI 加载与卸载调用方 |
|
||
| [Hotfix 启动](../Hotfix启动.md) | Bootstrap 接入 |
|
||
| [开发规则](../../../rules/20-开发规则.md) | 业务入口和异步规则 |
|