用途
Bevy Sandbox(薄路由)是一个类型(genre)路由器,用于在 Bevy 游戏中处理玩家自建内容的放置、移除与保存。当需要实现「放置、移除并保存玩家构建实体」时加载本技能。领域内的具体工作由下方关联的 Bevy 技能承担,本文件本身只做路由与最小实现。
主要能力与 ECS 结构
- 组件(Components):以纯数据形式保存该类型的逐实体标记。本文件不定义新的引擎类型。一个已放置的单元格是一个带网格坐标与种类 id 的组件。
- 资源(Resources):保存全局计数器(分数、波次索引、随机种子),通过 bevy-data-resources 实现。
- 系统(Systems):在
Update或来自 bevy-master 的固定时间步上读取这些组件。当后一个系统必须看到前一个结果时,用.chain()排序。 - 调度(Schedule):游戏模式切换通过 bevy-state-machines。本文件只注册放置、编辑与构建快照。
使用方式
依赖配置:
[dependencies]
bevy = "0.20"
serde = { version = "1", features = ["derive"] }
放置(Place)
定义一个携带网格坐标与种类 id 的 PlacedCell 组件,并在检测到按键时生成实体:
#[derive(Component, Clone, Copy)]
struct PlacedCell {
x: i32,
y: i32,
z: i32,
kind: u16,
}
fn place_cell(keys: Res<ButtonInput<KeyCode>>, mut commands: Commands) {
if keys.just_pressed(KeyCode::KeyP) {
commands.spawn((
PlacedCell {
x: 0,
y: 0,
z: 0,
kind: 1,
},
Transform::from_xyz(0.0, 0.0, 0.0),
));
}
}
pub struct PlacePlugin;
impl Plugin for PlacePlugin {
fn build(&self, app: &mut App) {
app.add_systems(Update, place_cell);
}
}
编辑(Edit):重绘与移除
#[derive(Component, Clone, Copy)]
struct PlacedCell {
x: i32,
y: i32,
z: i32,
kind: u16,
}
fn remove_empty(mut commands: Commands, cells: Query<(Entity, &PlacedCell)>) {
for (entity, cell) in &cells {
if cell.kind == 0 {
commands.entity(entity).despawn();
}
}
}
fn paint_neighbor(mut cells: Query<&mut PlacedCell>) {
for mut cell in &mut cells {
if cell.x == 0 && cell.kind == 1 {
cell.kind = 2;
}
}
}
pub struct EditPlugin;
impl Plugin for EditPlugin {
fn build(&self, app: &mut App) {
app.add_systems(Update, (paint_neighbor, remove_empty).chain());
}
}
构建快照(Snapshot,serde 序列化)
use serde::{Deserialize, Serialize};
#[derive(Component)]
struct PlacedCell {
x: i32,
y: i32,
z: i32,
kind: u16,
}
#[derive(Serialize, Deserialize, Clone, Default)]
struct CellRecord {
x: i32,
y: i32,
z: i32,
kind: u16,
}
#[derive(Resource, Default)]
struct BuildSnapshot(Vec<CellRecord>);
fn snapshot(cells: Query<&PlacedCell>, mut saved: ResMut<BuildSnapshot>) {
saved.0 = cells
.iter()
.map(|cell| CellRecord {
x: cell.x,
y: cell.y,
z: cell.z,
kind: cell.kind,
})
.collect();
}
pub struct SnapshotPlugin;
impl Plugin for SnapshotPlugin {
fn build(&self, app: &mut App) {
app.init_resource::<BuildSnapshot>()
.add_systems(Update, snapshot);
}
}
fn main() {
App::new()
.add_plugins(MinimalPlugins)
.add_plugins(SnapshotPlugin)
.run();
}
路由(关联技能)
- bevy-3d-world-building — 道具。
- bevy-inventory-system — 建造部件。
- bevy-save-load — 世界持久化。
- bevy-input-handling — 放置。
适用场景与范围
当玩家自建实体的放置、移除与保存需要接入沙盒式玩法时使用。已放置的单元格是一个带网格坐标和种类 id 的组件;道具、物品栏与文件持久化保留在上述关联技能中。示例场景:按下按键放置一个单元格(由本技能生成带 kind id 的 PlacedCell,道具网格由 bevy-3d-world-building 负责);x=0 处的 kind 1 变为 kind 2,然后 kind 0 被移除(通过 .chain() 先重绘再移除,文件 IO 交给 bevy-save-load);构建需要往返序列化(由本技能的 BuildSnapshot 保存 serde 记录,保存插件在 bevy-save-load)。
专家知识要点(目标 Bevy 0.20+)
核心 ECS 类型包括 Component、Resource、Query、Commands、Startup、Update、Fixed / FixedMain(bevy::time)、.chain()、Plugin、DefaultPlugins、MinimalPlugins。消息与观察者属于归属槽位,其 API 见 bevy-events-messaging。除非用 .chain() 对冲突系统排序,否则系统并行运行。
状态归属:单个实体上的数据由 Component 拥有,一个系统通过 Query 修改,运行在 Update 或 FixedMain;整个应用的一个值由 Resource 拥有,一个系统修改,Startup 插入然后在读取它的调度中运行;生成由 Commands 拥有,由生成系统调用,初始世界在 Startup,运行时生成在后续调度;不得竞态的顺序由 .chain() 拥有,仅链式系统适用;插件边界由 Plugin 拥有,build 注册系统与资源,在应用运行前。借用规则:两个都可变查询同一组件的系统必须排序(.chain())或拆分,使只有一个写入;无关系统保持并行。
限制与禁止事项
- 不要在文档 URL 中固定
/0.20.0/;链接保持latest,0.20 目标仅在正文声明一次。 - 不要从两个无序系统可变查询同一组件;除非
.chain()排序,调度会并行运行系统。 - 不要在此发明物理、导航、网络或 XR crate;本技能只命名有文档的 Bevy crate 与模块。
- 不要在同一对无序系统中重绘单元格又销毁它;两者都触及
PlacedCell数据,因此重绘须先于移除,通过.chain()实现。 - 不要发明类型 API;Bevy 代码保持惯用 ECS,只使用有文档的 Bevy API。
- 不要在此选择物理或网络 crate。
库固定版本为 0.20.0,官方页面保持在无版本站点上。官方文档参考包括 Assets、Examples(latest 分支)、ECS、Plugins。相关技能:前置 bevy-master、bevy-ecs-composition;补充 bevy-3d-world-building、bevy-inventory-system、bevy-save-load、bevy-input-handling;下游/消费者:无,本路由不拥有第二份实现;主路由 bevy-master。