用途
本技能用于 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;下游为战斗、技能等游戏玩法技能。