bevy-persistent

一个 Bevy 辅助工具，用于轻松管理需要跨游戏会话持久化的资源。

背景

在游戏中，有很多资源需要在游戏会话之间持久化

• 统计数据（例如，高分，死亡次数，游戏时间）
• 设置（例如，按键绑定，游戏难度，音频设置）
• 状态（例如，最后一个窗口的位置和大小，保存）
• 等等...

这个包旨在简化此类资源的管理！

安装

支持所有存储格式

cargo add bevy-persistent --features all

或明确指定

cargo add bevy-persistent --features bincode,ini,json,toml,yaml

当然，您也可以仅选择您计划使用的存储格式

cargo add bevy-persistent --features bincode,toml

使用方法

序言

您只需要 Persistent<R> 和 StorageFormat 类型即可使用此库，并且它们是从序言模块导出的。

use bevy_persistent::prelude::*;

定义

您需要定义您想要持久化的 Resource，并且它需要实现来自 serde 的 Serialize 和 Deserialize 特性。

#[derive(Resource, Serialize, Deserialize)]
struct KeyBindings {
    jump: KeyCode,
    crouch: KeyCode,
}

创建

在您的设置系统中，您可以创建持久化资源并将其插入到您的游戏中。

fn setup(mut commands: Commands) {
    let config_dir = dirs::config_dir().unwrap().join("your-amazing-game");
    commands.insert_resource(
        Persistent::<KeyBindings>::builder()
            .name("key bindings")
            .format(StorageFormat::Toml)
            .path(config_dir.join("key-bindings.toml"))
            .default(KeyBindings { jump: KeyCode::Space, crouch: KeyCode::C })
            .build()
            .expect("failed to initialize key bindings")
    )
}

如果是第一次运行，资源将具有指定的默认值，并将该默认值保存到指定的路径（指定的格式）。否则，按键绑定将从指定的路径（使用指定的格式）加载。

访问

要访问资源，您可以使用类型为 Res<Persistent<R>> 的参数。

fn access_key_bindings(key_bindings: Res<Persistent<KeyBindings>>) {
    log::info!("you can crouch using {:?}", key_bindings.crouch);
}

Persistent<R> 实现了 Deref<Target = R>，因此您可以轻松访问资源的公共字段和方法。

修改

要修改资源，您可以使用类型为 ResMut<Persistent<R>> 的参数。

fn modify_key_bindings(mut key_bindings: ResMut<Persistent<KeyBindings>>) {
    key_bindings.update(|key_bindings| {
        key_bindings.crouch = KeyCode::ControlLeft;
    }).expect("failed to update key bindings");
}

Persistent<R> 有 set 和 update 方法来修改底层资源。这两个方法在返回之前都会将更新后的资源写入磁盘。

如果在任何环节发生错误（例如，没有权限读取/写入指定的路径），将返回错误，但底层对象将被更新，新值将在游戏的其余部分可见。然而，它不会持久化到下一次游戏会话！

手动持久化

有些资源更新频繁，每次小更新都进行持久化可能并不理想。或者持久化可能需要手动触发（例如，在游戏中的某些特定点自动保存）。

对于此类情况，您可以避免使用 set 和 update 方法，并直接更新资源。

fn modify_key_bindings(mut key_bindings: ResMut<Persistent<KeyBindings>>) {
    key_bindings.crouch = KeyCode::ControlLeft;
}

当您希望资源与其当前值一起持久化时，可以使用 persist 方法。

fn persist_key_bindings(key_bindings: Res<Persistent<KeyBindings>>) {
    key_bindings.persist().expect("failed to save new key bindings");
}

回滚

对于某些持久化资源，将其回滚到默认值可能是有意义的。想象一下有一个键绑定设置页面，将其“还原为默认值”按钮放置在此页面上是一个好主意，因为如果玩家弄错了设置，将所有内容还原到默认状态会比手动调整每个键要容易得多。

此类持久化资源需要可回滚创建。

fn setup(mut commands: Commands) {
    let config_dir = dirs::config_dir().unwrap().join("your-amazing-game");
    commands.insert_resource(
        Persistent::<KeyBindings>::builder()
            .name("key bindings")
            .format(StorageFormat::Toml)
            .path(config_dir.join("key-bindings.toml"))
            .default(KeyBindings { jump: KeyCode::Space, crouch: KeyCode::C })
            .revertible(true)
            //^^^^^^^^^^^^^^^ using this
            .build()
            .expect("failed to initialize key bindings")
    )
}

可回滚的持久化资源可以使用 revert_to_default 方法。

fn revert_key_bindings_to_default(key_bindings: Res<Persistent<KeyBindings>>) {
    key_bindings.revert_to_default().expect("failed to revert key bindings to default");
}

还有一个选项可以在反序列化错误时自动回滚到默认值（例如，玩家造成的错误修改）。当启用时，如果持久化对象由于其内容而无法从持久化存储中加载，它将回滚到其默认值。

fn setup(mut commands: Commands) {
    let config_dir = dirs::config_dir().unwrap().join("your-amazing-game");
    commands.insert_resource(
        Persistent::<KeyBindings>::builder()
            .name("key bindings")
            .format(StorageFormat::Toml)
            .path(config_dir.join("key-bindings.toml"))
            .default(KeyBindings { jump: KeyCode::Space, crouch: KeyCode::C })
            .revertible(true)
            //^^^^^^^^^^^^^^^ requires this
            .revert_to_default_on_deserialization_errors(true)
            //^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ enable with this
            .build()
            .expect("failed to initialize key bindings")
    )
}

如果 key-bindings.toml 无法反序列化为 KeyBindings 对象，它将回滚到持久化存储中指定的默认值。

卸载/重新加载

默认情况下，持久化资源被保留在内存中。这可能会导致不必要的内存使用过高。为了克服这一点，您可以使用 unload 方法。

fn unload_key_bindings(key_bindings: Res<Persistent<KeyBindings>>) {
    key_bindings.unload().expect("failed to persist key bindings before unloading");
}

一旦运行此系统，最新版本的底层资源将被写入底层存储，底层资源将从内存中移除。

如果您不想在卸载之前持久化资源的最新版本，或者您知道最新版本已经持久化，可以使用 unload_without_persisting 方法。

fn unload_key_bindings_without_persisting(key_bindings: Res<Persistent<KeyBindings>>) {
    key_bindings.unload_without_persisting();
}

如果不想在创建时立即加载到内存中，持久化资源可以以卸载状态创建。

fn setup(mut commands: Commands) {
    let config_dir = dirs::config_dir().unwrap().join("your-amazing-game");
    commands.insert_resource(
        Persistent::<KeyBindings>::builder()
            .name("key bindings")
            .format(StorageFormat::Toml)
            .path(config_dir.join("key-bindings.toml"))
            .default(KeyBindings { jump: KeyCode::Space, crouch: KeyCode::C })
            .loaded(false)
            //^^^^^^^^^^^^ using this or ".unloaded(true)"
            .build()
            .expect("failed to initialize key bindings")
    )
}

当持久资源卸载时，直到使用reload方法将其重新加载到内存中，底层资源将无法访问。

fn reload_key_bindings(key_bindings: Res<Persistent<KeyBindings>>) {
    key_bindings.reload().expect("failed to reload key bindings");
}

重新加载还可以用于已加载的持久资源，以同步外部更改。这在某些情况下非常有用，例如保存编辑器。保存编辑器会更新保存文件，调用重新加载会将这些更新带到游戏中，而无需重新启动游戏！

使用未加载的持久资源时请务必小心！

// all of these will panic
fn incorrect_usage_of_unloaded_key_bindings(key_bindings: Res<Persistent<KeyBindings>>) {
    // can't access the fields since it's not in memory
    println!("{}", key_bindings.crouch);
    key_bindings.crouch = KeyCode::ControlLeft;

    // can't get the underlying resource since it's not in memory
    key_bindings.get();
    key_bindings.get_mut();

    // can't update, persist, or unload the underlying resource since it's not in memory
    key_bindings.update(...);
    key_bindings.persist();
    key_bindings.unload(); // this will call persist before unloading so it'll panic as well
}

// none of these will panic
fn correct_usage_of_unloaded_key_bindings(key_bindings: Res<Persistent<KeyBindings>>) {
    // can get properties of the persistent resource
    key_bindings.name();
    key_bindings.format();
    key_bindings.storage();
    key_bindings.is_loaded();
    key_bindings.is_unloaded();

    // can try to get the underlying resource
    key_bindings.try_get();
    key_bindings.try_get_mut();

    // can set the resource to a new value
    key_bindings.set(...);

    // can unload without persisting as it's a no-op
    key_bindings.unload_without_persisting(...);

    // can reload the persistent resource
    key_bindings.reload(...);

    // can revert the persistent resource to its default
    key_bindings.revert_to_default(...);
    key_bindings.revert_to_default_in_memory(...);
}

美化

在开发过程中，将一些资源以美化格式存储是一个好主意，以便轻松观察/修改它们。

您可以使用pretty功能来启用美化文本格式

[features]
debug = ["bevy-persistent/pretty"]

在你的游戏中

fn setup(mut commands: Commands) {
    let config_dir = dirs::config_dir().unwrap().join("your-amazing-game");
    commands.insert_resource(
        Persistent::<KeyBindings>::builder()
            .name("key bindings")
            .format({
                #[cfg(feature = "debug")]
                {
                    StorageFormat::JsonPretty
                }
                #[cfg(not(feature = "debug"))]
                {
                    StorageFormat::Json
                }
            })
            .path(config_dir.join("key-bindings.toml"))
            .default(KeyBindings { jump: KeyCode::Space, crouch: KeyCode::C })
            .build()
            .expect("failed to initialize key bindings")
    )
}

然后你可以使用以下方式开发你的游戏

cargo run --features debug

要发布你的游戏，你可以使用以下方式编译

cargo build --release

WebAssembly

...是支持的！

在构建持久资源时，您需要指定一个路径。通常，此路径用于指定文件系统中的位置，但WebAssembly中没有文件系统。取而代之的是，它有本地存储和会话存储。

更改库的API或为WebAssembly创建单独的API会使库的使用变得复杂。相反，库使用了可以使用路径选择存储的事实。

• /local/settings/key-bindings.toml将使用键settings/key-bindings.toml将持久资源存储在本地存储中
• /session/settings/key-bindings.toml将使用键settings/key-bindings.toml将持久资源存储在会话存储中

起初可能看起来很复杂，但确实使支持原生和WebAssembly应用程序变得非常容易。

use std::path::Path;

fn setup(mut commands: Commands) {
    let config_dir = dirs::config_dir()
        .map(|native_config_dir| native_config_dir.join("your-amazing-game"))
        .unwrap_or(Path::new("local").join("configuration"));

    commands.insert_resource(
        Persistent::<KeyBindings>::builder()
            .name("key bindings")
            .format(StorageFormat::Json)
            .path(config_dir.join("key-bindings.toml"))
            .default(KeyBindings { jump: KeyCode::Space, crouch: KeyCode::C })
            .build()
            .expect("failed to initialize key bindings")
    )
}

使用上面的代码，您不需要进行任何条件编译来支持原生和WebAssembly应用程序。

• 在原生应用程序中，它将确定平台的配置目录（例如，~/.config），并将您的游戏名称添加到其中（例如，~/.config/your-amazing-game），并将其用作文件系统的基目录。
• 在WebAssembly应用程序中，它将使用以configuration为基键的本地存储，一旦您将其与key-binding.toml连接起来，资源将使用键configuration/key-bindings.toml进行存储。

如果指定路径的第一个元素不是"local"或"session"，则库将引发恐慌！

如果您不喜欢这种方法，并希望对类型进行严格限制，则可以使用Persistent<R>的new方法。

fn setup(mut commands: Commands) {
    use bevy_persistent::Storage;

    let name = "key bindings";
    let format = StorageFormat::Toml;
    let storage = Storage::LocalStorage { key: "key bindings".to_owned() };
    let loaded = true;
    let default = KeyBindings { jump: KeyCode::Space, crouch: KeyCode::C };
    let revertible = false;
    let revert_to_default_on_deserialization_errors = false;

    commands.insert_resource(
        Persistent::new(
            name,
            format,
            storage,
            loaded,
            default,
            revertible,
            revert_to_default_on_deserialization_errors,
        )
        .expect("failed to initialize key bindings"),
    );
}

示例

您可以在examples文件夹中直接运行并使用这些示例。

cargo run --release --features all --example name-of-the-example

要使用WebAssembly在浏览器中运行示例，您可以使用wasm-server-runner。

cargo run --release --features all --target wasm32-unknown-unknown --example name-of-the-example

在顶部创建插件

如果您想创建使用持久资源的插件，您可以使用library功能来避免指定存储格式。

[package]
name = "bevy-amazing-library"
version = "0.1.0"
edition = "2021"

[dependencies]
bevy-persistent = { version = "0.3" }

[dev-dependencies]
bevy-persistent = { version = "0.3", features = ["all"] }

[features]
default = []
library = ["bevy-persistent/library"]

您可以在启用 library 功能的情况下开发您的库（例如，使用以下命令：cargo build --features library），此时 bevy-persistent 不会在构建您的库时发出警告，但应用程序仍然会报错。

与以下内容相关

bevy_pkv

bevy_pkv 是为 Bevy 提供的通用键值存储库。这是一个非常优秀的库，可以作为 bevy-persistent 的替代品。以下是这两个库之间的一些区别！

• bevy_pkv 更加灵活

假设您想要为两个不同的用户设置两种不同的 Settings。

目前，使用 bevy-persistent 来实现这一点并不直接，因为 Persistent<R> 是一种资源，只能有一个资源的实例。因此，您不能在同一个应用程序中拥有两个 Persistent<Settings>。您可以通过定义一个自定义结构体（例如，Persistent<AllSettings>）、使用元组（例如，Persistent<(Settings, Settings)>）、使用向量（例如，Persistent<Vec<Settings>>）或使用哈希表（例如，Persistent<HashMap<Settings>>）来解决这个问题。

fn setup(mut pkv: ResMut<PkvStore>) {
    // ...
    let blue_settings: Settings = ...;
    let red_settings: Settings = ...;
    // ...
    pkv.set("blue-settings", &blue_settings).unwrap();
    pkv.set("red-settings", &red_settings).unwrap();
    // ...
}

fn utilize_settings(pkv: Res<PkvStore>) {
    // ...
    let blue_settings: Settings = pkv.get("blue-settings").unwrap();
    let red_settings: Settings = pkv.get("red-settings").unwrap();
    // ...
}

fn setup(mut settings: ResMut<PersistentMap<&'static str, Settings>>) {
    // ...
    let blue_settings: Settings = ...;
    let red_settings: Settings = ...;
    // ...
    settings.insert("blue", blue_settings)?;
    settings.insert("red", red_settings)?;
    // ...
}

fn utilize_settings(settings: Res<PersistentMap<&'static str, Settings>>) {
    // ...
    let blue_settings: &Settings = settings["blue"];
    let red_settings: &Settings = settings["red"];
    // ...
}

fn modify_key_bindings(mut pkv: ResMut<PkvStore>) {
    let mut key_bindings = pkv.get::<KeyBindings>("key-bindings");
    key_bindings.crouch = KeyCode::ControlLeft;
    pkv.set("key-bindings", &key_bindings)
}

jump = "Space"
crouch = "C"

jump = "Space"
crouch = "ControlLeft"