Replace all different load variants in AssetServer with a builder.

_release-content/migration-guides/load_builder.md

@@ -0,0 +1,30 @@
+---
+title: Advanced AssetServer load variants are now exposed through a builder pattern.
+pull_requests: [23663]
+---
+
+In previous versions of Bevy, there were many different ways to load an asset:
+
+- `AssetServer::load`
+- `AssetServer::load_acquire`
+- `AssetServer::load_untyped`
+- `AssetServer::load_acquire_override_with_settings`
+- etc.
+
+All these variants have been simplified to only two variants:
+
+1. `AssetServer::load()`: This is just a convenience and just calls the load builder internally.
+2. `AssetServer::load_builder()`: allows for constructing more complex loads like untyped loads,
+   loads including guards, loads with settings, etc.
+
+Every load variant above can be reimplemented using `load_builder`, and each one of these methods
+has deprecation messages on them explaining their new equivalent. For example,
+`load_with_settings_override` can now be replaced by:
+
+```rust
+asset_server
+    .load_builder()
+    .with_settings(settings)
+    .override_unapproved()
+    .load(path)
+```

crates/bevy_asset/src/direct_access_ext.rs

@@ -3,7 +3,7 @@
 
 use bevy_ecs::world::World;
 
-use crate::{meta::Settings, Asset, AssetPath, AssetServer, Assets, Handle};
+use crate::{meta::Settings, Asset, AssetPath, AssetServer, Assets, Handle, LoadBuilder};
 
 /// An extension trait for methods for working with assets directly from a [`World`].
 pub trait DirectAssetAccessExt {
@@ -13,7 +13,11 @@ pub trait DirectAssetAccessExt {
     /// Load an asset similarly to [`AssetServer::load`].
     fn load_asset<'a, A: Asset>(&self, path: impl Into<AssetPath<'a>>) -> Handle<A>;
 
+    /// Creates a new [`LoadBuilder`] similar to [`AssetServer::load_builder`].
+    fn load_builder(&self) -> LoadBuilder<'_>;
+
     /// Load an asset with settings, similarly to [`AssetServer::load_with_settings`].
+    #[deprecated(note = "Use `world.load_builder().with_settings(settings).load(path)`")]
     fn load_asset_with_settings<'a, A: Asset, S: Settings>(
         &self,
         path: impl Into<AssetPath<'a>>,
@@ -37,6 +41,15 @@ impl DirectAssetAccessExt for World {
     fn load_asset<'a, A: Asset>(&self, path: impl Into<AssetPath<'a>>) -> Handle<A> {
         self.resource::<AssetServer>().load(path)
     }
+
+    /// Creates a new [`LoadBuilder`] similar to [`AssetServer::load_builder`].
+    ///
+    /// # Panics
+    /// If `self` doesn't have an [`AssetServer`] resource initialized yet.
+    fn load_builder(&self) -> LoadBuilder<'_> {
+        self.resource::<AssetServer>().load_builder()
+    }
+
     /// Load an asset with settings, similarly to [`AssetServer::load_with_settings`].
     ///
     /// # Panics
@@ -47,6 +60,8 @@ impl DirectAssetAccessExt for World {
         settings: impl Fn(&mut S) + Send + Sync + 'static,
     ) -> Handle<A> {
         self.resource::<AssetServer>()
-            .load_with_settings(path, settings)
+            .load_builder()
+            .with_settings(settings)
+            .load(path.into())
     }
 }

crates/bevy_asset/src/io/embedded/mod.rs

@@ -172,8 +172,9 @@ impl GetAssetServer for AssetServer {
 /// This macro takes two arguments and an optional third one:
 /// 1. The asset source. It may be `AssetServer`, `World` or `App`.
 /// 2. The path to the asset to embed, as a string literal.
-/// 3. Optionally, a closure of the same type as in [`AssetServer::load_with_settings`].
-///    Consider explicitly typing the closure argument in case of type error.
+/// 3. Optionally, a closure of the same type as in
+///    [`LoadBuilder::with_settings`](crate::LoadBuilder::with_settings). Consider explicitly typing
+///    the closure argument in case of type error.
 ///
 /// # Usage
 ///
@@ -196,7 +197,7 @@ macro_rules! load_embedded_asset {
     }};
     ($provider: expr, $path: literal, $settings: expr) => {{
         let (path, asset_server) = $crate::load_embedded_asset!(@get: $path, $provider);
-        asset_server.load_with_settings(path, $settings)
+        asset_server.load_builder().with_settings($settings).load(path)
     }};
     ($provider: expr, $path: literal) => {{
         let (path, asset_server) = $crate::load_embedded_asset!(@get: $path, $provider);

crates/bevy_asset/src/lib.rs

@@ -277,8 +277,8 @@ pub struct AssetPlugin {
 pub enum UnapprovedPathMode {
     /// Unapproved asset loading is allowed. This is strongly discouraged.
     Allow,
-    /// Fails to load any asset that is unapproved, unless an override method is used, like
-    /// [`AssetServer::load_override`].
+    /// Fails to load any asset that is unapproved, unless [`LoadBuilder::override_unapproved`] is
+    /// used.
     Deny,
     /// Fails to load any asset that is unapproved.
     #[default]
@@ -2130,7 +2130,10 @@ mod tests {
 
         let asset_server = app.world().resource::<AssetServer>().clone();
         assert_eq!(
-            asset_server.load_override::<CoolText>("../a.cool.ron"),
+            asset_server
+                .load_builder()
+                .override_unapproved()
+                .load::<CoolText>("../a.cool.ron"),
             Handle::default()
         );
     }
@@ -2151,7 +2154,10 @@ mod tests {
         let mut app = unapproved_path_setup(UnapprovedPathMode::Deny);
 
         let asset_server = app.world().resource::<AssetServer>().clone();
-        let handle = asset_server.load_override::<CoolText>("../a.cool.ron");
+        let handle = asset_server
+            .load_builder()
+            .override_unapproved()
+            .load::<CoolText>("../a.cool.ron");
         assert_ne!(handle, Handle::default());
 
         // Make sure this asset actually loads.
@@ -2543,10 +2549,10 @@ mod tests {
         // Load the test asset twice but with different settings.
 
         fn load(asset_server: &AssetServer, path: &'static str, value: u8) -> Handle<U8Asset> {
-            asset_server.load_with_settings::<U8Asset, U8LoaderSettings>(
-                path,
-                move |s: &mut U8LoaderSettings| s.0 = value,
-            )
+            asset_server
+                .load_builder()
+                .with_settings(move |s: &mut U8LoaderSettings| s.0 = value)
+                .load::<U8Asset>(path)
         }
 
         let handle_1 = load(asset_server, "test.u8", 1);
@@ -3116,36 +3122,54 @@ mod tests {
             // TODO: We have way too many "load" variants. We **need** to simplify this.
             assert_eq!(asset_server.load(path), Handle::<TestAsset>::default());
             assert_eq!(
-                asset_server.load_acquire(path, ()),
+                asset_server.load_builder().with_guard(()).load(path),
                 Handle::<TestAsset>::default()
             );
             assert_eq!(
-                asset_server.load_acquire_override(path, ()),
+                asset_server
+                    .load_builder()
+                    .with_guard(())
+                    .override_unapproved()
+                    .load(path),
                 Handle::<TestAsset>::default()
             );
             assert_eq!(
-                asset_server.load_acquire_with_settings(path, boring_settings, ()),
+                asset_server
+                    .load_builder()
+                    .with_guard(())
+                    .with_settings(boring_settings)
+                    .load(path),
                 Handle::<TestAsset>::default()
             );
             assert_eq!(
-                asset_server.load_erased(TYPE_ID, path),
+                asset_server.load_builder().load_erased(TYPE_ID, path),
                 Handle::<TestAsset>::default()
             );
             assert_eq!(
-                asset_server.load_override(path),
+                asset_server.load_builder().override_unapproved().load(path),
                 Handle::<TestAsset>::default()
             );
-            assert_eq!(asset_server.load_untyped(path), Handle::default());
+            assert_eq!(
+                asset_server.load_builder().load_untyped(path),
+                Handle::default()
+            );
             assert!(matches!(
-                block_on(asset_server.load_untyped_async(path)),
+                block_on(asset_server.load_builder().load_untyped_async(path)),
                 Err(AssetLoadError::EmptyPath(reported_path)) if AssetPath::from(path) == reported_path
             ));
             assert_eq!(
-                asset_server.load_with_settings(path, |_: &mut ()| {}),
+                asset_server
+                    .load_builder()
+                    .with_settings(|_: &mut ()| {})
+                    .load(path),
                 Handle::<TestAsset>::default()
             );
             assert_eq!(
-                asset_server.load_with_settings_override(path, |_: &mut ()| {}),
+                asset_server
+                    .load_builder()
+                    .with_settings(|_: &mut ()| {})
+                    .override_unapproved()
+                    .load(path),
                 Handle::<TestAsset>::default()
             );
         }

crates/bevy_asset/src/loader.rs

@@ -613,7 +613,7 @@ impl<'a> LoadContext<'a> {
         label: impl Into<CowArc<'b, str>>,
     ) -> Handle<A> {
         let path = self.asset_path.clone().with_label(label);
-        let handle = self.asset_server.get_or_create_path_handle::<A>(path, None);
+        let handle = self.asset_server.get_or_create_path_handle(path, None);
         // `get_or_create_path_handle` always returns a Strong variant, so we are safe to unwrap.
         let index = (&handle).try_into().unwrap();
         self.dependencies.insert(index);

crates/bevy_asset/src/loader_builders.rs

@@ -347,22 +347,25 @@ impl NestedLoader<'_, '_, DynamicTyped, Deferred> {
         let handle = if self.load_context.should_load_dependencies {
             self.load_context
                 .asset_server
-                .load_erased_with_meta_transform(
+                .load_with_meta_transform_erased(
                     path,
                     self.typing.asset_type_id,
+                    None,
                     self.meta_transform,
                     (),
+                    false,
                 )
         } else {
             self.load_context
                 .asset_server
                 .get_or_create_path_handle_erased(
                     path,
                     self.typing.asset_type_id,
+                    None,
                     self.meta_transform,
                 )
         };
-        // `load_erased_with_meta_transform` and `get_or_create_path_handle_erased` always returns a
+        // `load_with_meta_transform_erased` and `get_or_create_path_handle_erased` always returns a
         // Strong variant, so we are safe to unwrap.
         let index = (&handle).try_into().unwrap();
         self.load_context.dependencies.insert(index);
@@ -384,7 +387,7 @@ impl NestedLoader<'_, '_, UnknownTyped, Deferred> {
         let handle = if self.load_context.should_load_dependencies {
             self.load_context
                 .asset_server
-                .load_unknown_type_with_meta_transform(path, self.meta_transform)
+                .load_unknown_type_with_meta_transform(path, self.meta_transform, (), false)
         } else {
             self.load_context
                 .asset_server

crates/bevy_asset/src/reflect.rs

@@ -398,7 +398,7 @@ impl ReflectSerializerProcessor for HandleSerializeProcessor {
 pub trait LoadFromPath {
     /// Initiates the load for the given expected type ID, and the path.
     ///
-    /// See [`AssetServer::load_erased`] for more.
+    /// See [`LoadBuilder::load_erased`](crate::LoadBuilder::load_erased) for more.
     fn load_from_path_erased(&mut self, type_id: TypeId, path: AssetPath<'static>)
         -> UntypedHandle;
 }
@@ -419,7 +419,7 @@ impl LoadFromPath for AssetServer {
         type_id: TypeId,
         path: AssetPath<'static>,
     ) -> UntypedHandle {
-        self.load_erased(type_id, path)
+        self.load_builder().load_erased(type_id, path)
     }
 }
 
@@ -429,7 +429,7 @@ impl LoadFromPath for &AssetServer {
         type_id: TypeId,
         path: AssetPath<'static>,
     ) -> UntypedHandle {
-        self.load_erased(type_id, path)
+        self.load_builder().load_erased(type_id, path)
     }
 }
 
@@ -625,7 +625,7 @@ mod tests {
             let type_registry = app.world().resource::<AppTypeRegistry>().0.clone();
             let asset_server = app.world().resource::<AssetServer>().clone();
 
-            let untyped = asset_server.load_untyped("def.cool.ron");
+            let untyped = asset_server.load_builder().load_untyped("def.cool.ron");
             run_app_until(&mut app, |_| asset_server.is_loaded(&untyped).then_some(()));
             let untyped = app
                 .world()

crates/bevy_asset/src/server/info.rs

@@ -14,9 +14,11 @@ use bevy_ecs::world::World;
 use bevy_platform::collections::{hash_map::Entry, HashMap, HashSet};
 use bevy_tasks::Task;
 use bevy_utils::TypeIdMap;
-use core::{any::TypeId, task::Waker};
+use core::{
+    any::{type_name, TypeId},
+    task::Waker,
+};
 use crossbeam_channel::Sender;
-use either::Either;
 use thiserror::Error;
 use tracing::warn;
 
@@ -123,7 +125,8 @@ impl AssetInfos {
                 None,
                 true,
             ),
-            Either::Left(type_name),
+            type_id,
+            Some(type_name),
         )
         .unwrap()
     }
@@ -168,15 +171,13 @@ impl AssetInfos {
         loading_mode: HandleLoadingMode,
         meta_transform: Option<MetaTransform>,
     ) -> (Handle<A>, bool) {
-        let result = self.get_or_create_path_handle_internal(
+        let (handle, should_load) = self.get_or_create_path_handle_erased(
             path,
-            Some(TypeId::of::<A>()),
+            TypeId::of::<A>(),
+            Some(type_name::<A>()),
             loading_mode,
             meta_transform,
         );
-        // it is ok to unwrap because TypeId was specified above
-        let (handle, should_load) =
-            unwrap_with_context(result, Either::Left(core::any::type_name::<A>())).unwrap();
         (handle.typed_unchecked(), should_load)
     }
 
@@ -194,12 +195,8 @@ impl AssetInfos {
             loading_mode,
             meta_transform,
         );
-        let type_info = match type_name {
-            Some(type_name) => Either::Left(type_name),
-            None => Either::Right(type_id),
-        };
-        unwrap_with_context(result, type_info)
-            .expect("type should be correct since the `TypeId` is specified above")
+        // it is ok to unwrap because TypeId was specified above
+        unwrap_with_context(result, type_id, type_name).unwrap()
     }
 
     /// Retrieves asset tracking data, or creates it if it doesn't exist.
@@ -809,17 +806,18 @@ pub(crate) enum GetOrCreateHandleInternalError {
 
 pub(crate) fn unwrap_with_context<T>(
     result: Result<T, GetOrCreateHandleInternalError>,
-    type_info: Either<&str, TypeId>,
+    type_id: TypeId,
+    type_name: Option<&str>,
 ) -> Option<T> {
     match result {
         Ok(value) => Some(value),
         Err(GetOrCreateHandleInternalError::HandleMissingButTypeIdNotSpecified) => None,
-        Err(GetOrCreateHandleInternalError::MissingHandleProviderError(_)) => match type_info {
-            Either::Left(type_name) => {
+        Err(GetOrCreateHandleInternalError::MissingHandleProviderError(_)) => match type_name {
+            Some(type_name) => {
                 panic!("Cannot allocate an Asset Handle of type '{type_name}' because the asset type has not been initialized. \
                     Make sure you have called `app.init_asset::<{type_name}>()`");
             }
-            Either::Right(type_id) => {
+            None => {
                 panic!("Cannot allocate an AssetHandle of type '{type_id:?}' because the asset type has not been initialized. \
                     Make sure you have called `app.init_asset::<(actual asset type)>()`")
             }