XCEngine/docs/api/resources/resourcepackage/resourcepackage.md

# ResourcePackage

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

**类型**: `class`

**描述**: 资源包读写工具，支持打包多个资源文件到单个包文件中，以及从包中读取资源。

## 概述

`ResourcePackage` 提供了资源打包功能，可以将多个资源文件打包成单个包文件，方便分发和加载。包文件包含文件清单和数据区域。

## 头文件

```cpp
#include <XCEngine/Resources/ResourcePackage.h>
```

---

## PackageFileEntry 结构体

打包文件条目信息。

| 成员 | 类型 | 描述 |
|------|------|------|
| `relativePath` | `Containers::String` | 相对路径 |
| `size` | `size_t` | 文件大小 |
| `checksum` | `Core::uint64` | 校验和 |
| `offset` | `size_t` | 数据偏移量 |

---

## ResourcePackageBuilder

资源包构建器，用于创建新的资源包。

### 构造与析构

| 方法 | 描述 |
|------|------|
| `ResourcePackageBuilder()` | 默认构造 |
| `~ResourcePackageBuilder()` | 析构函数 |

### 包构建

| 方法 | 描述 |
|------|------|
| `bool AddFile(const Containers::String& sourcePath, const Containers::String& relativePath)` | 添加单个文件到包 |
| `bool AddDirectory(const Containers::String& sourceDir, const Containers::String& relativeBase = "")` | 添加整个目录到包（当前为 stub，始终返回 true） |
| `void SetOutputPath(const Containers::String& path)` | 设置输出包文件路径 |
| `const Containers::String& GetOutputPath() const` | 获取输出路径 |
| `bool Build()` | 构建包文件 |
| `float GetProgress() const` | 获取构建进度（0.0f ~ 1.0f） |
| `const Containers::String& GetError() const` | 获取错误信息 |

## 实现说明

**注意**: `ResourcePackageBuilder::AddDirectory()` 当前为 stub，始终返回 true。

## 使用示例（构建）

```cpp
ResourcePackageBuilder builder;

// 添加文件
builder.AddFile("textures/player.png", "textures/player.png");
builder.AddFile("textures/terrain.png", "textures/terrain.png");

// 添加目录
builder.AddDirectory("shaders/", "shaders/");

// 设置输出
builder.SetOutputPath("data/resources.pkg");

// 构建
if (builder.Build()) {
    printf("Package built successfully!\n");
} else {
    printf("Build failed: %s\n", builder.GetError().CStr());
}
```

---

## ResourcePackage

资源包读取器，用于从已打包的文件中读取资源。

### 构造与析构

| 方法 | 描述 |
|------|------|
| `ResourcePackage()` | 默认构造 |
| `~ResourcePackage()` | 析构函数，自动关闭包 |

### 包操作

| 方法 | 描述 |
|------|------|
| `bool Open(const Containers::String& packagePath)` | 打开包文件 |
| `void Close()` | 关闭包文件 |
| `bool IsValid() const` | 检查包是否有效 |

### 文件操作

| 方法 | 描述 |
|------|------|
| `bool Exists(const Containers::String& relativePath) const` | 检查文件是否存在于包中 |
| `Containers::Array<Core::uint8> Read(const Containers::String& relativePath) const` | 读取包内文件 |
| `size_t GetSize(const Containers::String& relativePath) const` | 获取包内文件大小 |
| `void Enumerate(const Containers::String& pattern, Containers::Array<Containers::String>& outFiles) const` | 枚举包内匹配的文件 |

### 包信息

| 方法 | 描述 |
|------|------|
| `const PackageInfo& GetInfo() const` | 获取包信息 |

### PackageInfo 结构体

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

## 使用示例（读取）

```cpp
ResourcePackage package;
if (package.Open("data/resources.pkg")) {
    // 检查文件
    if (package.Exists("textures/player.png")) {
        // 读取文件
        auto data = package.Read("textures/player.png");
        if (!data.Empty()) {
            // 使用数据...
        }
    }
    
    // 获取文件大小
    size_t size = package.GetSize("textures/player.png");
    
    // 枚举文件
    Containers::Array<Containers::String> files;
    package.Enumerate("textures/*.png", files);
    
    // 获取包信息
    auto info = package.GetInfo();
    printf("Package: %s, Files: %zu\n", info.path.CStr(), info.fileCount);
    
    package.Close();
}
```

## 相关文档

- [ResourceFileSystem](../filesystem/filesystem.md) - 资源文件系统
- [Resources 总览](../resources.md) - 返回模块总览