# IO

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

**类型**: `submodule`

**描述**: 定义资源路径辅助、资源加载器接口、包文件与虚拟文件系统相关基础设施。

## 概览

`Core/IO` 这个目录在物理结构上属于 `Core`，但逻辑命名空间已经落在 `XCEngine::Resources`。它承担的是“资源系统和底层文件访问之间的桥梁层”：

- [ResourcePath](ResourcePath/ResourcePath.md) 负责轻量路径拆分和 GUID 派生
- [IResourceLoader](IResourceLoader/IResourceLoader.md) 负责把磁盘数据转换成运行时 `IResource`
- [FileArchive](FileArchive/FileArchive.md) 和 [ResourcePackage](ResourcePackage/ResourcePackage.md) 负责资源容器抽象
- [ResourceFileSystem](ResourceFileSystem/ResourceFileSystem.md) 试图把目录、归档和包文件统一到一个虚拟资源访问入口

从设计方向看，这一层很像商业引擎里的 runtime file access / resource loading substrate。它不是完整的编辑器资产数据库，更接近运行时资源读取和格式装载层。

## 设计要点

- `IResourceLoader` 是当前最关键的接口，因为 [ResourceManager](../Asset/ResourceManager/ResourceManager.md) 最终就是靠它真正加载资源。
- `ResourcePath` 只是字符串辅助类，不负责真实文件系统查询、标准化或路径规范化。
- `FileArchive`、`ResourcePackage`、`ResourceFileSystem` 已经搭好了虚拟文件系统方向的 API 轮廓，但当前实现普遍还比较早期。
- 当前这层里存在一些需要明确写进文档的实现差异，例如：
  - `ResourcePath::GetExtension()` 返回带点扩展名，如 `.png`
  - `IResourceLoader::GetExtension()` 返回不带点扩展名，如 `png`

## 当前实现现状

- 真正稳定可用的主路径仍然是“具体 loader + [ResourceManager](../Asset/ResourceManager/ResourceManager.md) 同步加载”。
- `ResourcePath` 当前可用于做名称拆分和 GUID 生成，但不应被理解成跨平台标准化路径工具。
- `FileArchive` 当前更像“目录前缀适配器”，不是真正的压缩归档读取器。
- `ResourcePackage` 的 builder 和 reader 当前还没有形成闭环。
- `ResourceFileSystem` 的虚拟文件系统层当前仍有明显占位实现和行为缺口。

## 头文件

- [FileArchive](FileArchive/FileArchive.md) - `FileArchive.h`
- [IResourceLoader](IResourceLoader/IResourceLoader.md) - `IResourceLoader.h`
- [ResourceFileSystem](ResourceFileSystem/ResourceFileSystem.md) - `ResourceFileSystem.h`
- [ResourcePackage](ResourcePackage/ResourcePackage.md) - `ResourcePackage.h`
- [ResourcePath](ResourcePath/ResourcePath.md) - `ResourcePath.h`

## 推荐阅读顺序

1. 先读 [ResourcePath](ResourcePath/ResourcePath.md)，理解当前路径字符串约定和 GUID 派生方式。
2. 再读 [IResourceLoader](IResourceLoader/IResourceLoader.md)，这是连接 IO 层和 Asset 层的关键接口。
3. 然后读 [ResourceFileSystem](ResourceFileSystem/ResourceFileSystem.md)，了解当前虚拟文件系统层的设计方向和限制。
4. 最后再读 [FileArchive](FileArchive/FileArchive.md) 和 [ResourcePackage](ResourcePackage/ResourcePackage.md)，理解当前容器格式支持做到哪一步。

## 相关指南

- [Resource Paths, Packages, And Virtual File System](../../../_guides/Core/IO/Resource-Paths-Packages-And-Virtual-FileSystem.md)

## 相关文档

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