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

ResourcePackage

命名空间: XCEngine::Resources

类型: class

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

概述

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

头文件

#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。

使用示例（构建）

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	总大小

使用示例（读取）

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 - 资源文件系统
• Resources 总览 - 返回模块总览