# ResourceFileSystem

## 命名空间

`XCEngine::Resources`

## 类型

| 类型 | 名称 | 描述 |
|------|------|------|
| class | `ResourceFileSystem` | 资源文件系统管理器 |
| class | `IArchive` | 档案压缩包接口 |
| struct | `ResourceInfo` | 资源信息结构 |

## 概述

`ResourceFileSystem` 是 XCEngine 资源管理模块的核心组件，负责管理游戏资源的加载与访问。它支持从文件系统目录和档案压缩包（如 ZIP、Pak 等）中检索资源，并提供统一的资源访问接口。

该类采用单例模式，通过 `Get()` 静态方法获取全局实例。线程安全，通过内部互斥锁保护数据结构。

### 主要功能

- 支持多目录和多档案的资源来源
- 资源路径解析（相对路径 → 绝对路径）
- 资源读取（以字节数组形式返回）
- 资源存在性检查
- 资源元数据查询
- 资源枚举（支持通配符模式）
- 信息缓存以提高查询性能

## 公共方法表格

| 方法 | 签名 | 描述 |
|------|------|------|
| `Initialize` | `void Initialize(const Containers::String& rootPath)` | 初始化资源文件系统，设置根路径 |
| `Shutdown` | `void Shutdown()` | 关闭文件系统，释放所有资源 |
| `AddArchive` | `bool AddArchive(const Containers::String& archivePath)` | 添加档案压缩包作为资源来源 |
| `AddDirectory` | `bool AddDirectory(const Containers::String& directoryPath)` | 添加目录作为资源来源 |
| `RemoveArchive` | `void RemoveArchive(const Containers::String& archivePath)` | 移除指定的档案压缩包 |
| `FindResource` | `bool FindResource(const Containers::String& relativePath, Containers::String& outAbsolutePath) const` | 查找资源并返回绝对路径 |
| `ReadResource` | `Containers::Array<Core::uint8> ReadResource(const Containers::String& relativePath) const` | 读取资源数据 |
| `Exists` | `bool Exists(const Containers::String& relativePath) const` | 检查资源是否存在 |
| `GetResourceInfo` | `bool GetResourceInfo(const Containers::String& relativePath, ResourceInfo& outInfo) const` | 获取资源详细信息 |
| `EnumerateResources` | `void EnumerateResources(const Containers::String& pattern, Containers::Array<ResourceInfo>& outResources) const` | 枚举匹配模式的资源 |
| `Get` | `static ResourceFileSystem& Get()` | 获取单例实例 |

## 使用示例

```cpp
#include "Resources/ResourceFileSystem.h"

using namespace XCEngine;
using namespace XCEngine::Resources;

// 初始化资源文件系统
ResourceFileSystem& fs = ResourceFileSystem::Get();
fs.Initialize("C:/Game/Resources");

// 添加资源来源
fs.AddDirectory("C:/Game/Assets/Textures");
fs.AddArchive("C:/Game/Paks/Common.pak");

// 读取资源
Containers::Array<Core::uint8> data = fs.ReadResource("textures/player/diffuse.png");
if (data.Size() > 0) {
    // 处理资源数据
}

// 检查资源是否存在
if (fs.Exists("shaders/forward.glsl")) {
    // 加载着色器
}

// 获取资源信息
ResourceInfo info;
if (fs.GetResourceInfo("audio/bgm/main_theme.ogg", info)) {
    printf("Resource size: %zu\n", info.size);
}

// 枚举资源
Containers::Array<ResourceInfo> resources;
fs.EnumerateResources("textures/**/*.png", resources);
```

## 相关文档

- [IArchive 接口](iarchive.md)
- [ResourceInfo 结构](resource-info.md)