Struct MessageWriter 

pub struct MessageWriter<'w, E>
where
    E: Message,
{ /* private fields */ }

Writes Messages of type T.

Usage

MessageWriters are usually declared as a SystemParam.

#[derive(Message)]
pub struct MyMessage; // Custom message type.
fn my_system(mut writer: MessageWriter<MyMessage>) {
    writer.write(MyMessage);
}

Concurrency

MessageWriter param has ResMut<Messages<T>> inside. So two systems declaring MessageWriter<T> params for the same message type won’t be executed concurrently.

Untyped messages

MessageWriter can only write messages of one specific type, which must be known at compile-time. This is not a problem most of the time, but you may find a situation where you cannot know ahead of time every kind of message you’ll need to write. In this case, you can use the “type-erased message” pattern.

fn write_untyped(mut commands: Commands) {
    // Write a message of a specific type without having to declare that
    // type as a SystemParam.
    //
    // Effectively, we're just moving the type parameter from the /type/ to the /method/,
    // which allows one to do all kinds of clever things with type erasure, such as sending
    // custom messages to unknown 3rd party plugins (modding API).
    //
    // NOTE: the message won't actually be sent until commands get applied during
    // apply_deferred.
    commands.queue(|w: &mut World| {
        w.write_message(MyMessage);
    });
}

Note that this is considered non-idiomatic, and should only be used when MessageWriter will not work.

Implementations

impl<'w, E> MessageWriter<'w, E>

where E: Message,

pub fn write(&mut self, message: E) -> MessageId<E>

Writes an message, which can later be read by MessageReaders. This method returns the ID of the written message.

See Messages for details.

Examples found in repository

examples/ecs/send_and_receive_messages.rs (line 61)

fn read_and_write_different_message_types(mut a: MessageWriter<A>, mut b: MessageReader<B>) {
    for _ in b.read() {}
    a.write(A);
}

/// A dummy message type.
#[derive(Debug, Clone, Message)]
struct DebugMessage {
    resend_from_param_set: bool,
    resend_from_local_message_reader: bool,
    times_sent: u8,
}

/// A system that sends all combinations of messages.
fn send_messages(mut debug_messages: MessageWriter<DebugMessage>, frame_count: Res<FrameCount>) {
    println!("Sending messages for frame {}", frame_count.0);

    debug_messages.write(DebugMessage {
        resend_from_param_set: false,
        resend_from_local_message_reader: false,
        times_sent: 1,
    });
    debug_messages.write(DebugMessage {
        resend_from_param_set: true,
        resend_from_local_message_reader: false,
        times_sent: 1,
    });
    debug_messages.write(DebugMessage {
        resend_from_param_set: false,
        resend_from_local_message_reader: true,
        times_sent: 1,
    });
    debug_messages.write(DebugMessage {
        resend_from_param_set: true,
        resend_from_local_message_reader: true,
        times_sent: 1,
    });
}

/// A system that prints all messages sent since the last time this system ran.
///
/// Note that some messages will be printed twice, because they were sent twice.
fn debug_messages(mut messages: MessageReader<DebugMessage>) {
    for message in messages.read() {
        println!("{message:?}");
    }
}

/// A system that both sends and receives messages using [`ParamSet`].
fn send_and_receive_param_set(
    mut param_set: ParamSet<(MessageReader<DebugMessage>, MessageWriter<DebugMessage>)>,
    frame_count: Res<FrameCount>,
) {
    println!(
        "Sending and receiving messages for frame {} with a `ParamSet`",
        frame_count.0
    );

    // We must collect the messages to resend, because we can't access the writer while we're iterating over the reader.
    let mut messages_to_resend = Vec::new();

    // This is p0, as the first parameter in the `ParamSet` is the reader.
    for message in param_set.p0().read() {
        if message.resend_from_param_set {
            messages_to_resend.push(message.clone());
        }
    }

    // This is p1, as the second parameter in the `ParamSet` is the writer.
    for mut message in messages_to_resend {
        message.times_sent += 1;
        param_set.p1().write(message);
    }
}

examples/app/custom_loop.rs (line 38)

fn exit_system(input: Res<Input>, mut app_exit_reader: MessageWriter<AppExit>) {
    if input.0 == "exit" {
        app_exit_reader.write(AppExit::Success);
    }
}

examples/async_tasks/external_source_external_thread.rs (line 49)

fn read_stream(receiver: Res<StreamReceiver>, mut events: MessageWriter<StreamMessage>) {
    for from_stream in receiver.try_iter() {
        events.write(StreamMessage(from_stream));
    }
}

examples/ecs/message.rs (line 47)

fn deal_damage_over_time(
    time: Res<Time>,
    mut state: ResMut<DamageTimer>,
    mut deal_damage_writer: MessageWriter<DealDamage>,
) {
    if state.tick(time.delta()).is_finished() {
        // Messages can be sent with 'write' and constructed just like any other object.
        deal_damage_writer.write(DealDamage { amount: 10 });
    }
}

// This system mutates the 'DealDamage' messages to apply some armor value
// It also sends an 'ArmorBlockedDamage' message if the value of 'DealDamage' is zero
//
// Messages are mutated using an 'MessageMutator<T>' by calling 'read'. This returns an iterator
// over all the &mut T that this system has not read yet. Note, you can have multiple
// 'MessageReader', 'MessageWriter', and 'MessageMutator' in a given system, as long as the types (T) are different.
fn apply_armor_to_damage(
    mut dmg_messages: MessageMutator<DealDamage>,
    mut armor_messages: MessageWriter<ArmorBlockedDamage>,
) {
    for message in dmg_messages.read() {
        message.amount -= 1;
        if message.amount <= 0 {
            // Zero-sized messages can also be sent with 'send'
            armor_messages.write(ArmorBlockedDamage);
        }
    }
}

examples/ecs/ecs_guide.rs (line 171)

fn game_over_system(
    game_rules: Res<GameRules>,
    game_state: Res<GameState>,
    mut app_exit_writer: MessageWriter<AppExit>,
) {
    if let Some(ref player) = game_state.winning_player {
        println!("{player} won the game!");
        app_exit_writer.write(AppExit::Success);
    } else if game_state.current_round == game_rules.max_rounds {
        println!("Ran out of rounds. Nobody wins!");
        app_exit_writer.write(AppExit::Success);
    }
}

examples/3d/../helpers/widgets.rs (line 178)

pub fn handle_ui_interactions<T>(
    mut interactions: Query<
        (&Interaction, &WidgetClickSender<T>),
        (With<Button>, With<RadioButton>),
    >,
    mut widget_click_events: MessageWriter<WidgetClickEvent<T>>,
) where
    T: Clone + Send + Sync + 'static,
{
    for (interaction, click_event) in interactions.iter_mut() {
        if *interaction == Interaction::Pressed {
            widget_click_events.write(WidgetClickEvent((**click_event).clone()));
        }
    }
}

Additional examples can be found in:

• examples/audio/pitch.rs
• examples/ecs/observer_propagation.rs
• examples/games/desk_toy.rs
• examples/3d/mixed_lighting.rs
• examples/ui/box_shadow.rs
• examples/games/game_menu.rs
• examples/input/gamepad_rumble.rs
• examples/ui/size_constraints.rs
• examples/window/low_power.rs
• examples/ui/render_ui_to_texture.rs
• examples/app/headless_renderer.rs

pub fn write_batch( &mut self, messages: impl IntoIterator<Item = E>, ) -> WriteBatchIds<E>

Writes a list of messages all at once, which can later be read by MessageReaders. This is more efficient than writing each message individually. This method returns the IDs of the written messages.

See Messages for details.

Examples found in repository

examples/app/log_layers_ecs.rs (line 58)

fn transfer_log_messages(
    receiver: NonSend<CapturedLogMessages>,
    mut message_writer: MessageWriter<LogMessage>,
) {
    // Make sure to use `try_iter()` and not `iter()` to prevent blocking.
    message_writer.write_batch(receiver.try_iter());
}

pub fn write_default(&mut self) -> MessageId<E>

where E: Default,

Writes the default value of the message. Useful when the message is an empty struct. This method returns the ID of the written message.

See Messages for details.

Examples found in repository

examples/ecs/message.rs (line 84)

fn apply_damage_to_health(
    mut deal_damage_reader: MessageReader<DealDamage>,
    mut damaged_received_writer: MessageWriter<DamageReceived>,
) {
    for deal_damage in deal_damage_reader.read() {
        info!("Applying {} damage", deal_damage.amount);
        if deal_damage.amount > 0 {
            // Messages with a 'Default' implementation can be written with 'write_default'
            damaged_received_writer.write_default();
        }
    }
}

Trait Implementations

impl<E> SystemParam for MessageWriter<'_, E>

where E: Message,

type State = FetchState<E>

Used to store data which persists across invocations of a system.

type Item<'w, 's> = MessageWriter<'w, E>

The item type returned when constructing this system param. The value of this associated type should be Self, instantiated with new lifetimes.

fn init_state(world: &mut World) -> <MessageWriter<'_, E> as SystemParam>::State

Creates a new instance of this param’s State.

fn init_access( state: &<MessageWriter<'_, E> as SystemParam>::State, system_meta: &mut SystemMeta, component_access_set: &mut FilteredAccessSet, world: &mut World, )

Registers any World access used by this SystemParam

fn apply( state: &mut <MessageWriter<'_, E> as SystemParam>::State, system_meta: &SystemMeta, world: &mut World, )

Applies any deferred mutations stored in this SystemParam’s state. This is used to apply Commands during ApplyDeferred.

fn queue( state: &mut <MessageWriter<'_, E> as SystemParam>::State, system_meta: &SystemMeta, world: DeferredWorld<'_>, )

Queues any deferred mutations to be applied at the next ApplyDeferred.

unsafe fn validate_param<'w, 's>( state: &'s mut <MessageWriter<'_, E> as SystemParam>::State, _system_meta: &SystemMeta, _world: UnsafeWorldCell<'w>, ) -> Result<(), SystemParamValidationError>

Validates that the param can be acquired by the get_param.

unsafe fn get_param<'w, 's>( state: &'s mut <MessageWriter<'_, E> as SystemParam>::State, system_meta: &SystemMeta, world: UnsafeWorldCell<'w>, change_tick: Tick, ) -> <MessageWriter<'_, E> as SystemParam>::Item<'w, 's>

Creates a parameter to be passed into a SystemParamFunction.

impl<'w, 's, E> ReadOnlySystemParam for MessageWriter<'w, E>

where E: Message, ResMut<'w, Messages<E>>: ReadOnlySystemParam,