Struct MessageWriter 

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

Writes Messages of type T.

This system parameter takes exclusive access to the Messages<T> resource, so a system cannot also have a MessageReader parameter of the same type. If you need to both read and write messages of the same type, use MessageMutator.

Usage

MessageWriters are usually declared as a [SystemParam].

#[derive(Message)]
pub struct MyMessage(String); // Custom message type.
fn my_system(mut writer: MessageWriter<MyMessage>) {
    writer.write(MyMessage("My custom payload!".to_string()));
}

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, M> MessageWriter<'w, M>

where M: Message,

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

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

See Messages for details.

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

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.

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

where M: 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.

Trait Implementations

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

where M: Message,

type State = FetchState<M>

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

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

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<'_, M> as SystemParam>::State

Creates a new instance of this param’s State.

fn init_access( state: &<MessageWriter<'_, M> 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<'_, M> 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<'_, M> as SystemParam>::State, system_meta: &SystemMeta, world: DeferredWorld<'_>, )

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

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

Creates a parameter to be passed into a SystemParamFunction.

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

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