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.

Examples found in repository

examples/remote/app_under_test.rs (line 50)

fn on_button_click(_click: On<PointerClick>, mut exit: MessageWriter<AppExit>) {
    info!("Button pressed!");
    exit.write(AppExit::Success);
}

examples/app/custom_loop.rs (line 38)

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

examples/ecs/extraction.rs (line 108)

fn trigger_extraction(mut writer: MessageWriter<ExtractMessage>, keys: Res<ButtonInput<KeyCode>>) {
    if keys.pressed(KeyCode::Space) {
        writer.write(ExtractMessage);
    }
}

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 both reads and writes `DealDamage` messages.
//
// Trying to do this with a `MessageReader` and a `MessageWriter` will fail with conflicts,
// since they both use the same underlying resource.
// Instead, you may use a `MessageMutator`, which allows both reading and writing.
fn apply_extra_damage(mut dmg_messages: MessageMutator<DealDamage>) {
    let mut extra = Vec::new();
    for message in dmg_messages.read() {
        if message.amount >= 10 {
            extra.push(DealDamage {
                amount: message.amount / 10,
            });
        }
    }
    // Note that this system will read messages it wrote itself!
    // These are written after the `read()`, so they will be read the next time it runs.
    for message in extra {
        dmg_messages.write(message);
    }
}

// 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/2d/dynamic_mip_generation.rs (line 316)

fn setup(
    mut commands: Commands,
    mut regenerate_image_message_writer: MessageWriter<RegenerateImage>,
) {
    // Spawn the camera.
    commands.spawn(Camera2d);

    // Spawn the UI widgets at the bottom of the window.
    spawn_ui(&mut commands);

    // Schedule the image to be generated.
    regenerate_image_message_writer.write(RegenerateImage);
}

/// Spawns the UI widgets at the bottom of the window.
fn spawn_ui(commands: &mut Commands) {
    commands.spawn_scene(bsn! {
        @main_ui_node_scene()
        Children [
            // Spawn the "Regenerate Top Mip Level" button.
            @FeathersButton {
                @caption: bsn! { @caption("Regenerate Top Mip Level") }
            }
            RegenerateTopMipLevelButton
            Node {
                justify_content: JustifyContent::Center,
                align_items: AlignItems::Center,
            }
            BackgroundColor(Color::BLACK)
            --
            // Spawn the "Mip Generation" switch that allows the user to toggle
            // mip generation on and off.
            @feathers_option_buttons(
                "Mip Generation",
                &[
                    (
                        EnableMipGeneration::On,
                        "On"
                    ),
                    (
                        EnableMipGeneration::Off,
                        "Off"
                    ),
                ], 0
            )
            --
            // Spawn the "Image Width" control that allows the user to set the
            // width of the image.
            @feathers_option_buttons(
                "Image Width",
                &[
                    (ImageSizeSetting::ImageWidth(ImageSize::Size240), "240"),
                    (ImageSizeSetting::ImageWidth(ImageSize::Size480), "480"),
                    (ImageSizeSetting::ImageWidth(ImageSize::Size640), "640"),
                    (ImageSizeSetting::ImageWidth(ImageSize::Size1080), "1080"),
                    (ImageSizeSetting::ImageWidth(ImageSize::Size1920), "1920"),
                ],
                2
            )
            --
            // Spawn the "Image Height" control that allows the user to set the
            // height of the image.
            @feathers_option_buttons(
                "Image Height",
                &[
                    (ImageSizeSetting::ImageHeight(ImageSize::Size240), "240"),
                    (ImageSizeSetting::ImageHeight(ImageSize::Size480), "480"),
                    (ImageSizeSetting::ImageHeight(ImageSize::Size640), "640"),
                    (ImageSizeSetting::ImageHeight(ImageSize::Size1080), "1080"),
                    (ImageSizeSetting::ImageHeight(ImageSize::Size1920), "1920"),
                ],
                1
            )
        ]
    });
}

impl MipmapSizeIterator {
    /// Creates a [`MipmapSizeIterator`] corresponding to the size of the image
    /// currently being displayed.
    fn new(app_status: &AppStatus) -> MipmapSizeIterator {
        MipmapSizeIterator {
            size: Some(app_status.image_size_u32()),
        }
    }
}

impl Iterator for MipmapSizeIterator {
    type Item = UVec2;

    fn next(&mut self) -> Option<Self::Item> {
        // The size of mipmap level N + 1 is equal to half the size of mipmap
        // level N, rounding down, except that the size can never go below 1
        // pixel on either axis.
        let result = self.size;
        if let Some(size) = self.size {
            self.size = if size == UVec2::splat(1) {
                None
            } else {
                Some((size / 2).max(UVec2::splat(1)))
            };
        }
        result
    }
}

/// Updates the size of the image on the left side of the window each frame.
///
/// Resizing the image every frame effectively cycles through all the image's
/// mipmap levels, demonstrating the difference between the presence of mipmap
/// levels and their absence.
fn animate_image_scale(
    mut animated_images_query: Query<&mut Transform, With<AnimatedImage>>,
    windows_query: Query<&Window, With<PrimaryWindow>>,
    app_status: Res<AppStatus>,
    time: Res<Time>,
) {
    let window_size = windows_query.iter().next().unwrap().size();
    let animated_mesh_size = app_status.animated_mesh_size(window_size);

    for mut animated_image_transform in &mut animated_images_query {
        animated_image_transform.scale =
            animated_mesh_size.extend(1.0) * triangle_wave(time.elapsed_secs(), ANIMATION_PERIOD);
    }
}

/// Evaluates a [triangle wave] with the given wavelength.
///
/// This is used as part of [`animate_image_scale`], to derive the scale from
/// the current elapsed time.
///
/// [triangle wave]: https://en.wikipedia.org/wiki/Triangle_wave#Definition
fn triangle_wave(time: f32, wavelength: f32) -> f32 {
    2.0 * ops::abs(time / wavelength - ops::floor(time / wavelength + 0.5))
}

/// Adds the top mipmap level of the image to [`MipGenerationJobs`].
///
/// Note that this must run in the render world, not the main world, as
/// [`MipGenerationJobs`] is a resource that exists in the former. Consequently,
/// it must use [`Extract`] to access main world resources.
fn extract_mipmap_source_image(
    mipmap_source_image: Extract<Res<MipmapSourceImage>>,
    app_status: Extract<Res<AppStatus>>,
    mut mip_generation_jobs: ResMut<MipGenerationJobs>,
) {
    if app_status.enable_mip_generation == EnableMipGeneration::On {
        mip_generation_jobs.add(MIP_GENERATION_PHASE_ID, mipmap_source_image.id());
    }
}

/// Handles the button activation of the `RegenerateTopMipLevelButton`.
fn handle_regenerate_top_mip_level_activate(
    event: On<Activate>,
    q: Query<(), With<RegenerateTopMipLevelButton>>,
    mut regenerate_image_message_writer: MessageWriter<RegenerateImage>,
) {
    if q.contains(event.entity) {
        // Schedule the image to be regenerated.
        regenerate_image_message_writer.write(RegenerateImage);
    }
}

/// Handles a request from the user to change the enable mip generation setting via the UI.
fn handle_enable_mip_generation_change(
    event: On<ValueChange<Entity>>,
    new_value_query: Query<&RadioButtonOptionValue<EnableMipGeneration>>,
    mut app_status: ResMut<AppStatus>,
) {
    let Ok(RadioButtonOptionValue(enable_mip)) = new_value_query.get(event.value) else {
        return;
    };
    app_status.enable_mip_generation = *enable_mip;

    // Enabling mip generation does not trigger a request to regenerate the image.
}

/// Handles a request from the user to change the image size via the UI.
fn handle_image_size_setting_change(
    event: On<ValueChange<Entity>>,
    new_value_query: Query<&RadioButtonOptionValue<ImageSizeSetting>>,
    mut app_status: ResMut<AppStatus>,
    mut regenerate_image_message_writer: MessageWriter<RegenerateImage>,
) {
    let Ok(RadioButtonOptionValue(size_setting)) = new_value_query.get(event.value) else {
        return;
    };

    match *size_setting {
        ImageSizeSetting::ImageWidth(image_size) => app_status.image_width = image_size,
        ImageSizeSetting::ImageHeight(image_size) => app_status.image_height = image_size,
    }

    // Schedule the image to be regenerated.
    regenerate_image_message_writer.write(RegenerateImage);
}

/// Handles resize events for the window.
///
/// Resizing the window invalidates the image and repositions all image views.
/// (Regenerating the image isn't strictly necessary, but it's simplest to have
/// a single function that both regenerates the image and recreates the image
/// views.)
fn handle_window_resize_events(
    mut events: MessageReader<WindowResized>,
    mut regenerate_image_message_writer: MessageWriter<RegenerateImage>,
) {
    for _ in events.read() {
        regenerate_image_message_writer.write(RegenerateImage);
    }
}

Additional examples can be found in:

• examples/ecs/ecs_guide.rs
• examples/audio/pitch.rs
• examples/ecs/observer_propagation.rs
• examples/showcase/desk_toy.rs
• examples/camera/pan_orbit_camera_cad.rs
• examples/3d/mixed_lighting.rs
• examples/showcase/game_menu.rs
• examples/picking/custom_hit_data.rs
• examples/ui/widgets/feathers_gallery.rs
• examples/input/gamepad_rumble.rs
• examples/ui/render_ui_to_texture.rs
• examples/window/low_power.rs
• examples/camera/pan_orbit_camera_custom_input_plugin.rs
• examples/app/headless_renderer.rs

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.

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<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.

Examples found in repository

examples/ecs/message.rs (line 105)

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

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

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, system_access: &mut SystemAccess, 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.