SuperAPI AI 工具集

bevy-data-resources

编程与开发

查看项目

更新于 10-16 10:38

技能介绍

用途

本技能用于在 Bevy 0.20 中决定一份数据应该存放在哪里:是放在许多实体上,还是整个应用只保留一份。当你在 Query 与 Res/ResMut 之间做选择、使用 insert_resource、处理 Time 与 Timer,或者为整个应用一次性存储 RON 数据或资产句柄时,可以加载本技能。

主要能力

  • 区分 Component 与 Resource:Component 用于跨实体查询的数据(Component、Query),适合许多对象携带同类字段的场景;Resource 是全局唯一数据(Resource),例如经过时间、资产集合和渲染器,通过 Res<T>(读)和 ResMut<T>(写)访问。
  • 插入资源:insert_resource 将资源放到 App 上。示例在 GreetTimer(Timer) 上派生 Resource,并插入 Timer::from_seconds(2.0, TimerMode::Repeating)。
  • 时间处理:Time 由 add_plugins(DefaultPlugins) 插入,time.delta() 是自上次更新以来的经过时间,Timer::tick 和 just_finished 是计时器方法。
  • 调度:示例在 Update 系统中读取 Res<Time> 和 ResMut<GreetTimer>。
  • 资源可以持有通过 AssetServer 加载的资产句柄;句柄是数据,加载器仍留在资产服务器上。

使用方式

数据存放位置对照:单个游戏对象上的数据用 Component;整个应用一份的用 Resource,通过 insert_resource 插入;共享时钟用 DefaultPlugins 提供的 Time,或自定义 Resource;作者编写的文件用 serde 加 ron::from_str 解析进 Resource,或用 AssetServer 得到 Handle<Mesh>。

依赖示例(Cargo.toml):

[package]
name = "data-resources"
version = "0.1.0"
edition = "2021"

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

一个问候计时器资源,在 Update 中由 Time 驱动:

#[derive(Resource)]
struct GreetTimer(Timer);

fn greet(time: Res<Time>, mut timer: ResMut<GreetTimer>) {
    timer.0.tick(time.delta());
    if timer.0.just_finished() {
        let _ready = true;
    }
}

pub struct GreetPlugin;

impl Plugin for GreetPlugin {
    fn build(&self, app: &mut App) {
        app.insert_resource(GreetTimer(Timer::from_seconds(2.0, TimerMode::Repeating)))
            .add_systems(Update, greet);
    }
}

fn main() {
    App::new().add_plugins(DefaultPlugins).add_plugins(GreetPlugin).run();
}

每个实体的速度保持为组件,共享倍率保持为资源:

#[derive(Component)]
struct BaseSpeed(f32);

#[derive(Component)]
struct Speed(f32);

#[derive(Resource)]
struct SpeedScale(f32);

fn scale_speed(scale: Res<SpeedScale>, mut bodies: Query<(&BaseSpeed, &mut Speed)>) {
    for (base, mut speed) in &mut bodies {
        speed.0 = base.0 * scale.0;
    }
}

pub struct SpeedPlugin;

impl Plugin for SpeedPlugin {
    fn build(&self, app: &mut App) {
        app.insert_resource(SpeedScale(1.0))
            .add_systems(Startup, |mut commands: Commands| {
                commands.spawn((BaseSpeed(4.0), Speed(4.0)));
            })
            .add_systems(Update, scale_speed);
    }
}

将场景句柄加载进资源,并将 RON 表解析进另一个资源:

use serde::Deserialize;

#[derive(Resource)]
struct LevelAssets {
    mesh: Handle<Mesh>,
}

#[derive(Deserialize, Resource)]
struct Tuning {
    speed: f32,
}

fn load_level(mut commands: Commands, assets: Res<AssetServer>) {
    commands.insert_resource(LevelAssets {
        mesh: assets.load("models/gate.glb#Mesh0/Primitive0"),
    });
}

fn tuning_from_ron(raw: &str) -> Result<Tuning, ron::error::SpannedError> {
    ron::from_str(raw)
}

适用场景

  • 需要判断某份数据应作为每个实体的组件,还是整个应用唯一的资源。
  • 需要为应用插入全局配置、时钟或资产句柄。
  • 需要从 RON 文件解析调参数据到资源。
  • 需要理解 Time、Timer 与 Update 调度之间的关系。

限制

  • 目标版本为 Bevy 0.20+。
  • 每个实体的数据文件和存档 blob 不在本技能范围内,参见 bevy-save-load。
  • 本技能只命名有文档记录的 Bevy crate 和模块,不涉及物理、导航、网络或 XR crate。
  • 不要从两个无序系统可变查询同一组件;调度会并行运行系统,除非用 .chain() 排序。
  • 不要发明资产或序列化 API,不要使用第三方 crate。
  • 文档 URL 不要固定 /0.20.0/,链接保持在 latest。

参考

官方文档:Resources(Resource、Res、ResMut、insert_resource、Time、Timer、TimerMode)、Quick Start: ECS(Component 与 Query)、Apps(资源作为 World 中全局数据的唯一副本)、Examples(latest 分支示例树)。

相关技能:前置 bevy-master、bevy-ecs-composition;补充 bevy-app-resources;下游包括库存、属性和存档技能。