Non-blocking load_untyped using a wrapper asset

[NiklasEi]

Objective

• Assets v2 does not currently offer a public API to load untyped assets

Solution

• Wrap the untyped handle in a LoadedUntypedAsset asset to offer a non-blocking load for untyped assets. The user does not need to know the actual asset type.
• Handles to LoadedUntypedAsset have the same path as the wrapped asset, but their handles are shared using a label.

The user side of load_untyped looks like this:

use bevy::prelude::*;
use bevy_internal::asset::LoadedUntypedAsset;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_systems(Startup, setup)
        .add_systems(Update, check)
        .run();
}

#[derive(Resource)]
struct UntypedAsset {
    handle: Handle<LoadedUntypedAsset>,
}

fn setup(
    mut commands: Commands,
    asset_server: Res<AssetServer>,
) {
    let handle = asset_server.load_untyped("branding/banner.png");
    commands.insert_resource(UntypedAsset { handle });
    commands.spawn(Camera2dBundle::default());
}

fn check(
    mut commands: Commands,
    res: Option<Res<UntypedAsset>>,
    assets: Res<Assets<LoadedUntypedAsset>>,
) {
    if let Some(untyped_asset) = res {
        if let Some(asset) = assets.get(&untyped_asset.handle) {
            commands.spawn(SpriteBundle {
                texture: asset.handle.clone().typed(),
                ..default()
            });
            commands.remove_resource::<UntypedAsset>();
        }
    }
}

---

Changelog

• load_untyped on the asset server now returns a handle to a LoadedUntypedAsset instead of an untyped handle to the asset at the given path. The untyped handle for the given path can be retrieved from the LoadedUntypedAsset once it is done loading.

Migration Guide

Whenever possible use the typed API in order to directly get a handle to your asset. If you do not know the type or need to use load_untyped for a different reason, Bevy 0.12 introduces an additional layer of indirection. The asset server will return a handle to a LoadedUntypedAsset, which will load in the background. Once it is loaded, the untyped handle to the asset file can be retrieved from the LoadedUntypedAssets field handle.

[cart]

We can't safely use labels here:

// this will internally be referenced as "a.gltf#untyped"
assets.load_untyped("a.gltf#Foo")

// this will internally be referenced as "a.gltf#untyped"
assets.load_untyped("a.gltf#Bar")

This will also be ambiguous with any asset labeled untyped in the asset, which is unlikely, but still possible and likely to occur eventually.

Instead, I think we should create a reasonably unique asset source name (generated from the real asset source). This will create a brand new namespace that will never step on actual assets (and can still use labels to differentiate).

[cart]

Just pushed a fix!

[cart]

I'm on board for this general direction, but we can't safely use labels to make a unique asset path here (because it won't be unique).

I've pushed a commit that uses "unique" (for some reasonable definition of unique) asset source names instead.

[alice-i-cecile]

This API makes sense to me now, and I think the use case is compelling.

[alice-i-cecile]

@NiklasEi let me know when you've seen these changes, and if you're on board with them. If you are, I'll press the big button and merge this for 0.12 :)

[NiklasEi]

@alice-i-cecile I saw them and it looks good to me 👍