用途
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。