SuperAPI AI 工具集

bevy-events-messaging

编程与开发

查看项目

更新于 10-16 10:38

技能介绍

用途

本技能用于 Bevy ECS 中的事件与消息传递。当某个系统需要“注意到某事发生了”,而又不想把这个事实存储到每个实体上时,就加载本技能。它要求在消息(Message)与观察者(Observer)之间做出选择,并明确禁止自行发明第三种通道。

主要能力

技能覆盖两类机制:

  • 消息(拉取式)。 Message 是用于拉取式处理的缓冲消息。MessageWriter 负责写入,MessageReader 负责读取并跟踪自己已经看过哪些内容,Messages 保存最近两次更新内发生的内容。通过 App::add_message 注册类型。引擎负责更新缓冲区,游戏逻辑系统只负责写入和读取。
  • 事件(推送式)。 派生 Event,添加观察者,然后触发。Commands::trigger 和 World::trigger 会在调用内部立即运行观察者。On<E> 是系统参数。派生事件的 Event::Trigger 默认为 GlobalTrigger。
  • 观察者。 Observer 是一个持有系统的组件。EntityEvent 面向单个实体:事件携带 entity 字段,On::event_target 返回该实体。
  • 状态转换。 StateTransitionEvent<S> 在状态 S 变化时触发,该类型随状态一起定义,详见 bevy-state-machines。

使用方式

依赖声明:

[dependencies]
bevy = "0.20"

消息示例(拉取)。 一次命中是其他系统轮询的事实。注册消息,在攻击系统中写入,并在同一调度中稍后读取。add_message 维护双缓冲队列。

#[derive(Message)]
struct Hit {
    amount: i32,
}

fn install(app: &mut App) {
    app.add_message::<Hit>()
        .add_systems(Update, (deal, apply).chain());
}

fn deal(mut hits: MessageWriter<Hit>) {
    hits.write(Hit { amount: 12 });
}

fn apply(mut hits: MessageReader<Hit>) {
    for hit in hits.read() {
        info!("hit {}", hit.amount);
    }
}

事件示例(推送)。 一次呼喊应立即运行监听者。派生 Event,用 On<Shout> 观察,然后 trigger。观察者在 trigger 内部、系统返回之前运行。

#[derive(Event)]
struct Shout {
    text: String,
}

fn listen(shout: On<Shout>) {
    info!("{}", shout.event().text);
}

fn setup(mut commands: Commands) {
    commands.spawn(Observer::new(listen));
    commands.trigger(Shout {
        text: "round".into(),
    });
}

面向实体的事件示例。 面向实体的事件会指明目标。event_target 就是该实体;观察者仍然立即运行。

#[derive(EntityEvent)]
struct Stagger {
    entity: Entity,
}

fn on_stagger(hit: On<Stagger>) {
    info!("stagger {:?}", hit.event_target());
}

fn strike(mut commands: Commands, fighters: Query<Entity>) {
    for entity in &fighters {
        commands.trigger(Stagger { entity });
    }
}

作用域与约束

  • 在任何 MessageWriter 或 MessageReader 之前,先用 App::add_message 注册消息。
  • 面向实体的触发使用 EntityEvent 和 Commands::trigger,并设置 entity 字段。
  • 在同一调度中用 .chain() 写入并读取消息,使读取者在缓冲区更新前看到写入。

适用场景

适用于 Bevy 0.20+ 项目中需要跨系统通知但不共享状态的场合,例如战斗命中、技能触发、实体受击等游戏循环。技能附带 ECS 所有权与调度决策表,帮助判断何时用 Component、Resource、FixedMain、Commands,何时用消息或观察者。

限制

  • 目标版本为 Bevy 0.20+。
  • 不得在文档 URL 中固定 /0.20.0/,链接保持 latest,版本目标只在正文中说明一次。
  • 不得从两个无序系统可变查询同一组件;调度默认并行运行系统,除非用 .chain() 排序。
  • 不得在本技能中发明物理、导航、网络或 XR crate;只命名官方文档中的 Bevy crate 与模块。
  • 不得发明消息注册或触发方法,不得使用第三方 crate,代码保持符合 ECS 习惯并只使用官方 Bevy API。
  • 官方文档链接:ECS messages(https://bevy.org/learn/quick-start/getting-started/ecs/)、Observer 示例(https://github.com/bevyengine/bevy/blob/latest/examples/ecs/observer_propagation.rs)、示例树(https://github.com/bevyengine/bevy/tree/latest/examples#examples)。
  • 相关技能:前置 bevy-master、bevy-ecs-composition;互补 bevy-state-machines;下游为战斗、技能等游戏玩法技能。