SuperAPI AI 工具集

bevy-save-load

编程与开发

查看项目

更新于 10-16 10:40

技能介绍

用途

bevy-save-load 用于在 Bevy 项目中实现玩家进度持久化。当设计需要保存玩家进度时使用该技能:把应用全局的进度保存为一个带版本号的 Resource,并在存在 SaveRequest 时将其序列化为 RON 写入磁盘。

该技能明确区分了两类内容:关卡内容通过 AssetServer 和场景生成加载,属于此技能的边界之外;场景生成(scene spawn)不等于玩家存档槽位,不应把 bsn! 当作用户存档处理。

主要能力

  • 以版本化的 Resource 作为存档载体,进度结构体使用 serde 和 RON 序列化。
  • 存档文件中保存基础类型与 version 字段;实体 id 和资源句柄不写入文件。
  • 支持旧版本迁移:旧文件可能缺少 version 字段,迁移逻辑在数据被插入前构建出当前结构体。
  • 通过显式请求系统触发写盘,避免在每一帧 Update 中都写文件。
  • 写盘系统仅在 SaveRequest 存在时运行,完成后移除该 Resource。

使用方式

依赖配置(serde 与 ron 位于 Bevy 之外):

[dependencies]
bevy = "0.20"
serde = { version = "1", features = ["derive"] }
ron = "0.10"

进度类型是一个普通 Resource:

use serde::{Deserialize, Serialize};

#[derive(Resource, Clone, Serialize, Deserialize)]
struct Progress {
    version: u32,
    coins: u32,
    level: String,
}

fn fresh_progress() -> Progress {
    Progress {
        version: 2,
        coins: 0,
        level: "town".to_string(),
    }
}

编码与解码是普通函数,由请求系统调用,而不是来自逐帧查询:

use serde::{Deserialize, Serialize};

#[derive(Clone, Serialize, Deserialize)]
struct Progress {
    version: u32,
    coins: u32,
    level: String,
}

fn encode_slot(progress: &Progress) -> String {
    ron::ser::to_string_pretty(progress, ron::ser::PrettyConfig::default())
        .expect("progress encodes")
}

fn decode_slot(text: &str) -> Progress {
    ron::from_str(text).expect("progress decodes")
}

fn round_trip() {
    let saved = Progress {
        version: 2,
        coins: 4,
        level: "town".to_string(),
    };
    let loaded = decode_slot(&encode_slot(&saved));
    assert_eq!(loaded.coins, 4);
}

旧文件迁移:先尝试解析为当前结构体,失败则按旧结构体解析并构建当前结构体。

use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize)]
struct SaveV1 {
    coins: u32,
}

#[derive(Resource, Clone, Serialize, Deserialize)]
struct Progress {
    version: u32,
    coins: u32,
}

fn load_any(text: &str) -> Progress {
    if let Ok(current) = ron::from_str::<Progress>(text) {
        return current;
    }
    let legacy: SaveV1 = ron::from_str(text).expect("legacy slot");
    Progress {
        version: 2,
        coins: legacy.coins,
    }
}

保存系统只在 SaveRequest 存在时运行,然后移除它,由同一个系统同时掌管 Resource 与磁盘写入:

use serde::{Deserialize, Serialize};

#[derive(Resource, Clone, Serialize, Deserialize)]
struct Progress {
    version: u32,
    coins: u32,
}

#[derive(Resource)]
struct SaveRequest {
    path: String,
}

fn write_slot(progress: Res<Progress>, request: Res<SaveRequest>) -> std::io::Result<()> {
    let text = ron::ser::to_string(&*progress).expect("progress encodes");
    std::fs::write(&request.path, text)
}

fn save_when_asked(mut commands: Commands, progress: Res<Progress>, request: Option<Res<SaveRequest>>) {
    let Some(request) = request else {
        return;
    };
    let _ = write_slot(progress, request);
    commands.remove_resource::<SaveRequest>();
}

pub struct SavePlugin;

impl Plugin for SavePlugin {
    fn build(&self, app: &mut App) {
        app.insert_resource(Progress {
            version: 2,
            coins: 0,
        })
        .add_systems(Update, save_when_asked);
    }
}

该持久化什么

需求 Bevy 惯用做法
设计师内容 一个资源 Handle,或你在代码中拥有的 Resource
关卡实例 在 bevy-asset-scenes 上做 Scene 生成
玩家存档槽位 一个带版本号的 Resource,在存在 SaveRequest 时以 RON 写入

适用场景

适用于需要在 Bevy 中保存玩家进度的项目,例如保存金币、关卡等应用全局数据。存档路径、version 字段与 RON 文本都定义在 Progress 和 SaveRequest 上。

限制与边界

  • 原生 std::fs 写入是桌面端存档方案;Web 构建需要不同的存储方案,不应直接假定浏览器上存在该路径。
  • 存档槽中不放引擎配置文件类型,槽位就是编码为 RON 的版本化 Resource。
  • 不使用本文件未列出的 DynamicScene 或场景文件写入器,不使用第三方存档 crate。
  • 不要在文档 URL 中固定 /0.20.0/,链接保持在 latest,0.20 目标在正文中说明一次。
  • 不要从两个无序系统可变查询同一组件,调度默认并行,除非用 .chain() 排序。
  • 不要在本技能中虚构物理、导航、网络或 XR crate。
  • Bevy 版本目标为 0.20+,库版本锁定在 0.20。