Implement minimal asset saving by andriyDev · Pull Request #22622 · bevyengine/bevy

andriyDev · 2026-01-21T09:22:49Z

Objective

A step towards Bevy Asset Saving and Improvements #11216.

Solution

Allow users to build SavedAsset instances by building up their labeled assets. This can either take an existing handle + asset ref, or will create a handle for your asset ref.
Provide a function to correctly call the AssetSaver, and write out the correct meta file.

Some things I am leaving to future PRs

Making it easier to access subassets in an AssetSaver.
Making a nicer API for asset saving (e.g., registering asset savers and looking up the appropriate saver for type ID + extension).

Weird implementation details

I needed to create my own Cow-like type (which I named Moo), since I needed to store just a ref or owned hashmap. I wrote a lengthy comment explaining why it's needed (TL;DR variance is complicated, Cow doesn't work). Note: it's possible we could just use CowArc instead, but we never need to clone the map so this seems like overkill. Also having a nice place to explain the variance problems is useful here.
For the builder, I needed to add an extra lifetime to add_labeled_asset_with_*<'b: 'a>, since otherwise, the CowArc gets coerced to 'static which means the lifetime of the subasset needs to be 'static, which practically makes this unusable. By adding a second lifetime dedicated to the CowArc,

Testing

Created a new example: this allows you to make a small "scene" of boxes, and save and load it to your heart's content!
Added a couple simple tests.

crates/bevy_asset/src/saver.rs

greeble-dev

I'm clicking approve as the PR does what it says and is backed up by tests and an example. I left a few minor suggestions.

I do have some concerns with the overall direction:

The code is significantly complicated by having to support handles and avoid copies. I'm not sure this complexity is worth it right now.
We're not dogfooding since the engine doesn't have a complicated saver built-in - the example code is fairly contrived. This makes it hard to predict if the API will work well.
My guess is that the subtleties around sub-assets and when to use add_labeled_asset_with_new_handle versus add_labeled_asset_with_existing_handle will be challenging for users.

I don't think these concerns are blocking, but maybe they deserve more discussion. And as ever, there's the possibility that assets-as-entities ends up remaking the whole thing.

greeble-dev · 2026-01-26T12:32:20Z

crates/bevy_asset/src/saver.rs

-        CowArc<'static, str>: Borrow<Q>,
-        Q: ?Sized + Hash + Eq,
-    {
+    pub fn get_labeled<B: Asset>(&self, label: &str) -> Option<SavedAsset<'a, '_, B>> {


This change means get_labeled can no longer be called directly with a CowArc<str>. Only a minor regression, but is it necessary? I guess the lifetimes might be tricky.

We now accept impl AsRef<str>, so this should work now I think.

greeble-dev · 2026-01-26T14:34:08Z

examples/asset/asset_saving.rs

@@ -0,0 +1,372 @@
+//! This example demonstrates how to save assets.


Maybe worth calling the example asset_saving_subassets.rs? Or subasset_saving.rs? It's a fairly complicated example, so this would leave space for a simpler example that doesn't involve sub-assets.

I'm okay with this for now, and then we can rename once a simpler example is prepared.

I can make a followup PR to split this into a simple saving example and a complex saving example.

I primarily focuses on the complex case since it's the one that this PR actually enables (the simple case you could previously do anyway).

greeble-dev · 2026-01-26T14:43:59Z

release-content/release-notes/asset_saving.md

+
+## 1. Building the `SavedAsset`
+
+To build the `SavedAsset`, either use `SavedAsset::from_asset`, or `SavedAssetBuilder`. For example:


I think this could do with a brief example of SavedAsset::from_asset that's separate from the SavedAssetBuilder example? Would make clear that SavedAssetBuilder is only needed for more complicated cases.

Added a more simple example just for SavedAsset::from_asset!

greeble-dev · 2026-01-26T15:21:56Z

crates/bevy_asset/src/saver.rs

+                // NOTE: We can't handle embedded dependencies in any way, since we need to write to
+                // another file to do so.
+                embedded_dependencies: vec![],
+            };


Suggested change

// NOTE: We can't handle embedded dependencies in any way, since we need to write to

// another file to do so.

embedded_dependencies: vec![],

};

embedded_dependencies: vec![],

};

// NOTE: We can't handle embedded dependencies in any way, since we need to write to

// another file to do so.

assert!(asset.embedded_dependencies.is_empty());

Assert seems safer if this is only used in tests.

greeble-dev · 2026-01-26T17:41:31Z

.gitignore

 .web-asset-cache
 examples/large_scenes/bistro/assets/*
 examples/large_scenes/caldera_hotel/assets/*
+examples/asset/saved_assets


I'm not sure what this is for? The example asset+meta is already tracked by git, and the example doesn't add new ones.

Woops yup my jumping around my branch made me add these files accidentally.

I've gone and deleted them from the original commit so they remain untracked.

alice-i-cecile

Happy to see progress here. I think this is a sensible design, and the code is clear enough to be maintainable. I would also prefer a simpler example (keeping this one for a more advanced one), but I'm not going to block on that.

alice-i-cecile · 2026-02-02T21:38:50Z

release-content/release-notes/asset_saving.md

+Note that since these assets are borrowed, building the `SavedAsset` should happen in the same async
+task as the next step.
+
+## 2. Calling `save_using_saver`


Can we simply rename this to save? Are there plans for a simpler API that don't require an explicit saver?

If not, we should definitely use the simpler name for the standard path.

In the future, I think we will likely have a separate save function that looks up the appropriate saver for you (the same way load looks up the loader). This minimal version still seems reasonable to support in that world anyway, so it's not clear to me we will delete this function.

…tch `AssetLoader`.

…methods.

…otes.

andriyDev force-pushed the asset-saving-v0 branch from b8953aa to 6f9d0e6 Compare January 21, 2026 09:24

Rewrite SavedAsset to borrow each asset individually.

2774b67

andriyDev force-pushed the asset-saving-v0 branch 3 times, most recently from 1d215e4 to 77a14a9 Compare January 21, 2026 09:30

andriyDev added this to the 0.19 milestone Jan 21, 2026

andriyDev requested a review from kristoff3r January 21, 2026 10:10

alice-i-cecile added the M-Release-Note Work that should be called out in the blog due to impact label Jan 21, 2026

andriyDev requested a review from greeble-dev January 22, 2026 16:54

IronGremlin reviewed Jan 22, 2026

View reviewed changes

crates/bevy_asset/src/saver.rs Show resolved Hide resolved

greeble-dev approved these changes Jan 26, 2026

View reviewed changes

andriyDev added S-Waiting-on-Author The author needs to make changes or address concerns before this can be merged and removed S-Needs-Review Needs reviewer attention (from anyone!) to move forward labels Feb 2, 2026

alice-i-cecile approved these changes Feb 2, 2026

View reviewed changes

alice-i-cecile added S-Ready-For-Final-Review This PR has been approved by the community. It's ready for a maintainer to consider merging it and removed S-Waiting-on-Author The author needs to make changes or address concerns before this can be merged labels Feb 2, 2026

alice-i-cecile reviewed Feb 2, 2026

View reviewed changes

alice-i-cecile added S-Waiting-on-Author The author needs to make changes or address concerns before this can be merged and removed S-Ready-For-Final-Review This PR has been approved by the community. It's ready for a maintainer to consider merging it labels Feb 2, 2026

andriyDev added 7 commits February 2, 2026 23:20

Implement asset saving.

fea6174

Switch AssetSaver to use Into<BevyError> for the error type to ma…

9fe95c1

…tch `AssetLoader`.

Create an example for demonstrating how to do asset saving.

f54c833

Allow SavedAssetBuilder::labeled_assets to store owned strings.

8658621

Add migration guide and release notes.

5f644ab

Add must_use on add_labeled_asset_with_new_handle*.

0088b59

Improve the documentation of the add_labeled_asset_with_new_handle …

00346b1

…methods.

andriyDev added 3 commits February 2, 2026 23:20

Provide an example of using SavedAsset::from_asset in the release n…

d6cdc94

…otes.

Prevent embedded text in the CoolTextSaver for testing.

9960904

Make get_labeled accept any AsRef<str> to work with CowArc<str>.

65b770b

andriyDev force-pushed the asset-saving-v0 branch from 18da29b to 65b770b Compare February 3, 2026 07:41

andriyDev added S-Ready-For-Final-Review This PR has been approved by the community. It's ready for a maintainer to consider merging it and removed S-Waiting-on-Author The author needs to make changes or address concerns before this can be merged labels Feb 3, 2026

alice-i-cecile added this pull request to the merge queue Feb 4, 2026

Merged via the queue into bevyengine:main with commit 5d9a10c Feb 4, 2026
44 checks passed

		@@ -0,0 +1,372 @@
		//! This example demonstrates how to save assets.


		## 1. Building the `SavedAsset`

		To build the `SavedAsset`, either use `SavedAsset::from_asset`, or `SavedAssetBuilder`. For example:

Uh oh!

Comments

Conversation

andriyDev commented Jan 21, 2026

Objective

Solution

Some things I am leaving to future PRs

Weird implementation details

Testing

Uh oh!

Uh oh!

greeble-dev left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

greeble-dev Jan 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alice-i-cecile left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

greeble-dev Jan 26, 2026 •

edited

Loading