- resovles #15098

- implements consistently named AssertServer methods for
    asset, dependency, and recursive dependency load states
- adds error to DependencyLoadState::Failed and
    RecursiveDependencyLoadState::Failed

Author: crvarner

crates/bevy_asset/src/lib.rs

@@ -1095,13 +1095,19 @@ mod tests {
 
             assert!(d_text.is_none());
             assert!(matches!(d_load, LoadState::Failed(_)));
-            assert_eq!(d_deps, DependencyLoadState::Failed);
-            assert_eq!(d_rec_deps, RecursiveDependencyLoadState::Failed);
+            assert!(matches!(d_deps, DependencyLoadState::Failed(_)));
+            assert!(matches!(
+                d_rec_deps,
+                RecursiveDependencyLoadState::Failed(_)
+            ));
 
             assert_eq!(a_text.text, "a");
             assert_eq!(a_load, LoadState::Loaded);
             assert_eq!(a_deps, DependencyLoadState::Loaded);
-            assert_eq!(a_rec_deps, RecursiveDependencyLoadState::Failed);
+            assert!(matches!(
+                a_rec_deps,
+                RecursiveDependencyLoadState::Failed(_)
+            ));
 
             assert_eq!(b_text.text, "b");
             assert_eq!(b_load, LoadState::Loaded);
@@ -1110,8 +1116,25 @@ mod tests {
 
             assert_eq!(c_text.text, "c");
             assert_eq!(c_load, LoadState::Loaded);
-            assert_eq!(c_deps, DependencyLoadState::Failed);
-            assert_eq!(c_rec_deps, RecursiveDependencyLoadState::Failed);
+            assert!(matches!(c_deps, DependencyLoadState::Failed(_)));
+            assert!(matches!(
+                c_rec_deps,
+                RecursiveDependencyLoadState::Failed(_)
+            ));
+
+            assert_eq!(asset_server.load_state(a_id), LoadState::Loaded);
+            assert_eq!(
+                asset_server.dependency_load_state(a_id),
+                DependencyLoadState::Loaded
+            );
+            assert!(matches!(
+                asset_server.recursive_dependency_load_state(a_id),
+                RecursiveDependencyLoadState::Failed(_)
+            ));
+
+            assert!(asset_server.is_loaded(a_id));
+            assert!(asset_server.is_loaded_with_dependencies(a_id));
+            assert!(!asset_server.is_loaded_with_recursive_dependencies(a_id));
 
             Some(())
         });

crates/bevy_asset/src/server/info.rs

@@ -390,6 +390,7 @@ impl AssetInfos {
         let mut failed_deps = HashSet::new();
         let mut loading_rec_deps = loading_deps.clone();
         let mut failed_rec_deps = HashSet::new();
+        let mut first_rec_error = None;
         loading_deps.retain(|dep_id| {
             if let Some(dep_info) = self.get_mut(*dep_id) {
                 match dep_info.rec_dep_load_state {
@@ -404,7 +405,10 @@ impl AssetInfos {
                         // If dependency is loaded, reduce our count by one
                         loading_rec_deps.remove(dep_id);
                     }
-                    RecursiveDependencyLoadState::Failed => {
+                    RecursiveDependencyLoadState::Failed(ref error) => {
+                        if first_rec_error.is_none() {
+                            first_rec_error = Some(error.clone());
+                        }
                         failed_rec_deps.insert(*dep_id);
                         loading_rec_deps.remove(dep_id);
                     }
@@ -437,7 +441,7 @@ impl AssetInfos {
         let dep_load_state = match (loading_deps.len(), failed_deps.len()) {
             (0, 0) => DependencyLoadState::Loaded,
             (_loading, 0) => DependencyLoadState::Loading,
-            (_loading, _failed) => DependencyLoadState::Failed,
+            (_loading, _failed) => DependencyLoadState::Failed(first_rec_error.clone().unwrap()),
         };
 
         let rec_dep_load_state = match (loading_rec_deps.len(), failed_rec_deps.len()) {
@@ -450,7 +454,7 @@ impl AssetInfos {
                 RecursiveDependencyLoadState::Loaded
             }
             (_loading, 0) => RecursiveDependencyLoadState::Loading,
-            (_loading, _failed) => RecursiveDependencyLoadState::Failed,
+            (_loading, _failed) => RecursiveDependencyLoadState::Failed(first_rec_error.unwrap()),
         };
 
         let (dependants_waiting_on_load, dependants_waiting_on_rec_load) = {
@@ -480,14 +484,14 @@ impl AssetInfos {
             info.failed_rec_dependencies = failed_rec_deps;
             info.load_state = LoadState::Loaded;
             info.dep_load_state = dep_load_state;
-            info.rec_dep_load_state = rec_dep_load_state;
+            info.rec_dep_load_state = rec_dep_load_state.clone();
             if watching_for_changes {
                 info.loader_dependencies = loaded_asset.loader_dependencies;
             }
 
             let dependants_waiting_on_rec_load = if matches!(
                 rec_dep_load_state,
-                RecursiveDependencyLoadState::Loaded | RecursiveDependencyLoadState::Failed
+                RecursiveDependencyLoadState::Loaded | RecursiveDependencyLoadState::Failed(_)
             ) {
                 Some(std::mem::take(
                     &mut info.dependants_waiting_on_recursive_dep_load,
@@ -519,9 +523,9 @@ impl AssetInfos {
                         Self::propagate_loaded_state(self, loaded_asset_id, dep_id, sender);
                     }
                 }
-                RecursiveDependencyLoadState::Failed => {
+                RecursiveDependencyLoadState::Failed(error) => {
                     for dep_id in dependants_waiting_on_rec_load {
-                        Self::propagate_failed_state(self, loaded_asset_id, dep_id);
+                        Self::propagate_failed_state(self, loaded_asset_id, dep_id, &error);
                     }
                 }
                 RecursiveDependencyLoadState::Loading | RecursiveDependencyLoadState::NotLoaded => {
@@ -570,11 +574,12 @@ impl AssetInfos {
         infos: &mut AssetInfos,
         failed_id: UntypedAssetId,
         waiting_id: UntypedAssetId,
+        error: &Arc<AssetLoadError>,
     ) {
         let dependants_waiting_on_rec_load = if let Some(info) = infos.get_mut(waiting_id) {
             info.loading_rec_dependencies.remove(&failed_id);
             info.failed_rec_dependencies.insert(failed_id);
-            info.rec_dep_load_state = RecursiveDependencyLoadState::Failed;
+            info.rec_dep_load_state = RecursiveDependencyLoadState::Failed(error.clone());
             Some(std::mem::take(
                 &mut info.dependants_waiting_on_recursive_dep_load,
             ))
@@ -584,7 +589,7 @@ impl AssetInfos {
 
         if let Some(dependants_waiting_on_rec_load) = dependants_waiting_on_rec_load {
             for dep_id in dependants_waiting_on_rec_load {
-                Self::propagate_failed_state(infos, waiting_id, dep_id);
+                Self::propagate_failed_state(infos, waiting_id, dep_id, error);
             }
         }
     }
@@ -595,14 +600,15 @@ impl AssetInfos {
             return;
         }
 
+        let error = Arc::new(error);
         let (dependants_waiting_on_load, dependants_waiting_on_rec_load) = {
             let Some(info) = self.get_mut(failed_id) else {
                 // The asset was already dropped.
                 return;
             };
-            info.load_state = LoadState::Failed(Box::new(error));
-            info.dep_load_state = DependencyLoadState::Failed;
-            info.rec_dep_load_state = RecursiveDependencyLoadState::Failed;
+            info.load_state = LoadState::Failed(error.clone());
+            info.dep_load_state = DependencyLoadState::Failed(error.clone());
+            info.rec_dep_load_state = RecursiveDependencyLoadState::Failed(error.clone());
             (
                 std::mem::take(&mut info.dependants_waiting_on_load),
                 std::mem::take(&mut info.dependants_waiting_on_recursive_dep_load),
@@ -613,12 +619,15 @@ impl AssetInfos {
             if let Some(info) = self.get_mut(waiting_id) {
                 info.loading_dependencies.remove(&failed_id);
                 info.failed_dependencies.insert(failed_id);
-                info.dep_load_state = DependencyLoadState::Failed;
+                // don't overwrite DependencyLoadState if already failed to preserve first error
+                if !(matches!(info.dep_load_state, DependencyLoadState::Failed(_))) {
+                    info.dep_load_state = DependencyLoadState::Failed(error.clone());
+                }
             }
         }
 
         for waiting_id in dependants_waiting_on_rec_load {
-            Self::propagate_failed_state(self, failed_id, waiting_id);
+            Self::propagate_failed_state(self, failed_id, waiting_id, &error);
         }
     }
 

crates/bevy_asset/src/server/mod.rs

@@ -895,26 +895,49 @@ impl AssetServer {
         &self,
         id: impl Into<UntypedAssetId>,
     ) -> Option<(LoadState, DependencyLoadState, RecursiveDependencyLoadState)> {
+        self.data.infos.read().get(id.into()).map(|i| {
+            (
+                i.load_state.clone(),
+                i.dep_load_state.clone(),
+                i.rec_dep_load_state.clone(),
+            )
+        })
+    }
+
+    /// Retrieves the main [`LoadState`] of a given asset `id`.
+    ///
+    /// Note that this is "just" the root asset load state. To get the load state of
+    /// its dependencies or recursive dependencies, see [`AssetServer::get_dependency_load_state`]
+    /// and [`AssetServer::get_recursive_dependency_load_state`] respectively.
+    pub fn get_load_state(&self, id: impl Into<UntypedAssetId>) -> Option<LoadState> {
         self.data
             .infos
             .read()
             .get(id.into())
-            .map(|i| (i.load_state.clone(), i.dep_load_state, i.rec_dep_load_state))
+            .map(|i| i.load_state.clone())
     }
 
-    /// Retrieves the main [`LoadState`] of a given asset `id`.
+    /// Retrieves the [`DependencyLoadState`] of a given asset `id`'s dependencies.
     ///
-    /// Note that this is "just" the root asset load state. To check if an asset _and_ its recursive
-    /// dependencies have loaded, see [`AssetServer::is_loaded_with_dependencies`].
-    pub fn get_load_state(&self, id: impl Into<UntypedAssetId>) -> Option<LoadState> {
+    /// Note that this is only the load state of direct dependencies of the root asset. To get
+    /// the load state of the root asset itself or its recursive dependencies, see
+    /// [`AssetServer::get_load_state`] and [`AssetServer::get_recursive_dependency_load_state`] respectively.
+    pub fn get_dependency_load_state(
+        &self,
+        id: impl Into<UntypedAssetId>,
+    ) -> Option<DependencyLoadState> {
         self.data
             .infos
             .read()
             .get(id.into())
-            .map(|i| i.load_state.clone())
+            .map(|i| i.dep_load_state.clone())
     }
 
-    /// Retrieves the [`RecursiveDependencyLoadState`] of a given asset `id`.
+    /// Retrieves the main [`RecursiveDependencyLoadState`] of a given asset `id`'s recursive dependencies.
+    ///
+    /// Note that this is only the load state of recursive dependencies of the root asset. To get
+    /// the load state of the root asset itself or its direct dependencies only, see
+    /// [`AssetServer::get_load_state`] and [`AssetServer::get_dependency_load_state`] respectively.
     pub fn get_recursive_dependency_load_state(
         &self,
         id: impl Into<UntypedAssetId>,
@@ -923,15 +946,30 @@ impl AssetServer {
             .infos
             .read()
             .get(id.into())
-            .map(|i| i.rec_dep_load_state)
+            .map(|i| i.rec_dep_load_state.clone())
     }
 
     /// Retrieves the main [`LoadState`] of a given asset `id`.
+    ///
+    /// This is the same as [`AssetServer::get_load_state`] except the result is unwrapped. If
+    /// the result is None, [`LoadState::NotLoaded`] is returned.
     pub fn load_state(&self, id: impl Into<UntypedAssetId>) -> LoadState {
         self.get_load_state(id).unwrap_or(LoadState::NotLoaded)
     }
 
+    /// Retrieves the [`DependencyLoadState`] of a given asset `id`.
+    ///
+    /// This is the same as [`AssetServer::get_dependency_load_state`] except the result is unwrapped. If
+    /// the result is None, [`DependencyLoadState::NotLoaded`] is returned.
+    pub fn dependency_load_state(&self, id: impl Into<UntypedAssetId>) -> DependencyLoadState {
+        self.get_dependency_load_state(id)
+            .unwrap_or(DependencyLoadState::NotLoaded)
+    }
+
     /// Retrieves the  [`RecursiveDependencyLoadState`] of a given asset `id`.
+    ///
+    /// This is the same as [`AssetServer::get_recursive_dependency_load_state`] except the result is unwrapped. If
+    /// the result is None, [`RecursiveDependencyLoadState::NotLoaded`] is returned.
     pub fn recursive_dependency_load_state(
         &self,
         id: impl Into<UntypedAssetId>,
@@ -940,11 +978,30 @@ impl AssetServer {
             .unwrap_or(RecursiveDependencyLoadState::NotLoaded)
     }
 
-    /// Returns true if the asset and all of its dependencies (recursive) have been loaded.
+    /// Convenience method that returns true if the asset has been loaded.
+    pub fn is_loaded(&self, id: impl Into<UntypedAssetId>) -> bool {
+        matches!(self.load_state(id), LoadState::Loaded)
+    }
+
+    /// Convenience method that returns true if the asset and all of its direct dependencies have been loaded.
     pub fn is_loaded_with_dependencies(&self, id: impl Into<UntypedAssetId>) -> bool {
-        let id = id.into();
-        self.load_state(id) == LoadState::Loaded
-            && self.recursive_dependency_load_state(id) == RecursiveDependencyLoadState::Loaded
+        matches!(
+            self.get_load_states(id),
+            Some((LoadState::Loaded, DependencyLoadState::Loaded, _))
+        )
+    }
+
+    /// Convenience method that returns true if the asset, all of its dependencies, and all of its recursive
+    /// dependencies have been loaded.
+    pub fn is_loaded_with_recursive_dependencies(&self, id: impl Into<UntypedAssetId>) -> bool {
+        matches!(
+            self.get_load_states(id),
+            Some((
+                LoadState::Loaded,
+                DependencyLoadState::Loaded,
+                RecursiveDependencyLoadState::Loaded
+            ))
+        )
     }
 
     /// Returns an active handle for the given path, if the asset at the given path has already started loading,
@@ -1361,11 +1418,11 @@ pub enum LoadState {
     /// The asset has been loaded and has been added to the [`World`]
     Loaded,
     /// The asset failed to load.
-    Failed(Box<AssetLoadError>),
+    Failed(Arc<AssetLoadError>),
 }
 
 /// The load state of an asset's dependencies.
-#[derive(Component, Copy, Clone, Debug, Eq, PartialEq, Ord, PartialOrd)]
+#[derive(Component, Clone, Debug, Eq, PartialEq)]
 pub enum DependencyLoadState {
     /// The asset has not started loading yet
     NotLoaded,
@@ -1374,11 +1431,11 @@ pub enum DependencyLoadState {
     /// Dependencies have all loaded
     Loaded,
     /// One or more dependencies have failed to load
-    Failed,
+    Failed(Arc<AssetLoadError>),
 }
 
 /// The recursive load state of an asset's dependencies.
-#[derive(Component, Copy, Clone, Debug, Eq, PartialEq, Ord, PartialOrd)]
+#[derive(Component, Clone, Debug, Eq, PartialEq)]
 pub enum RecursiveDependencyLoadState {
     /// The asset has not started loading yet
     NotLoaded,
@@ -1387,7 +1444,7 @@ pub enum RecursiveDependencyLoadState {
     /// Dependencies in this asset's dependency tree have all loaded
     Loaded,
     /// One or more dependencies have failed to load in this asset's dependency tree
-    Failed,
+    Failed(Arc<AssetLoadError>),
 }
 
 /// An error that occurs during an [`Asset`] load.