# Asset

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

**类型**: `submodule`

**描述**: 定义运行时资源系统的标识、句柄、缓存、加载和依赖管理基础设施。

## 概览

`Core/Asset` 是当前引擎运行时资源系统的基础层。它并不直接实现材质、着色器、网格或音频资源本身，而是提供一套更底层的通用约定：

- 用 [ResourceTypes](ResourceTypes/ResourceTypes.md) 定义资源类型和 GUID 规则
- 用 [IResource](IResource/IResource.md) 约束资源对象的最小公共接口
- 用 [ImportSettings](ImportSettings/ImportSettings.md) 传递资源导入配置
- 用 [ResourceManager](ResourceManager/ResourceManager.md) 做同步加载、加载器注册和引用计数入口
- 用 [ResourceHandle](ResourceHandle/ResourceHandle.md) 在上层代码里传递带类型的资源引用
- 用 [ResourceCache](ResourceCache/ResourceCache.md)、[AsyncLoader](AsyncLoader/AsyncLoader.md)、[ResourceDependencyGraph](ResourceDependencyGraph/ResourceDependencyGraph.md) 为缓存、异步加载和依赖卸载预留基础结构

从设计意图上看，这一层更接近商业引擎里“运行时资源服务”的雏形，而不是 Unity `AssetDatabase` 那类编辑器资产数据库。它强调的是运行时可加载、可引用、可扩展，而不是导入流水线和编辑器管理界面。

## 设计要点

- 资源身份和资源对象分离。`ResourceGUID` 负责标识，`IResource` 负责对象实例，`ResourceHandle<T>` 负责类型化访问。
- 资源类型分派依赖 `GetResourceType<T>()` 模板特化，而不是 RTTI 或字符串注册。
- `ResourceManager` 当前是主入口，但它和 `ResourceCache`、`AsyncLoader`、`ResourceDependencyGraph` 的集成还没有完全做完。
- 当前自动注册的内建 loader 只有 `MaterialLoader` 和 `ShaderLoader`。
- 这套接口已经有明显的“未来做流式加载和资源依赖卸载”的方向，但当前很多能力仍处于占位或半成品状态。

## 当前实现现状

- 同步加载路径是当前最可靠的使用方式。
- `Load<T>()` 直接把传入路径交给 loader，当前不会自动调用 `ResolvePath()`，所以 `SetResourceRoot()` 只是一个路径拼接辅助，不是统一的实际加载入口。
- `LoadAsync()` 已经有 API 形状，但当前队列不会被后台线程消费，成功回调路径也没有闭环，不能把它当成成熟的异步流式系统。
- `ResourceManager`、`ResourceCache` 和句柄引用计数之间还没有完全打通，文档里会明确标出这些差异，而不把它们包装成“完整资源生命周期管理”。

## 头文件

- [AsyncLoader](AsyncLoader/AsyncLoader.md) - `AsyncLoader.h`
- [ImportSettings](ImportSettings/ImportSettings.md) - `ImportSettings.h`
- [IResource](IResource/IResource.md) - `IResource.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. 先读 [ResourceTypes](ResourceTypes/ResourceTypes.md)，理解 `ResourceType` 和 `ResourceGUID`。
2. 再读 [IResource](IResource/IResource.md) 与 [ImportSettings](ImportSettings/ImportSettings.md)，理解资源对象和导入配置契约。
3. 然后读 [ResourceManager](ResourceManager/ResourceManager.md) 与 [ResourceHandle](ResourceHandle/ResourceHandle.md)，这是当前实际最常用的运行时入口。
4. 最后再读 [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)