Add extra_asset_source example (#11824)

# Objective

- Make it easier to figure out how to add asset sources

## Solution

- Add an example that adds an asset source, it functions almost
identical to the embedded_asset example
- Move the file from the embedded_asset example into a `files/` folder

Cargo.toml

@@ -1237,6 +1237,17 @@ description = "Embed an asset in the application binary and load it"
 category = "Assets"
 wasm = true
 
+[[example]]
+name = "extra_asset_source"
+path = "examples/asset/extra_source.rs"
+doc-scrape-examples = true
+
+[package.metadata.example.extra_asset_source]
+name = "Extra asset source"
+description = "Load an asset from a non-standard asset source"
+category = "Assets"
+wasm = true
+
 [[example]]
 name = "hot_asset_reloading"
 path = "examples/asset/hot_asset_reloading.rs"

examples/README.md

@@ -197,6 +197,7 @@ Example | Description
 [Custom Asset](../examples/asset/custom_asset.rs) | Implements a custom asset loader
 [Custom Asset IO](../examples/asset/custom_asset_reader.rs) | Implements a custom AssetReader
 [Embedded Asset](../examples/asset/embedded_asset.rs) | Embed an asset in the application binary and load it
+[Extra asset source](../examples/asset/extra_source.rs) | Load an asset from a non-standard asset source
 [Hot Reloading of Assets](../examples/asset/hot_asset_reloading.rs) | Demonstrates automatic reloading of assets when modified on disk
 
 ## Async Tasks

examples/asset/embedded_asset.rs

@@ -20,7 +20,7 @@ impl Plugin for EmbeddedAssetPlugin {
         let omit_prefix = "examples/asset";
         // Path to asset must be relative to this file, because that's how
         // include_bytes! works.
-        embedded_asset!(app, omit_prefix, "bevy_pixel_light.png");
+        embedded_asset!(app, omit_prefix, "files/bevy_pixel_light.png");
     }
 }
 
@@ -31,11 +31,11 @@ fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
     let crate_name = "embedded_asset";
 
     // The actual file path relative to workspace root is
-    // "examples/asset/bevy_pixel_light.png".
+    // "examples/asset/files/bevy_pixel_light.png".
     //
     // We omit the "examples/asset" from the embedded_asset! call and replace it
     // with the crate name.
-    let path = Path::new(crate_name).join("bevy_pixel_light.png");
+    let path = Path::new(crate_name).join("files/bevy_pixel_light.png");
     let source = AssetSourceId::from("embedded");
     let asset_path = AssetPath::from_path(&path).with_source(source);
 
@@ -43,7 +43,7 @@ fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
     // path.
     assert_eq!(
         asset_path,
-        "embedded://embedded_asset/bevy_pixel_light.png".into()
+        "embedded://embedded_asset/files/bevy_pixel_light.png".into()
     );
 
     commands.spawn(SpriteBundle {

examples/asset/extra_source.rs

@@ -0,0 +1,51 @@
+//! An example of registering an extra asset source, and loading assets from it.
+//! This asset source exists in addition to the default asset source.
+
+use bevy::asset::{
+    io::{AssetSourceBuilder, AssetSourceBuilders, AssetSourceId},
+    AssetPath,
+};
+use bevy::prelude::*;
+use std::path::Path;
+
+fn main() {
+    let mut app = App::new();
+
+    // We add an extra asset source with the name "example_files" to the
+    // AssetSourceBuilders.
+    // This needs to be done before AssetPlugin finalizes building them
+    let mut sources = app
+        .world
+        .get_resource_or_insert_with::<AssetSourceBuilders>(default);
+    sources.insert(
+        "example_files",
+        AssetSourceBuilder::platform_default("examples/asset/files", None),
+    );
+
+    // DefaultPlugins contains AssetPlugin so it needs to be added to our App
+    // after inserting our new asset source
+    app.add_plugins(DefaultPlugins)
+        .add_systems(Startup, setup)
+        .run();
+}
+
+fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
+    commands.spawn(Camera2dBundle::default());
+
+    // Now we can load the asset using our new asset source
+    //
+    // The actual file path relative to workspace root is
+    // "examples/asset/files/bevy_pixel_light.png".
+    let path = Path::new("bevy_pixel_light.png");
+    let source = AssetSourceId::from("example_files");
+    let asset_path = AssetPath::from_path(path).with_source(source);
+
+    // You could also parse this URL-like string representation for the asset
+    // path.
+    assert_eq!(asset_path, "example_files://bevy_pixel_light.png".into());
+
+    commands.spawn(SpriteBundle {
+        texture: asset_server.load(asset_path),
+        ..default()
+    });
+}