Configurable Asset Storage

[brianreavis]

This is an attempt at a minimally-invasive update to allow Asset types to define how they want to be stored within Res<Assets<A>>. This is like Arc-ed assets (#15813), but more generic and less invasive.

Showcase

/// Status quo (the default if `asset_storage` not set)
#[derive(Asset)]
#[asset_storage(StackAssetStorage)]
struct Mesh { ... }

/// Effectively https://github.com/bevyengine/bevy/pull/15813
#[derive(Asset)]
#[asset_storage(ArcedAssetStorage)]
struct Mesh { ... }

/// The asset is stored on the stack by default (like StackAssetStorage), but can transition
/// into an Arc<A> / Arc<RwLock<A>> so that it can be read or written to on background threads.
#[derive(Asset)]
#[asset_storage(HybridAssetStorage)]
struct Mesh { ... }

Comparison

• Arc-d assets #15813 - What’s different:

  • Fewer public API changes.
  • Customizable behavior on a per-asset-type basis.
  • Assets that are cheap to clone (e.g. materials) can remain un’Arc-ed as they are today by using the StackAssetStorage strategy. No need to pay for atomics.
  • RenderAsset takes AssetSnapshot<Self::SourceAsset> (a generic that derefences to &Self::SourceAsset) instead of Arc<Self::SourceAsset>. For ArcedAssetStorage and HybridAssetStorage, this is Arc<Self::SourceAsset>. For StackAssetStorage, this is effectively A.

• Asset locking #15359 - Similar concepts. Need to review this one in more detail to comment.

Work-in-Progress

This is more-or-less complete, though I want to clean up the documentation a little, review/cleanup the async approach in HybridStorageStrategy, and add a migration guide. Open to feedback!

[cart]

I'd personally prefer to hold off on asset storage changes until we've sorted out "assets as entities". I think we should try to reconcile that design with the "arc-ed assets" needs.

[brianreavis]

I see this as a potential stopgap before Assets as Entities - which I’m excited for, but seems quite a ways out. The status quo of cloning heavy images and meshes into the render world is a bit rough.

The goal here is to provide a stepping stone that doesn't rock the boat much. At best, it could inform assets as entities, and at worst, it could be yeeted w/o complication when building Assets as Entities¹.

Regarding the stepping stone comment, the storage abstractions here could potentially be used if assets end up as entities:

#[derive(Component)]
AssetComponent<A: Asset>(StoredAsset<A>) 

Footnotes

1. If it’d be helpful to delete HybridStorageStrategy that provides new async-specific APIs like get_arc and get_arc_rwlock to Res<Assets<A>>, I think that’d be fine. Assets could be arc-ed with ArcedStorageStrategy without the user knowing anything about the underlying implementation. ↩

[github-actions]

It looks like your PR has been selected for a highlight in the next release blog post, but you didn't provide a release note.

Please review the instructions for writing release notes, then expand or revise the content in the release notes directory to showcase your changes.