diff --git a/Cargo.toml b/Cargo.toml index 0c6411301c9b5..7186adb940a7e 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1354,6 +1354,28 @@ category = "Application" wasm = false # Assets +[[example]] +name = "alter_mesh" +path = "examples/asset/alter_mesh.rs" +doc-scrape-examples = true + +[package.metadata.example.alter_mesh] +name = "Alter Mesh" +description = "Shows how to modify the underlying asset of a Mesh after spawning." +category = "Assets" +wasm = false + +[[example]] +name = "alter_sprite" +path = "examples/asset/alter_sprite.rs" +doc-scrape-examples = true + +[package.metadata.example.alter_sprite] +name = "Alter Sprite" +description = "Shows how to modify texture assets after spawning." +category = "Assets" +wasm = false + [[example]] name = "asset_loading" path = "examples/asset/asset_loading.rs" diff --git a/examples/README.md b/examples/README.md index cd8c7edcccd22..fb03438de3c9e 100644 --- a/examples/README.md +++ b/examples/README.md @@ -219,6 +219,8 @@ Example | Description Example | Description --- | --- +[Alter Mesh](../examples/asset/alter_mesh.rs) | Shows how to modify the underlying asset of a Mesh after spawning. +[Alter Sprite](../examples/asset/alter_sprite.rs) | Shows how to modify texture assets after spawning. [Asset Decompression](../examples/asset/asset_decompression.rs) | Demonstrates loading a compressed asset [Asset Loading](../examples/asset/asset_loading.rs) | Demonstrates various methods to load assets [Asset Processing](../examples/asset/processing/asset_processing.rs) | Demonstrates how to process and load custom assets diff --git a/examples/asset/alter_mesh.rs b/examples/asset/alter_mesh.rs new file mode 100644 index 0000000000000..5bd3053af3b8c --- /dev/null +++ b/examples/asset/alter_mesh.rs @@ -0,0 +1,237 @@ +//! Shows how to modify mesh assets after spawning. + +use bevy::{ + gltf::GltfLoaderSettings, input::common_conditions::input_just_pressed, prelude::*, + render::mesh::VertexAttributeValues, render::render_asset::RenderAssetUsages, +}; + +fn main() { + App::new() + .add_plugins(DefaultPlugins) + .add_systems(Startup, (setup, spawn_text)) + .add_systems( + Update, + alter_handle.run_if(input_just_pressed(KeyCode::Space)), + ) + .add_systems( + Update, + alter_mesh.run_if(input_just_pressed(KeyCode::Enter)), + ) + .run(); +} + +#[derive(Component, Debug)] +enum Shape { + Cube, + Sphere, +} + +impl Shape { + fn get_model_path(&self) -> String { + match self { + Shape::Cube => "models/cube/cube.gltf".into(), + Shape::Sphere => "models/sphere/sphere.gltf".into(), + } + } + + fn set_next_variant(&mut self) { + *self = match self { + Shape::Cube => Shape::Sphere, + Shape::Sphere => Shape::Cube, + } + } +} + +#[derive(Component, Debug)] +struct Left; + +fn setup( + mut commands: Commands, + asset_server: Res, + mut materials: ResMut>, +) { + let left_shape = Shape::Cube; + let right_shape = Shape::Cube; + + // In normal use, you can call `asset_server.load`, however see below for an explanation of + // `RenderAssetUsages`. + let left_shape_model = asset_server.load_with_settings( + GltfAssetLabel::Primitive { + mesh: 0, + // This field stores an index to this primitive in its parent mesh. In this case, we + // want the first one. You might also have seen the syntax: + // + // models/cube/cube.gltf#Scene0 + // + // which accomplishes the same thing. + primitive: 0, + } + .from_asset(left_shape.get_model_path()), + // `RenderAssetUsages::all()` is already the default, so the line below could be omitted. + // It's helpful to know it exists, however. + // + // `RenderAssetUsages` tell Bevy whether to keep the data around: + // - for the GPU (`RenderAssetUsages::RENDER_WORLD`), + // - for the CPU (`RenderAssetUsages::MAIN_WORLD`), + // - or both. + // `RENDER_WORLD` is necessary to render the mesh, `MAIN_WORLD` is necessary to inspect + // and modify the mesh (via `ResMut>`). + // + // Since most games will not need to modify meshes at runtime, many developers opt to pass + // only `RENDER_WORLD`. This is more memory efficient, as we don't need to keep the mesh in + // RAM. For this example however, this would not work, as we need to inspect and modify the + // mesh at runtime. + |settings: &mut GltfLoaderSettings| settings.load_meshes = RenderAssetUsages::all(), + ); + + // Here, we rely on the default loader settings to achieve a similar result to the above. + let right_shape_model = asset_server.load( + GltfAssetLabel::Primitive { + mesh: 0, + primitive: 0, + } + .from_asset(right_shape.get_model_path()), + ); + + // Add a material asset directly to the materials storage + let material_handle = materials.add(StandardMaterial { + base_color: Color::srgb(0.6, 0.8, 0.6), + ..default() + }); + + commands.spawn(( + Left, + Name::new("Left Shape"), + PbrBundle { + mesh: left_shape_model, + material: material_handle.clone(), + transform: Transform::from_xyz(-3.0, 0.0, 0.0), + ..default() + }, + left_shape, + )); + + commands.spawn(( + Name::new("Right Shape"), + PbrBundle { + mesh: right_shape_model, + material: material_handle, + transform: Transform::from_xyz(3.0, 0.0, 0.0), + ..default() + }, + right_shape, + )); + + commands.spawn(( + Name::new("Point Light"), + PointLightBundle { + transform: Transform::from_xyz(4.0, 5.0, 4.0), + ..default() + }, + )); + + commands.spawn(( + Name::new("Camera"), + Camera3dBundle { + transform: Transform::from_xyz(0.0, 3.0, 20.0).looking_at(Vec3::ZERO, Vec3::Y), + ..default() + }, + )); +} + +fn spawn_text(mut commands: Commands) { + commands + .spawn(( + Name::new("Instructions"), + NodeBundle { + style: Style { + align_items: AlignItems::Start, + flex_direction: FlexDirection::Column, + justify_content: JustifyContent::Start, + width: Val::Percent(100.), + ..default() + }, + ..default() + }, + )) + .with_children(|parent| { + parent.spawn(TextBundle::from_section( + "Space: swap meshes by mutating a Handle", + TextStyle::default(), + )); + parent.spawn(TextBundle::from_section( + "Return: mutate the mesh itself, changing all copies of it", + TextStyle::default(), + )); + }); +} + +fn alter_handle( + asset_server: Res, + mut right_shape: Query<(&mut Handle, &mut Shape), Without>, +) { + // Mesh handles, like other parts of the ECS, can be queried as mutable and modified at + // runtime. We only spawned one shape without the `Left` marker component. + let Ok((mut handle, mut shape)) = right_shape.get_single_mut() else { + return; + }; + + // Switch to a new Shape variant + shape.set_next_variant(); + + // Modify the handle associated with the Shape on the right side. Note that we will only + // have to load the same path from storage media once: repeated attempts will re-use the + // asset. + *handle = asset_server.load( + GltfAssetLabel::Primitive { + mesh: 0, + primitive: 0, + } + .from_asset(shape.get_model_path()), + ); +} + +fn alter_mesh( + mut is_mesh_scaled: Local, + left_shape: Query<&Handle, With>, + mut meshes: ResMut>, +) { + // It's convenient to retrieve the asset handle stored with the shape on the left. However, + // we could just as easily have retained this in a resource or a dedicated component. + let Ok(handle) = left_shape.get_single() else { + return; + }; + + // Obtain a mutable reference to the Mesh asset. + let Some(mesh) = meshes.get_mut(handle) else { + return; + }; + + // Now we can directly manipulate vertices on the mesh. Here, we're just scaling in and out + // for demonstration purposes. This will affect all entities currently using the asset. + // + // To do this, we need to grab the stored attributes of each vertex. `Float32x3` just describes + // the format in which the attributes will be read: each position consists of an array of three + // f32 corresponding to x, y, and z. + // + // `ATTRIBUTE_POSITION` is a constant indicating that we want to know where the vertex is + // located in space (as opposed to which way its normal is facing, vertex color, or other + // details). + if let Some(VertexAttributeValues::Float32x3(positions)) = + mesh.attribute_mut(Mesh::ATTRIBUTE_POSITION) + { + // Check a Local value (which only this system can make use of) to determine if we're + // currently scaled up or not. + let scale_factor = if *is_mesh_scaled { 0.5 } else { 2.0 }; + + for position in positions.iter_mut() { + // Apply the scale factor to each of x, y, and z. + position[0] *= scale_factor; + position[1] *= scale_factor; + position[2] *= scale_factor; + } + + // Flip the local value to reverse the behaviour next time the key is pressed. + *is_mesh_scaled = !*is_mesh_scaled; + } +} diff --git a/examples/asset/alter_sprite.rs b/examples/asset/alter_sprite.rs new file mode 100644 index 0000000000000..7725ad36eb8f2 --- /dev/null +++ b/examples/asset/alter_sprite.rs @@ -0,0 +1,164 @@ +//! Shows how to modify texture assets after spawning. + +use bevy::{ + input::common_conditions::input_just_pressed, + prelude::*, + render::{render_asset::RenderAssetUsages, texture::ImageLoaderSettings}, +}; + +fn main() { + App::new() + .add_plugins(DefaultPlugins) + .add_systems(Startup, (setup, spawn_text)) + .add_systems( + Update, + alter_handle.run_if(input_just_pressed(KeyCode::Space)), + ) + .add_systems( + Update, + alter_asset.run_if(input_just_pressed(KeyCode::Enter)), + ) + .run(); +} + +#[derive(Component, Debug)] +enum Bird { + Normal, + Logo, +} + +impl Bird { + fn get_texture_path(&self) -> String { + match self { + Bird::Normal => "branding/bevy_bird_dark.png".into(), + Bird::Logo => "branding/bevy_logo_dark.png".into(), + } + } + + fn set_next_variant(&mut self) { + *self = match self { + Bird::Normal => Bird::Logo, + Bird::Logo => Bird::Normal, + } + } +} + +#[derive(Component, Debug)] +struct Left; + +fn setup(mut commands: Commands, asset_server: Res) { + let bird_left = Bird::Normal; + let bird_right = Bird::Normal; + commands.spawn(Camera2dBundle::default()); + + let texture_left = asset_server.load_with_settings( + bird_left.get_texture_path(), + // `RenderAssetUsages::all()` is already the default, so the line below could be omitted. + // It's helpful to know it exists, however. + // + // `RenderAssetUsages` tell Bevy whether to keep the data around: + // - for the GPU (`RenderAssetUsages::RENDER_WORLD`), + // - for the CPU (`RenderAssetUsages::MAIN_WORLD`), + // - or both. + // `RENDER_WORLD` is necessary to render the image, `MAIN_WORLD` is necessary to inspect + // and modify the image (via `ResMut>`). + // + // Since most games will not need to modify textures at runtime, many developers opt to pass + // only `RENDER_WORLD`. This is more memory efficient, as we don't need to keep the image in + // RAM. For this example however, this would not work, as we need to inspect and modify the + // image at runtime. + |settings: &mut ImageLoaderSettings| settings.asset_usage = RenderAssetUsages::all(), + ); + + commands.spawn(( + Name::new("Bird Left"), + // This marker component ensures we can easily find either of the Birds by using With and + // Without query filters. + Left, + SpriteBundle { + texture: texture_left, + transform: Transform::from_xyz(-200.0, 0.0, 0.0), + ..default() + }, + bird_left, + )); + + commands.spawn(( + Name::new("Bird Right"), + SpriteBundle { + // In contrast to the above, here we rely on the default `RenderAssetUsages` loader + // setting. + texture: asset_server.load(bird_right.get_texture_path()), + transform: Transform::from_xyz(200.0, 0.0, 0.0), + ..default() + }, + bird_right, + )); +} + +fn spawn_text(mut commands: Commands) { + commands + .spawn(( + Name::new("Instructions"), + NodeBundle { + style: Style { + align_items: AlignItems::Start, + flex_direction: FlexDirection::Column, + justify_content: JustifyContent::Start, + width: Val::Percent(100.), + ..default() + }, + ..default() + }, + )) + .with_children(|parent| { + parent.spawn(TextBundle::from_section( + "Space: swap image texture paths by mutating a Handle", + TextStyle::default(), + )); + parent.spawn(TextBundle::from_section( + "Return: mutate the image Asset itself, changing all copies of it", + TextStyle::default(), + )); + }); +} + +fn alter_handle( + asset_server: Res, + mut right_bird: Query<(&mut Bird, &mut Handle), Without>, +) { + // Image handles, like other parts of the ECS, can be queried as mutable and modified at + // runtime. We only spawned one bird without the `Left` marker component. + let Ok((mut bird, mut handle)) = right_bird.get_single_mut() else { + return; + }; + + // Switch to a new Bird variant + bird.set_next_variant(); + + // Modify the handle associated with the Bird on the right side. Note that we will only + // have to load the same path from storage media once: repeated attempts will re-use the + // asset. + *handle = asset_server.load(bird.get_texture_path()); +} + +fn alter_asset(mut images: ResMut>, left_bird: Query<&Handle, With>) { + // It's convenient to retrieve the asset handle stored with the bird on the left. However, + // we could just as easily have retained this in a resource or a dedicated component. + let Ok(handle) = left_bird.get_single() else { + return; + }; + + // Obtain a mutable reference to the Image asset. + let Some(image) = images.get_mut(handle) else { + return; + }; + + for pixel in &mut image.data { + // Directly modify the asset data, which will affect all users of this asset. By + // contrast, mutating the handle (as we did above) affects only one copy. In this case, + // we'll just invert the colors, by way of demonstration. Notice that both uses of the + // asset show the change, not just the one on the left. + *pixel = 255 - *pixel; + } +}