2个不稳定版本

0.2.0 2022年2月11日
0.1.0 2022年2月7日

#730 in 游戏开发


用于2个Crate(通过treasury-store

MIT/Apache

33KB
765

库资源

crates docs actions MIT/Apache loc

库资源是一个易于使用的库和工具集合,用于为游戏引擎或其他应用程序创建资源管道。

目录

💻 安装

库资源提供的应用程序可以使用 cargo 安装。

要安装 treasury-server,请运行

cargo install treasury-server

要安装 treasury 命令行工具

cargo install treasury-cli

✋ 使用

⚡ 初始化

要开始使用库资源,必须创建一个实例。库资源实例由 Treasury.toml 文件定义。文件的父目录称为 "基础目录"。

此文件可以手动创建 👷 或使用以下方法

  • 命令行工具

    treasury init
    

    将使用当前目录作为基础来初始化库资源实例。

    treasury --base <path> init
    

    将使用基础目录 <path> 来初始化库资源实例。

  • 客户端库API提供了方法 Client::local。将 init 参数设置为 true 时,它将初始化库资源。这在上面的CLI调用中内部使用。

⚡ 配置

默认的 Treasury.toml 文件看起来像这样

是的,空文件。

有四个字段可以覆盖。

  • artifacts = "<path>"
    

    将覆盖工件目录到指定的相对于 <base> 的路径。默认为 <base>/treasury/artifacts

    工件目录是所有工件存储的地方。这可以,而且 不应该 被版本控制系统覆盖。如果路径在存储库内部,则应该被忽略。如果库资源创建工件目录(在存储工件且目录不存在时),它将创建一个包含 "*" 的 .gitignore 文件。

  • external = "<path>"
    

    将覆盖外部目录到相对于 <base> 指定的路径。默认为 <base>/treasury/external

    外部目录用于存储远程资产的元数据文件。此目录 应该 在存储库中,并且不应被版本控制系统忽略。

  • temp = "<path>"
    

    将覆盖临时文件的默认目录。默认为 std::env::temp_dir() 的结果。临时文件用作下载的源文件的中间存储,以便导入器使用和导入器的输出。

  • importers = ["<list>", "<of>", "<paths>"]
    

    将指定此实例应使用的导入器库。
    对于 Rust 项目,它们通常位于 cargo 工作空间的 target 目录中。

初始化 Treasury 实例后,可以用于存储和检索资产。

⚡ 存储

在 Treasury 中存储资产非常简单。使用 CLI 看起来是这样的

treasury store <source-path> <target-format>

如果存储操作成功,输出中的最后一行将包含 AssetId。否则将打印错误。

如果源格式不明确,可以在目标格式之后指定。

treasury store <source-path> <target-format> <source-format>

要使用 URL 存储资产,请使用 --url(短 -u)标志。

treasury store --url <source-url> <target-format> <source-format>

没有此标志,源参数始终解释为文件路径。使用此标志,源参数始终解释为 URL。它也可以是 file: URL。

使用库 API 存储时,使用 treasury_client::Client::store_asset 方法。

存储过程

整个过程可以描述为四个步骤

  1. 用户提供资产源,端应用将使用的目标格式,以及可选的源格式。如果模糊,则需要源格式。
  2. 注册的导入器运行并处理资产为工件。
  3. Treasury 存储生成的工件。它避免存储重复项,尽管不同的资产可能指向同一个工件。
  4. 返回 AssetId。

⚡ 检索

用户可以使用资产源和目标格式或 AssetId 检索已存储资产的工件。工件应始终使用 AssetId。当资产源迁移时,.treasury 文件应随之迁移。在这种情况下,不需要重新导入,并且它们的 AssetId 将保留。

⚡ 导入器

为了存储资产,需要导入器将资产源 🥚 转换为工件 🐤。

导入器是实现了 treasury_import::Importer 特性的类型。
Treasury 可以配置为从动态库加载导入器。

为了简化编写导入器库并最大限度地减少由无效实现引起的问题,应使用 treasury_import::make_treasury_importers_library 宏。
此宏将导出服务器期望的所有符号。它将确保使用 treasury_import crate 的主要版本进行 ABI 兼容性。此宏及其生成的代码将执行所有不安全的操作,使导入器库的作者拥有简单且 100% 安全的 Rust。

示例导入器

基本的导入器库可能看起来像这样

# Cargo.toml
[package]
name = "my-importer"
version = "0.1.0"
edition = "2021"

[lib]
crate-type = ["cdylib"]

[dependencies]
treasury-import = { path = "../../import" }
//! src/lib.rs
struct MyImporter;

impl treasury_import::Importer for MyImporter {
    fn import(
        &self,
        source: &std::path::Path,
        output: &std::path::Path,
        _sources: &impl treasury_import::Sources,
        _dependencies: &impl treasury_import::Dependencies,
    ) -> Result<(), treasury_import::ImportError> {
        match std::fs::copy(source, output) {
          Ok(_) => Ok(()),
          Err(err) => Err(treasury_import::ImporterError::Other { reason: "SOMETHING WENT WRONG".to_owned() }),
        }
    }
}


// Define all required exports.
treasury_import::make_treasury_importers_library! {
    // [extensions list]  <name> : <source-format> -> <target-format> = <expr>;
    // <expr> must have type &'static I where I: Importer
    // Use `Box::leak(importer)` if importer instance cannot be constructed in constant expression.
    [foo] foo : foo -> foo = &FooImporter;
}

导入过程中产生的工件应始终使用 AssetId 来引用依赖。资产源文件可以包含路径(相对于源文件或绝对路径)或URL,可以通过 Dependencies 容易地将其转换为 AssetId。如果找不到依赖项,应返回 ImportResult::RequireDependencies { ... }。存储过程将尝试存储依赖项并重试导入。

缺少什么?

目前该项目是资产管道的裸骨实现。

  • 打包尚未实现。必须有一种方法可以将工件子集打包成优化用于磁盘存储和无需间接引用的包。
  • 服务器尚未准备好在远程模式下使用。为了准备这一点,服务器应该能够从请求存储操作的客户机获取本地源数据。
  • 目前仅支持 file:data: URLs。这对于处理本地资产是足够的。
  • 🔥 热重载 🔥 还不可用,因为服务器不监视 👀 源文件的变化。

许可协议

许可方式为以下之一

任选其一。

贡献

除非您明确表示,否则根据 Apache-2.0 许可证定义的,您有意提交给作品的所有贡献,均应按上述方式双许可,不附加任何额外条款或条件。

依赖项

~0.7–1.4MB
~29K SLoC