Merge car meshes in bevy_city and improve loading screen (#23574)

# Objective

- In the asset pack used for bevy_city the tires of all the cars are
separate meshes from the car body. In some of the cars even the doors
are also separate meshes.
- Since we don't animate these elements of the car we can trivially
combine all the meshes of each car scene into one single car mesh. This
helps a lot to keep performance manageable and eventually increase the
scale of bevy_city.

## Solution

- Wait for the assets to load and once they are loaded loop over all the
car scenes and combine their meshes. This is mainly possible because the
entire asset pack uses a single texture so we don't need a separate
material for each part of the mesh.
- To do this I also refactored a bit how each step happens when starting
the app. I also made sure that each step is reflected on the loading
screen.
- I also added a bit more docs

## Testing

- I ran bevy_city and confirmed that the tires are where they should be
relative to the mesh and that performance was better. I went from 90fps
to 112fps on my machine

---

## Showcase


https://github.com/user-attachments/assets/c2a10681-d148-4394-a3ca-fffe928fa09c

Author: IceSentry

examples/large_scenes/bevy_city/src/assets.rs

@@ -1,4 +1,4 @@
-use bevy::prelude::*;
+use bevy::{ecs::system::SystemState, prelude::*};
 use rand::RngExt;
 
 const BASE_URL: &str = "https://github.com/bevyengine/bevy_asset_files/raw/main/kenney";
@@ -13,6 +13,8 @@ pub fn strip_base_url(path: String) -> String {
 pub struct CityAssets {
     pub untyped_assets: Vec<UntypedHandle>,
     pub cars: Vec<Handle<WorldAsset>>,
+    pub car_meshes: Vec<Handle<Mesh>>,
+    pub car_material: Handle<StandardMaterial>,
     pub crossroad: Handle<WorldAsset>,
     pub road_straight: Handle<WorldAsset>,
     pub high_density: Buildings,
@@ -30,8 +32,12 @@ pub struct CityAssets {
 }
 
 impl CityAssets {
-    pub fn get_random_car<R: RngExt>(&self, rng: &mut R) -> Handle<WorldAsset> {
-        self.cars[rng.random_range(0..self.cars.len())].clone()
+    pub fn get_random_car<R: RngExt>(
+        &self,
+        rng: &mut R,
+    ) -> (Mesh3d, MeshMaterial3d<StandardMaterial>) {
+        let mesh = self.car_meshes[rng.random_range(0..self.car_meshes.len())].clone();
+        (Mesh3d(mesh), MeshMaterial3d(self.car_material.clone()))
     }
 }
 
@@ -68,6 +74,13 @@ pub fn load_assets(
         }};
     }
 
+    let car_texture: Handle<Image> =
+        load_asset!(format!("{base_url}/car-kit/Textures/colormap.png"));
+    let car_material = materials.add(StandardMaterial {
+        base_color_texture: Some(car_texture),
+        ..Default::default()
+    });
+
     let cars = {
         // TODO generate color variations
         [
@@ -222,6 +235,8 @@ pub fn load_assets(
     commands.insert_resource(CityAssets {
         untyped_assets,
         cars,
+        car_meshes: vec![],
+        car_material,
         crossroad,
         road_straight,
         high_density,
@@ -234,3 +249,57 @@ pub fn load_assets(
         fence,
     });
 }
+
+/// Merge the meshes of all the cars gltf into a single mesh per car.
+///
+/// The asset pack we are using uses a separate mesh for each tire of the car and some also have
+/// doors as separate meshes. This is useful if you want to animate these element individually but
+/// in this scene we don't need to do that. Having multiple meshes for a single car means we need
+/// to run transform propagation on all these meshes and it will also generate even more indirect
+/// commands for each of those meshes.
+pub fn merge_car_meshes(
+    city_assets: &mut CityAssets,
+    world_assets: &mut Assets<WorldAsset>,
+    meshes: &mut Assets<Mesh>,
+) {
+    for car_scene in &city_assets.cars {
+        let Some(merged) = merge_world_asset(world_assets, meshes, car_scene) else {
+            continue;
+        };
+        city_assets.car_meshes.push(meshes.add(merged));
+    }
+}
+
+/// Merge an entire scene into a single mesh
+fn merge_world_asset(
+    world_assets: &mut Assets<WorldAsset>,
+    meshes: &mut Assets<Mesh>,
+    scene_handle: &Handle<WorldAsset>,
+) -> Option<Mesh> {
+    let mut scene = world_assets.get_mut(scene_handle)?;
+    let mut merged: Option<Mesh> = None;
+
+    let mut system_state = SystemState::<TransformHelper>::new(&mut scene.world);
+    let helper = system_state.get(&scene.world).ok()?;
+
+    for entity_ref in scene.world.iter_entities() {
+        let Some(mesh) = entity_ref
+            .get::<Mesh3d>()
+            .and_then(|mesh3d| meshes.get(mesh3d))
+        else {
+            continue;
+        };
+        let Ok(global_transform) = helper.compute_global_transform(entity_ref.id()) else {
+            continue;
+        };
+        let transform = global_transform.compute_transform();
+        let transformed = mesh.clone().transformed_by(transform);
+        match &mut merged {
+            Some(mesh) => {
+                let _ = mesh.merge(&transformed);
+            }
+            None => merged = Some(transformed),
+        }
+    }
+    merged
+}

examples/large_scenes/bevy_city/src/generate_city.rs

@@ -122,7 +122,7 @@ fn spawn_roads_and_cars<R: RngExt>(
 
                 if rng.random::<f32>() < max_car_density {
                     commands.spawn((
-                        WorldAssetRoot(assets.get_random_car(rng)),
+                        assets.get_random_car(rng),
                         Transform::from_translation(car_pos + Vec3::new(0.0, 0.0, -0.15))
                             .with_scale(Vec3::splat(0.15))
                             .with_rotation(Quat::from_axis_angle(
@@ -139,7 +139,7 @@ fn spawn_roads_and_cars<R: RngExt>(
 
                 if rng.random::<f32>() < max_car_density {
                     commands.spawn((
-                        WorldAssetRoot(assets.get_random_car(rng)),
+                        assets.get_random_car(rng),
                         Transform::from_translation(car_pos + Vec3::new(0.0, 0.0, 0.15))
                             .with_scale(Vec3::splat(0.15))
                             .with_rotation(Quat::from_axis_angle(
@@ -180,7 +180,7 @@ fn spawn_roads_and_cars<R: RngExt>(
 
                 if rng.random::<f32>() < max_car_density {
                     commands.spawn((
-                        WorldAssetRoot(assets.get_random_car(rng)),
+                        assets.get_random_car(rng),
                         Transform::from_translation(car_pos + Vec3::new(0.15, 0.0, 0.0))
                             .with_scale(Vec3::splat(0.15)),
                         Car {
@@ -193,7 +193,7 @@ fn spawn_roads_and_cars<R: RngExt>(
 
                 if rng.random::<f32>() < max_car_density {
                     commands.spawn((
-                        WorldAssetRoot(assets.get_random_car(rng)),
+                        assets.get_random_car(rng),
                         Transform::from_translation(car_pos + Vec3::new(-0.15, 0.0, 0.0))
                             .with_scale(Vec3::splat(0.15))
                             .with_rotation(Quat::from_axis_angle(Vec3::Y, std::f32::consts::PI)),

examples/large_scenes/bevy_city/src/main.rs

@@ -20,7 +20,10 @@ use bevy::{
     world_serialization::WorldInstanceReady,
 };
 
-use crate::{assets::strip_base_url, settings::Settings};
+use crate::{
+    assets::{merge_car_meshes, strip_base_url},
+    settings::Settings,
+};
 use crate::{generate_city::spawn_city, settings::setup_settings_ui};
 
 mod assets;
@@ -75,12 +78,22 @@ fn main() {
         // Like in many realistic large scenes, many of the objects don't move
         // We can accelerate transform propagation by optimizing for this case
         .insert_resource(StaticTransformOptimizations::Enabled)
+        .add_message::<CityAssetsLoaded>()
+        .add_message::<CityAssetsReady>()
+        .add_message::<CitySpawned>()
         .add_systems(Startup, (setup, load_assets))
-        .add_systems(Update, (simulate_cars, loading_screen))
-        .add_observer(add_no_cpu_culling)
+        .add_systems(
+            Update,
+            (
+                simulate_cars,
+                loading_screen,
+                process_assets.run_if(on_message::<CityAssetsLoaded>),
+                on_city_assets_ready.run_if(on_message::<CityAssetsReady>),
+                (add_no_cpu_culling, on_city_spawned, setup_settings_ui)
+                    .run_if(on_message::<CitySpawned>),
+            ),
+        )
         .add_observer(add_no_cpu_culling_on_scene_ready)
-        .add_observer(on_city_assets_ready)
-        .add_observer(setup_settings_ui)
         .run();
 }
 
@@ -168,27 +181,28 @@ struct LoadingText;
 #[derive(Component)]
 struct LoadingPaths;
 
-#[derive(Event)]
+/// Triggers when all the assets managed in [`CityAssets`] are loaded
+#[derive(Message)]
+struct CityAssetsLoaded;
+/// Triggers when all the assets are done loading and have been processed
+#[derive(Message)]
 struct CityAssetsReady;
-
-#[derive(Event)]
+/// Triggers once all the city blocks have been spawned
+#[derive(Message)]
 struct CitySpawned;
 
+#[allow(clippy::type_complexity)]
 fn loading_screen(
     mut commands: Commands,
     assets: Res<CityAssets>,
     asset_server: Res<AssetServer>,
     mut loading_text: Query<&mut Text, With<LoadingText>>,
-    mut loading_paths: Query<&mut Text, (With<LoadingPaths>, Without<LoadingText>)>,
-    loading_screen: Query<Entity, With<LoadingScreen>>,
+    mut loading_paths: Query<(Entity, &mut Text), (With<LoadingPaths>, Without<LoadingText>)>,
 ) {
-    let Ok(loading_screen) = loading_screen.single() else {
-        return;
-    };
     let Ok(mut text) = loading_text.single_mut() else {
         return;
     };
-    let Ok(mut paths_text) = loading_paths.single_mut() else {
+    let Ok((paths_entity, mut paths_text)) = loading_paths.single_mut() else {
         return;
     };
     let mut paths = vec![];
@@ -201,8 +215,10 @@ fn loading_screen(
         }
     }
     if paths.is_empty() {
-        commands.entity(loading_screen).despawn();
-        commands.trigger(CityAssetsReady);
+        commands.entity(paths_entity).despawn();
+        text.0 = "Processing assets...".into();
+        // Use a Message instead of an Event so asset processing only starts on the next frame
+        commands.write_message(CityAssetsLoaded);
     } else {
         text.0 = format!(
             "Loading assets: {}/{}",
@@ -214,14 +230,46 @@ fn loading_screen(
     }
 }
 
+/// Runs after the assets are loaded. For now, this will merge all the meshes for each car gltf into
+/// a single mesh. This is necessary because the tires are separate meshes and this increases the
+/// amount of meshes bevy has to process every frame for no benefits.
+///
+/// Eventually, this will also be used for things like generating LODs
+fn process_assets(
+    mut commands: Commands,
+    mut city_assets: ResMut<CityAssets>,
+    mut world_assets: ResMut<Assets<WorldAsset>>,
+    mut meshes: ResMut<Assets<Mesh>>,
+) {
+    merge_car_meshes(&mut city_assets, &mut world_assets, &mut meshes);
+
+    // Use a Message instead of an Event so spawning the city happens in the next frame
+    commands.write_message(CityAssetsReady);
+}
+
 fn on_city_assets_ready(
-    _: On<CityAssetsReady>,
     mut commands: Commands,
-    assets: Res<CityAssets>,
+    city_assets: Res<CityAssets>,
     args: Res<Args>,
+    mut loading_text: Query<&mut Text, With<LoadingText>>,
 ) {
-    spawn_city(&mut commands, &assets, args.seed, args.size);
-    commands.trigger(CitySpawned);
+    let Ok(mut text) = loading_text.single_mut() else {
+        return;
+    };
+    text.0 = "Spawning city...".into();
+
+    spawn_city(&mut commands, &city_assets, args.seed, args.size);
+    commands.write_message(CitySpawned);
+}
+
+fn on_city_spawned(
+    mut commands: Commands,
+    loading_screen: Option<Single<Entity, With<LoadingScreen>>>,
+) {
+    let Some(loading_screen) = loading_screen else {
+        return;
+    };
+    commands.entity(*loading_screen).despawn();
 }
 
 #[derive(Component)]
@@ -237,6 +285,10 @@ struct Car {
     dir: f32,
 }
 
+/// Do a very naive traffic simulation. This will only move the car to the end of the road then
+/// spawn it back at the start.
+///
+/// Eventually this will be a more complex traffic simulation that should stress the ECS
 fn simulate_cars(
     settings: Res<Settings>,
     roads: Query<(&Road, &Transform, &Children), Without<Car>>,
@@ -267,8 +319,8 @@ fn simulate_cars(
     }
 }
 
+/// Adds [`NoCpuCulling`] to all meshes in the scene after the city is done spawning
 fn add_no_cpu_culling(
-    _: On<CitySpawned>,
     mut commands: Commands,
     meshes: Query<Entity, (With<Mesh3d>, Without<NoCpuCulling>)>,
     args: Res<Args>,
@@ -280,6 +332,10 @@ fn add_no_cpu_culling(
     }
 }
 
+/// Adds [`NoCpuCulling`] to all meshes in all scenes after the city is done spawning
+///
+/// This is required because a few assets are spawned using a [`WorldAssetRoot`] instead of directly
+/// spawning a [`Mesh`]
 fn add_no_cpu_culling_on_scene_ready(
     scene_ready: On<WorldInstanceReady>,
     mut commands: Commands,

examples/large_scenes/bevy_city/src/settings.rs

@@ -13,8 +13,8 @@ use bevy::{
 };
 use rand::RngExt;
 
+use crate::assets::CityAssets;
 use crate::generate_city::{spawn_city, CityRoot};
-use crate::{assets::CityAssets, CitySpawned};
 
 #[derive(Resource)]
 pub struct Settings {
@@ -37,6 +37,10 @@ impl Default for Settings {
     }
 }
 
+pub fn setup_settings_ui(mut commands: Commands) {
+    commands.spawn_scene(settings_ui());
+}
+
 pub fn settings_ui() -> impl Scene {
     bsn! {
         Node {
@@ -161,7 +165,3 @@ pub fn settings_ui() -> impl Scene {
         )]
     }
 }
-
-pub fn setup_settings_ui(_: On<CitySpawned>, mut commands: Commands) {
-    commands.spawn_scene(settings_ui());
-}