XCEngine/docs/api/resources/resource-package/index.md

# ResourcePackage 类

## 命名空间

`XCEngine::Resources`

## 类型

类 (Class)

## 描述

ResourcePackage 是 XCEngine 资源包的核心类，用于读取和管理 `.xcp` 格式的资源包文件。资源包是一种将多个资源文件打包成单一文件的格式，支持文件枚举、读取和校验。

## 概述

ResourcePackage 提供了一套完整的资源包读取接口，包括打开/关闭包、查询文件存在性、读取文件内容、获取文件大小以及枚举包内文件等功能。包文件格式采用二进制结构，包含文件头、清单和数据区域。

包文件格式：
- **文件头** (20 字节): 魔数 "XCRP" (4B) + 版本号 (2B) + 清单大小 (4B) + 文件数量 (4B) + 数据偏移 (8B)
- **清单区域**: 存储文件元数据列表
- **数据区域**: 存储实际文件数据

## 公共方法表格

| 方法 | 签名 | 描述 |
|------|------|------|
| [Open](open.md) | `bool Open(const Containers::String& packagePath)` | 打开资源包文件 |
| [Close](close.md) | `void Close()` | 关闭资源包并释放资源 |
| [IsValid](isvalid.md) | `bool IsValid() const` | 检查包是否有效 |
| [Exists](exists.md) | `bool Exists(const Containers::String& relativePath) const` | 检查文件是否存在 |
| [Read](read.md) | `Containers::Array<Core::uint8> Read(const Containers::String& relativePath) const` | 读取文件内容 |
| [GetSize](getsize.md) | `size_t GetSize(const Containers::String& relativePath) const` | 获取文件大小 |
| [Enumerate](enumerate.md) | `void Enumerate(const Containers::String& pattern, Containers::Array<Containers::String>& outFiles) const` | 枚举匹配的文件 |
| [GetInfo](getinfo.md) | `const PackageInfo& GetInfo() const` | 获取包信息 |

## 嵌套类型

### PackageInfo

包文件的元信息结构体。

| 成员 | 类型 | 描述 |
|------|------|------|
| `path` | `Containers::String` | 包文件路径 |
| `version` | `Core::uint16` | 包文件版本号 |
| `fileCount` | `size_t` | 包内文件数量 |
| `totalSize` | `size_t` | 包文件总大小 |

## 使用示例

```cpp
#include <XCEngine/Core/IO/ResourcePackage.h>

using namespace XCEngine;
using namespace XCEngine::Containers;
using namespace XCEngine::Resources;

// 打开资源包
ResourcePackage package;
if (!package.Open("assets/resources.xcp")) {
    // 处理打开失败
    return;
}

// 检查文件是否存在
if (package.Exists("textures/player.png")) {
    // 读取文件
    Array<uint8> data = package.Read("textures/player.png");
    // 处理数据...
}

// 获取文件大小
size_t size = package.GetSize("textures/player.png");

// 枚举所有文件
Array<String> files;
package.Enumerate("*", files);
for (const auto& file : files) {
    printf("Found file: %s\n", file.CStr());
}

// 获取包信息
const auto& info = package.GetInfo();
printf("Package: %s, Version: %u, Files: %zu\n", 
       info.path.CStr(), info.version, info.fileCount);

// 关闭资源包
package.Close();
```

## 相关文档

- [ResourceTypes](../resourcetypes/resourcetypes.md) - 资源类型定义