SuperAPI AI 工具集

bevy-genre-sandbox

编程与开发

查看项目

更新于 10-16 10:37

技能介绍

用途

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。