lms
bdadfd5759
- 增加 UTF-8 输出编码设置 - 增加 Unity Assets/ 路径中文检查 - 增加未跟踪 Markdown 专项提示 - 修正 AssestBundle -> AssetBundle 拼写 - 细化 commit-module-mappings 中 entity/event/scene/network/skill/pool/ui/resource 映射 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
171 lines
7.3 KiB
Markdown
171 lines
7.3 KiB
Markdown
# 资源管理
|
||
|
||
## 目的
|
||
|
||
资源管理负责 AssetBundle、依赖、语言资源、SpriteAtlas、内存卸载、启动代码更新和普通资源分包下载。
|
||
|
||
## 源码边界
|
||
|
||
| 类型 | 路径 | 说明 |
|
||
|---|---|---|
|
||
| ESF AssetBundle 源码 | `Assets/StrayFog/Editor/CopyToX/CopyToHF/AssetBundle/` | 框架修改源头 |
|
||
| HF AssetBundle 代码 | `Assets/Game/GameHFScripte/CopyToHF/AssetBundle/` | CopyToX 生成，禁止手改 |
|
||
| V2 公共运行时 | `Assets/StrayFog/Core/SFSubPackageV2.cs` | 非热更层与热更层共享下载状态 |
|
||
| V2 编辑器构建 | `Assets/StrayFog/Editor/Tools/AssetBundle/` | 包配置、校验、清单和枚举生成 |
|
||
| 热更业务门面 | `Assets/Game/GameHFScripte/GameFunction/HFDownLoadSubPackage/` | 普通资源下载 API |
|
||
| 启动代码入口 | `Assets/Game/GameMono/Scripts/GameDllManager.cs` | Bootstrap 校验、下载和加载 |
|
||
|
||
修改 `ESF_` 后执行 CopyToX，再检查生成的 `HF_` 差异和 `GameHF` 编译结果。
|
||
|
||
## AssetBundle 加载
|
||
|
||
```text
|
||
HFFunCatalogue.Asset / HFABMgr.LoadInMemory
|
||
-> 读取 AssetBundleManifest
|
||
-> 语言与路径修正
|
||
-> 创建或复用 HFAssetLoader
|
||
-> 加载依赖 Bundle
|
||
-> 加载主 Bundle
|
||
-> HFAssetResponse.GetAsset<T>()
|
||
```
|
||
|
||
`HFABMgr` 继续作为统一入口，并使用 partial 文件组织 Manifest、Loader、GC、路径和模式逻辑。内部职责可以封装，但业务入口不拆散。
|
||
|
||
### Manifest 与来源顺序
|
||
|
||
Editor 模式直接读取工程资源。Player 本地模式按以下顺序初始化 Manifest：
|
||
|
||
```text
|
||
PersistentData Manifest
|
||
-> 不存在或无效时读取 StreamingAssets Manifest
|
||
-> 两处都不可用且已配置 CDN 时读取 CDN Manifest
|
||
```
|
||
|
||
- PersistentData 保存热更新后的可写资源，优先于母包资源。
|
||
- StreamingAssets 是只读随包资源；Android、WebGL 等 URL 路径通过 UnityWebRequest 协程读取。
|
||
- CDN 是本地 Manifest 都不可用或资源需要更新时的远端来源。
|
||
- 显式 CDN/小游戏模式按平台适配层和缓存回调工作，不假设普通文件系统可用。
|
||
- `Application.dataPath` 只用于 `UNITY_EDITOR` 下的资源定位和分析。
|
||
|
||
PersistentData 普通文件优先使用 `AssetBundle.LoadFromFileAsync`。StreamingAssets URL、CDN byte[]、小游戏缓存和需要解密的数据继续使用 `LoadFromMemoryAsync`。
|
||
|
||
### CDN 落盘
|
||
|
||
`SetCdnSaveRootPath(string)` 允许平台层传入保存根目录。有效外部路径优先；未设置时使用 `SFGlobalData.assetBundleRoot`，即项目 PersistentData 资源根目录。保存时保留相对目录结构。
|
||
|
||
## 内存与卸载
|
||
|
||
- GC 与主动卸载共用 loader 释放流程。
|
||
- 释放时调用 `AssetBundle.Unload(false)`，销毁 loader，并同步清理 loader 映射、生命周期池和内存统计。
|
||
- 按资源名卸载只在唯一匹配且 loader 可卸载时成功；未找到、重名、加载未完成或仍有请求时返回 `false`。
|
||
- 内存大小使用 loader 统计或本地文件长度估算，只用于运行时观察，不替代 Unity Profiler。
|
||
|
||
公开使用方式见 [资源管理使用指南](使用指南.md)。
|
||
|
||
## 分包 V2
|
||
|
||
V2 将编辑器构建清单与设备下载状态分离。运行时只消费编辑器生成的 V2 清单，不识别旧 `SPI_*` 结构。
|
||
|
||
### 编辑器阶段
|
||
|
||
资源包通过 Unity 编辑器自由配置，XML 只负责持久化。每个 Package 包含：
|
||
|
||
- `Id`、`DisplayName`、`Priority`、`BuiltIn`
|
||
- `RootPaths[]`
|
||
- `DependencyPackageIds[]`
|
||
|
||
保存和构建会校验空/重复 ID、无效路径、自依赖、缺失依赖和循环依赖。根路径使用标准化小写路径与目录边界前缀匹配；重叠目录警告但允许构建。
|
||
|
||
构建顺序：
|
||
|
||
```text
|
||
普通 AssetBundle
|
||
-> AOT 与 HotUpdate DLL 产物
|
||
-> 收集最终文件
|
||
-> 生成 V2 subpackage.json
|
||
-> 复制 BuiltIn 文件并生成分析结果
|
||
```
|
||
|
||
生成清单的同时生成 `enHFSubPackageId.cs`。枚举成员由 PackageId 转换，XML 注释使用 DisplayName；业务通过映射恢复原始 PackageId，生成文件禁止手改。
|
||
|
||
### V2 清单
|
||
|
||
```text
|
||
Version / Platform / BuildId
|
||
BootstrapFiles[] AOT 与 HotUpdate 启动代码
|
||
Files[] 普通 AB 的 Path、MD5、Size、Dependencies
|
||
Packages[] 包配置、FilePaths 和 Size
|
||
```
|
||
|
||
- `BootstrapFiles` 按 `CodeKind` 和 `LoadOrder` 控制 AOT、HotUpdate 加载顺序。
|
||
- `Files` 以标准化 Path 全局唯一，依赖来自 Unity AssetBundleManifest。
|
||
- `Packages` 没有固定业务类型；PackageId 的业务意义由调用方决定。
|
||
- Package 显式依赖和 AB 文件依赖是两套关系，运行时都会递归展开。
|
||
|
||
### 运行时顺序
|
||
|
||
```text
|
||
下载并校验远端 V2 清单
|
||
-> 比对 BootstrapFiles
|
||
-> PersistentData 命中则复用
|
||
-> 否则检查 StreamingAssets
|
||
-> 仍不匹配则从 CDN 下载到临时文件并校验 MD5
|
||
-> AOT 加载成功
|
||
-> HotUpdate 加载与入口执行成功
|
||
-> CommitBootstrapCodeLoaded 提交清单和状态
|
||
-> 普通资源比对与下载开放
|
||
```
|
||
|
||
Bootstrap 是普通资源的硬门禁。清单、下载、MD5、AOT、HotUpdate 或入口任一步失败都不会开放普通资源阶段。
|
||
|
||
CDN URL 使用：
|
||
|
||
```text
|
||
{BaseUrl}/{AppPartner}/{AppVersion}/{Platform}/{FilePath}
|
||
```
|
||
|
||
BaseUrl 按配置顺序尝试，使用 `/` 进行 URI 拼接。Bootstrap 文件最多三轮，每轮尝试全部有效 BaseUrl；普通文件一次请求按顺序尝试有效地址。
|
||
|
||
### 普通资源更新范围
|
||
|
||
`CheckAndDownloadAllFiles` 不会无条件下载整个 `Files[]`，它处理：
|
||
|
||
- 未归属任何 Package 的基础文件。
|
||
- `BuiltIn = true` 的 Package 及依赖包。
|
||
- `DownloadedPackageIds` 中历史成功下载的 Package 及依赖包。
|
||
- 上述文件的完整 AB 依赖闭包。
|
||
|
||
从未下载、非 BuiltIn 的可选 Package 不会被全量更新误下载。业务可按 PackageId 主动下载，资源加载缺文件时也可按 `Files[]` 下载目标文件依赖闭包。
|
||
|
||
### 状态与去重
|
||
|
||
`subpackage_state.json` 当前保存：
|
||
|
||
- `BuildId`
|
||
- `DownloadedFiles` 的 Path 与 MD5
|
||
- `DownloadedPackageIds`
|
||
|
||
Package 完整成功后才记录请求包和依赖包。查询 Package 是否完成时会同时检查当前清单、PackageId 状态、依赖包状态和所有文件 MD5。
|
||
|
||
去重分为三层：清单 Path 唯一、进行中任务按 `Path + MD5` 合并、本地文件和状态校验通过后复用。文件只有完整写入并通过 MD5 后才更新状态和进度计数。
|
||
|
||
## 验证重点
|
||
|
||
- PersistentData、StreamingAssets 和 CDN 的 Manifest 回退不会卡住主线程。
|
||
- 本地文件使用正确加载策略，平台 URL 使用协程。
|
||
- GC/主动卸载后能重新加载，loader 映射和内存统计正确。
|
||
- V2 差异结果在下载前回调，失败信息包含 Path、期望 MD5 和尝试 URL。
|
||
- 冷启动会从状态继续按文件校验，已完成文件不重复下载。
|
||
- 已下载 Package 在远端 MD5、依赖或 FilePaths 变化后参与更新。
|
||
|
||
## 文档关联
|
||
|
||
| 文档 | 关联原因 |
|
||
|---|---|
|
||
| [资源管理使用指南](使用指南.md) | 业务调用、卸载、内存和分包 API |
|
||
| [模块索引](../../模块索引.md) | 模块入口和状态 |
|
||
| [UI 窗口系统](../UI窗口系统/README.md) | UI Prefab 加载与卸载 |
|
||
| [Hotfix 启动](../Hotfix启动.md) | Bootstrap 代码加载入口 |
|
||
| [架构说明](../../../rules/10-架构说明.md) | ESF/HF 源码边界 |
|
||
| [工作流清单](../../../rules/40-工作流清单.md) | 生成和平台验证流程 |
|