Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Non-blocking load_untyped using a wrapper asset #10198

Merged
merged 5 commits into from
Oct 26, 2023

Conversation

NiklasEi
Copy link
Member

@NiklasEi NiklasEi commented Oct 19, 2023

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.

@NiklasEi NiklasEi added C-Feature A new feature, making something new possible A-Assets Load files from disk to use for things like images, models, and sounds labels Oct 19, 2023
@NiklasEi NiklasEi marked this pull request as ready for review October 21, 2023 01:09
@cart cart added this to the 0.12 milestone Oct 21, 2023
.infos
.write()
.get_or_create_path_handle::<LoadedUntypedAsset>(
path.clone().with_label("untyped"),
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just pushed a fix!

Copy link
Member

@cart cart left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

@alice-i-cecile alice-i-cecile left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@alice-i-cecile alice-i-cecile added the S-Ready-For-Final-Review This PR has been approved by the community. It's ready for a maintainer to consider merging it label Oct 26, 2023
@alice-i-cecile
Copy link
Member

@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
Copy link
Member Author

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

@cart cart enabled auto-merge October 26, 2023 22:12
@cart cart added this pull request to the merge queue Oct 26, 2023
Merged via the queue into bevyengine:main with commit 77309ba Oct 26, 2023
22 checks passed
ameknite pushed a commit to ameknite/bevy that referenced this pull request Nov 6, 2023
# 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:
```rust
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
`LoadedUntypedAsset`s field `handle`.

---------

Co-authored-by: Carter Anderson <mcanders1@gmail.com>
rdrpenguin04 pushed a commit to rdrpenguin04/bevy that referenced this pull request Jan 9, 2024
# 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:
```rust
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
`LoadedUntypedAsset`s field `handle`.

---------

Co-authored-by: Carter Anderson <mcanders1@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-Assets Load files from disk to use for things like images, models, and sounds C-Feature A new feature, making something new possible S-Ready-For-Final-Review This PR has been approved by the community. It's ready for a maintainer to consider merging it
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants