alter_sprite/
alter_sprite.rs

1//! Shows how to modify texture assets after spawning.
2
3use bevy::{
4    image::ImageLoaderSettings, input::common_conditions::input_just_pressed, prelude::*,
5    render::render_asset::RenderAssetUsages,
6};
7
8fn main() {
9    App::new()
10        .add_plugins(DefaultPlugins)
11        .add_systems(Startup, (setup, spawn_text))
12        .add_systems(
13            Update,
14            alter_handle.run_if(input_just_pressed(KeyCode::Space)),
15        )
16        .add_systems(
17            Update,
18            alter_asset.run_if(input_just_pressed(KeyCode::Enter)),
19        )
20        .run();
21}
22
23#[derive(Component, Debug)]
24enum Bird {
25    Normal,
26    Logo,
27}
28
29impl Bird {
30    fn get_texture_path(&self) -> String {
31        match self {
32            Bird::Normal => "branding/bevy_bird_dark.png".into(),
33            Bird::Logo => "branding/bevy_logo_dark.png".into(),
34        }
35    }
36
37    fn set_next_variant(&mut self) {
38        *self = match self {
39            Bird::Normal => Bird::Logo,
40            Bird::Logo => Bird::Normal,
41        }
42    }
43}
44
45#[derive(Component, Debug)]
46struct Left;
47
48fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
49    let bird_left = Bird::Normal;
50    let bird_right = Bird::Normal;
51    commands.spawn(Camera2d);
52
53    let texture_left = asset_server.load_with_settings(
54        bird_left.get_texture_path(),
55        // `RenderAssetUsages::all()` is already the default, so the line below could be omitted.
56        // It's helpful to know it exists, however.
57        //
58        // `RenderAssetUsages` tell Bevy whether to keep the data around:
59        //   - for the GPU (`RenderAssetUsages::RENDER_WORLD`),
60        //   - for the CPU (`RenderAssetUsages::MAIN_WORLD`),
61        //   - or both.
62        // `RENDER_WORLD` is necessary to render the image, `MAIN_WORLD` is necessary to inspect
63        // and modify the image (via `ResMut<Assets<Image>>`).
64        //
65        // Since most games will not need to modify textures at runtime, many developers opt to pass
66        // only `RENDER_WORLD`. This is more memory efficient, as we don't need to keep the image in
67        // RAM. For this example however, this would not work, as we need to inspect and modify the
68        // image at runtime.
69        |settings: &mut ImageLoaderSettings| settings.asset_usage = RenderAssetUsages::all(),
70    );
71
72    commands.spawn((
73        Name::new("Bird Left"),
74        // This marker component ensures we can easily find either of the Birds by using With and
75        // Without query filters.
76        Left,
77        Sprite::from_image(texture_left),
78        Transform::from_xyz(-200.0, 0.0, 0.0),
79        bird_left,
80    ));
81
82    commands.spawn((
83        Name::new("Bird Right"),
84        // In contrast to the above, here we rely on the default `RenderAssetUsages` loader setting
85        Sprite::from_image(asset_server.load(bird_right.get_texture_path())),
86        Transform::from_xyz(200.0, 0.0, 0.0),
87        bird_right,
88    ));
89}
90
91fn spawn_text(mut commands: Commands) {
92    commands.spawn((
93        Name::new("Instructions"),
94        Text::new(
95            "Space: swap the right sprite's image handle\n\
96            Return: modify the image Asset of the left sprite, affecting all uses of it",
97        ),
98        Node {
99            position_type: PositionType::Absolute,
100            top: Val::Px(12.),
101            left: Val::Px(12.),
102            ..default()
103        },
104    ));
105}
106
107fn alter_handle(
108    asset_server: Res<AssetServer>,
109    mut right_bird: Query<(&mut Bird, &mut Sprite), Without<Left>>,
110) {
111    // Image handles, like other parts of the ECS, can be queried as mutable and modified at
112    // runtime. We only spawned one bird without the `Left` marker component.
113    let Ok((mut bird, mut sprite)) = right_bird.get_single_mut() else {
114        return;
115    };
116
117    // Switch to a new Bird variant
118    bird.set_next_variant();
119
120    // Modify the handle associated with the Bird on the right side. Note that we will only
121    // have to load the same path from storage media once: repeated attempts will re-use the
122    // asset.
123    sprite.image = asset_server.load(bird.get_texture_path());
124}
125
126fn alter_asset(mut images: ResMut<Assets<Image>>, left_bird: Query<&Sprite, With<Left>>) {
127    // It's convenient to retrieve the asset handle stored with the bird on the left. However,
128    // we could just as easily have retained this in a resource or a dedicated component.
129    let Ok(sprite) = left_bird.get_single() else {
130        return;
131    };
132
133    // Obtain a mutable reference to the Image asset.
134    let Some(image) = images.get_mut(&sprite.image) else {
135        return;
136    };
137
138    for pixel in &mut image.data {
139        // Directly modify the asset data, which will affect all users of this asset. By
140        // contrast, mutating the handle (as we did above) affects only one copy. In this case,
141        // we'll just invert the colors, by way of demonstration. Notice that both uses of the
142        // asset show the change, not just the one on the left.
143        *pixel = 255 - *pixel;
144    }
145}
alter_sprite/alter_sprite.rs

alter_sprite/
alter_sprite.rs
