# Asset

**命名空间**: `XCEngine::Resources`

**类型**: `submodule`

**描述**: 定义项目资产数据库、artifact 缓存、运行时资源加载、句柄、缓存与项目资产查询快照这一整套资源基础设施。

## 概述

当前 `Core/Asset` 已经不只是“运行时按路径加载资源”的薄层接口，而是可以分成三层来看：

1. [AssetDatabase](AssetDatabase/AssetDatabase.md)
   负责扫描项目 `Assets`、维护 `.meta`、保存 source/artifact 索引，并在需要时把源资产导入成 `Library/Artifacts/...` 下的 artifact。
2. [AssetImportService](AssetImportService/AssetImportService.md) + [ProjectAssetIndex](ProjectAssetIndex/ProjectAssetIndex.md)
   负责把 `AssetDatabase` 包装成线程安全服务，并导出供热路径查询使用的 path/GUID snapshot。
3. [ResourceManager](ResourceManager/ResourceManager.md)
   负责运行时加载、缓存、句柄与 loader 分发；当设置了项目根目录后，它会先经 `AssetImportService` 准备 artifact，再通过 `ProjectAssetIndex` 做 `AssetRef` / 路径查询。

这意味着当前资源系统的真实链路是：

```text
Assets/... source files
-> AssetDatabase
-> AssetImportService
-> ProjectAssetIndex snapshot
-> ResourceManager
-> concrete loader / runtime resource
```

其中，[AssetGUID](AssetGUID/AssetGUID.md)、[AssetRef](AssetRef/AssetRef.md) 和 [ArtifactFormats](ArtifactFormats/ArtifactFormats.md) 分别补上了“资产身份”“资产引用”和“artifact 磁盘格式”这三块基础协议。

## 当前实现关系

- `editor/src/Application.cpp` 初始化编辑器时会调用 `ResourceManager::SetResourceRoot(projectRoot)`，从而绑定项目根、初始化 `ResourceFileSystem`，并刷新 `ProjectAssetIndex` 快照。
- `ResourceManager::LoadResource()` 在加载项目资产时，会先调用 `AssetImportService::EnsureArtifact()`；只有 artifact 就绪后，才把 `ImportedAsset::runtimeLoadPath` 交给具体 loader。
- `ProjectAssetIndex::TryGetAssetRef()` 当前会优先查本地 snapshot，cache miss 时再回退到 `AssetImportService`；必要时会先 `Refresh()` 数据库再整体重建 snapshot。
- `ProjectAssetIndex::TryResolveAssetPath()` 当前同样优先查 snapshot，但 miss 时只回退到 `AssetImportService::TryGetPrimaryAssetPath()`，不会主动刷新整份 snapshot。
- `engine/src/Resources/Material/MaterialLoader.cpp` 现在已经把材质纹理路径解析、`.xcmat` 中的 texture `AssetRef` 回读，以及首次访问时的懒加载纳入真实行为范围，因此 `AssetDatabase` 的材质依赖快照不再只是预留设计。
- `.xcmat` 当前已经是 material artifact v2：texture binding 会同时写出编码后的 `AssetRef` 和可选路径字符串，后续由 `MaterialLoader` 与 `Material` 协作懒解析成真正贴图句柄。

## 设计要点

- 把“项目资产身份与导入缓存”和“运行时资源实例加载”拆成两层，避免 `ResourceManager` 直接承载 GUID、`.meta` 和 artifact 细节。
- 再引入 `AssetImportService + ProjectAssetIndex` 作为服务层和只读快照层，把线程同步、项目根切换和高频查询从 `AssetDatabase` 与 `ResourceManager` 本体里拆出来。
- `AssetDatabase` 通过 `guid + importer + source/meta/dependency snapshot` 生成 `artifactKey`，让重导入条件可复现。
- `ResourceManager` 仍保留 `builtin://` 这类虚拟路径直载能力；只有能解析到项目 `Assets` 的路径才会进入项目资产链路。
- `ResourceHandle`、`ResourceCache` 和 `AsyncLoader` 继续围绕运行时 `IResource` 实例运转，而不是直接把 source asset 当作运行时对象。

## 当前实现边界

- `AssetDatabase` 当前只有 `TextureImporter`、`MaterialImporter` 和 `ModelImporter` 会产出 artifact；`FolderImporter` 和 `DefaultImporter` 只保留 source 记录。
- `.meta` 文件当前只保存 `guid`、`folderAsset`、`importer` 和 `importerVersion`，还没有持久化 importer 专属设置。
- `ProjectAssetIndex` 当前只缓存主资产路径，生成的 `AssetRef` 仍默认使用 `kMainAssetLocalID`。
- `ResourceManager` 会在同步加载路径里触发 artifact 生成，但当前没有后台导入队列或文件监听闭环。
- `LoadAsync()` / `AsyncLoader` 当前已经具备真实的工作线程与完成队列闭环，但回调仍依赖 `Update()` 手动轮询分发，取消与配置所有权语义也还比较原始。

## 头文件

- [ArtifactFormats](ArtifactFormats/ArtifactFormats.md) - `ArtifactFormats.h`
- [AssetDatabase](AssetDatabase/AssetDatabase.md) - `AssetDatabase.h`
- [AssetGUID](AssetGUID/AssetGUID.md) - `AssetGUID.h`
- [AssetImportService](AssetImportService/AssetImportService.md) - `AssetImportService.h`
- [AssetRef](AssetRef/AssetRef.md) - `AssetRef.h`
- [AsyncLoader](AsyncLoader/AsyncLoader.md) - `AsyncLoader.h`
- [ImportSettings](ImportSettings/ImportSettings.md) - `ImportSettings.h`
- [IResource](IResource/IResource.md) - `IResource.h`
- [ProjectAssetIndex](ProjectAssetIndex/ProjectAssetIndex.md) - `ProjectAssetIndex.h`
- [ResourceCache](ResourceCache/ResourceCache.md) - `ResourceCache.h`
- [ResourceDependencyGraph](ResourceDependencyGraph/ResourceDependencyGraph.md) - `ResourceDependencyGraph.h`
- [ResourceHandle](ResourceHandle/ResourceHandle.md) - `ResourceHandle.h`
- [ResourceManager](ResourceManager/ResourceManager.md) - `ResourceManager.h`
- [ResourceTypes](ResourceTypes/ResourceTypes.md) - `ResourceTypes.h`

## 推荐阅读顺序

1. 先读 [AssetGUID](AssetGUID/AssetGUID.md) 与 [AssetRef](AssetRef/AssetRef.md)，理解项目资产的身份与引用契约。
2. 再读 [AssetDatabase](AssetDatabase/AssetDatabase.md) 与 [ArtifactFormats](ArtifactFormats/ArtifactFormats.md)，理解 source asset 如何导入为 `Library/Artifacts` 下的 artifact。
3. 然后读 [AssetImportService](AssetImportService/AssetImportService.md) 与 [ProjectAssetIndex](ProjectAssetIndex/ProjectAssetIndex.md)，理解数据库如何被包装成线程安全服务和热路径查询缓存。
4. 接着读 [ResourceManager](ResourceManager/ResourceManager.md) 与 [ResourceHandle](ResourceHandle/ResourceHandle.md)，理解运行时如何消费这些 artifact 和 snapshot。
5. 最后再看 [ResourceCache](ResourceCache/ResourceCache.md)、[AsyncLoader](AsyncLoader/AsyncLoader.md) 和 [ResourceDependencyGraph](ResourceDependencyGraph/ResourceDependencyGraph.md)，理解缓存、异步与依赖管理的现状。

## 相关指南

- [Resource Lifecycle And Handles](../../../_guides/Core/Asset/Resource-Lifecycle-And-Handles.md)

## 相关文档

- [上级目录](../Core.md)
- [API 总索引](../../../main.md)