Messages
Send buffered messages between systems with MessageWriter, read them with MessageReader, change them with MessageMutator, and know how long they last.
On this page
A message is a value one system writes and other systems read later. Messages decouple systems: the system that detects a hit doesn't need to know about the systems that play a sound, shake the camera and update the score. Each of those reads the same Hit messages on its own.
Messages are buffered and read at fixed points in the schedule, which makes them efficient for many messages per frame. If you want code to run immediately when something happens, use an event and observer instead.
Define, register, write, read#
use neo::prelude::*;
#[derive(Message)]
struct Hit {
target: Entity,
damage: u32,
}
fn detect_hits(mut hits: MessageWriter<Hit>, targets: Query<Entity, With<Target>>) {
for target in &targets {
hits.write(Hit { target, damage: 10 });
}
}
fn apply_damage(mut hits: MessageReader<Hit>, mut health: Query<&mut Health>) {
for hit in hits.read() {
if let Ok(mut health) = health.get_mut(hit.target) {
health.0 = health.0.saturating_sub(hit.damage);
}
}
}
fn play_hit_sound(mut hits: MessageReader<Hit>) {
for _ in hits.read() {
info!("thud");
}
}
fn main() {
App::new()
.add_plugins(DefaultPlugins)
.add_message::<Hit>()
.add_systems(Update, (detect_hits, (apply_damage, play_hit_sound)).chain())
.run();
}
#[derive(Component)]
struct Target;
#[derive(Component)]
struct Health(u32);Every message type must be registered with app.add_message::<T>() before systems use it. Engine plugins register their own messages, such as AppExit and keyboard input messages.
The parameters#
| Parameter | What it does |
|---|---|
MessageWriter<M> | write(m), write_batch(iter), and write_default() for types with Default. |
MessageReader<M> | read() iterates the messages this system hasn't seen yet. Also len(), is_empty() and clear() (mark all as read). |
PopulatedMessageReader<M> | Like MessageReader, but the system is skipped when there are no new messages. |
MessageMutator<M> | Reads messages as &mut M, so a system can change them before later readers see them. It can also write. |
Each reader keeps its own position, so any number of systems can read the same messages, and each sees each message once. A system can't have a MessageReader<M> and a MessageWriter<M> for the same M; use MessageMutator<M> when one system must do both.
You can also write messages without a writer: commands.write_message(m) from a system, or world.write_message(m) from exclusive code and hooks.
How long messages last#
Messages are double-buffered. Once per frame, at the start of the frame, the older buffer is cleared and the buffers swap. A message therefore stays readable until the end of the frame after the one it was written in.
- A reader that runs every frame never misses a message, whatever the order.
- A reader that runs less often, for example behind a run condition, can miss messages written two or more frames earlier.
- Order the writer before its readers (
.chain(),.before,.after) to handle messages in the same frame; otherwise a reader may see them a frame later.
When FixedUpdate runs, messages are cleared only after a fixed step has run, so systems in FixedUpdate see messages written in Update even on frames where no fixed step ran.
Running only when there are messages#
The on_message run condition skips a system unless there are new messages of a type:
app.add_systems(Update, refresh_scoreboard.run_if(on_message::<Hit>));Messages or events?#
| Messages | Events and observers |
|---|---|
| Read at a fixed point in the schedule. | Observers run immediately, inside the call that triggers the event. |
| Efficient for many per frame, read in batches. | One observer call per event. |
| Readers are ordinary systems in a schedule. | Observers are separate systems that react. |
| Can't target an entity's own handlers. | EntityEvents run observers attached to that entity, and can bubble up a hierarchy. |
A good default: use messages for streams of gameplay data processed every frame (hits, inputs, network packets) and observers for reactions to one-off things (a button was clicked, an entity died).
Examples#
| Example | What it shows |
|---|---|
cargo run --example message | Writers, readers, MessageMutator and ordering, as a damage-over-time effect. |
Run it from the engine core's workspace.