Assets as entities v0 by andriyDev · Pull Request #22939 · bevyengine/bevy

andriyDev · 2026-02-13T08:50:05Z

Objective

First version of Assets as Entities #11266.
Part of Assets as Entities #23094
This change tries to do the bare minimum to converting us to implementing assets as entities. There is plenty of followup work to do as documented in Assets as Entities #11266.

Solution

Remove the Assets resource.
Turn AssetHandleProvider into a resource that can create any kind of handle.
Create an AssetCommands system param that spawns an entity and creates a handle for it.
Make AssetServer hold a RemoveAllocator and remote-allocate an entity when loading assets.
Create a system to listen for handle drop events and despawn the entity.
Create Assets and AssetsMut system params to replicate the old Assets API.

I've done my best to keep this PR focused on the bare minimum for assets as entities. This also means I've had to do some weird back-porting. For example, I've needed to create a type ID to "sender" map to be able to send the appropriate AssetEvent::Unused when despawning an asset. In the future, this should be replaced by just an event, and then we don't need the type ID at all.

Some features we get for free:

Always strong: handles are now always strong in essence! UUID handles are now just looked up just before accessing the asset data, but this lookup map stores the asset handle to the actual entity. So assigning a handle to a UUID essentially just treats that UUID as a permanent reference.
Fixes Dropping a handle from Assets::get_strong_handle has different behaviour to one from AssetServer::load. #20651: there's now no difference between handles created from the asset server or Assets. This also simplifies our handle dropping stuff.
We can load UUID assets now by loading an asset and then assigning that handle to a UUID in the AssetUuidMap! Maybe no one will use this, but it's cool we can do this now!

Some concerns with this feature/implementation.

We can no longer "revive" an asset once its handles are dropped. Previously, if all handles for an asset are dropped, but you call AssetServer::load or Assets::get_strong_handle for that asset in the same frame, the asset won't be dropped and you will now have new handles to that asset. Based on discussion in Fix handles being split by asset_server_managed. #22261 (comment), it seems we are ok with that. This could be something to bring back in the future.
We can no longer access assets mutably after adding them in the same system. Since assets need to be spawned in order to query them, and spawning (in a normal system) is deferred, we can't really do this. I think this is just a permanent limitation.
Systems can now reasonably have two Commands params: one Commands and another AssetCommands. Unfortunately these are applied in param order, not the order that commands are enqueued. So if the order is Commands then AssetCommands, and if a user spawns an asset through AssetCommands, then enqueue a command that uses that entity, the entity will not have been spawned yet! This is discussed more in Shared State for System Param #22885. It's probably not a big deal, but if we care about removing this footrake, we can solve Shared State for System Param #22885.
AssetServer::load returns a Handle::Entity which is a remote-allocated entity. It only gets actually allocated during handle_internal_asset_events in PreUpdate. I'm not entirely sure what the behavior is here with every feature: I assume that trying to access this entity (e.g., through World::get_entity_mut) before it's actually allocated will return an error (or for panicking APIs, panic). This could be future work: we could split AssetServer into AssetServer SystemParam (which would allow us to not remote-allocate the entity), and RemoteAssetServer (which would remote-allocate the entity).
I've had to re-implement AssetEvent and the implementation is kind of rough. UUID handles in particular are not the most reliable. Changing which asset entity a UUID points to may break things - however this API wasn't even possible before so it's unlikely people will use it. In addition, we expect to delete AssetEvent in the future and replace it with change detection / observers. So this fix is duct tape, but that's ok.
You can no longer add assets with things that impl Into<A>. I've done this since we now have untyped AssetCommands::spawn_asset and world.spawn_asset: we can't deduce the type of A from this. So in many cases, we'd need to explicitly specify the asset type which seems silly especially when you do asset_commands.spawn_asset::<StandardMaterial>(StandardMaterial { .. }). This has the effect that things like Cuboid need to be converted into a Mesh, either through .into() or Mesh::from.

Testing

I ran a handful of examples and they still seem to work! I tested the solari example also which tests both the changes made to solari, and also the changes made to the text pipelines (since that example contains rendered text). The testbed_ui examples also showed how necessary (for the time being) AssetEvents for UUID assets are.
Asset tests all pass.

github-actions · 2026-02-14T01:45:59Z

Your PR caused a change in the graphical output of an example or rendering test. This might be intentional, but it could also mean that something broke!
You can review it at https://pixel-eagle.com/project/B04F67C0-C054-4A6F-92EC-F599FEC2FD1D?filter=PR-22939

If it's expected, please add the M-Deliberate-Rendering-Change label.

If this change seems unrelated to your PR, you can consider updating your PR to target the latest main branch, either by rebasing or merging main into it.

github-actions · 2026-02-14T01:50:57Z

Your PR caused a change in the graphical output of an example or rendering test. This might be intentional, but it could also mean that something broke!
You can review it at https://pixel-eagle.com/project/B04F67C0-C054-4A6F-92EC-F599FEC2FD1D?filter=PR-22939

If it's expected, please add the M-Deliberate-Rendering-Change label.

If this change seems unrelated to your PR, you can consider updating your PR to target the latest main branch, either by rebasing or merging main into it.

github-actions · 2026-02-14T03:22:01Z

Your PR caused a change in the graphical output of an example or rendering test. This might be intentional, but it could also mean that something broke!
You can review it at https://pixel-eagle.com/project/B04F67C0-C054-4A6F-92EC-F599FEC2FD1D?filter=PR-22939

If it's expected, please add the M-Deliberate-Rendering-Change label.

If this change seems unrelated to your PR, you can consider updating your PR to target the latest main branch, either by rebasing or merging main into it.

github-actions · 2026-02-14T06:40:56Z

Your PR caused a change in the graphical output of an example or rendering test. This might be intentional, but it could also mean that something broke!
You can review it at https://pixel-eagle.com/project/B04F67C0-C054-4A6F-92EC-F599FEC2FD1D?filter=PR-22939

If it's expected, please add the M-Deliberate-Rendering-Change label.

If this change seems unrelated to your PR, you can consider updating your PR to target the latest main branch, either by rebasing or merging main into it.

github-actions · 2026-02-14T06:56:10Z

Your PR caused a change in the graphical output of an example or rendering test. This might be intentional, but it could also mean that something broke!
You can review it at https://pixel-eagle.com/project/B04F67C0-C054-4A6F-92EC-F599FEC2FD1D?filter=PR-22939

If it's expected, please add the M-Deliberate-Rendering-Change label.

If this change seems unrelated to your PR, you can consider updating your PR to target the latest main branch, either by rebasing or merging main into it.

github-actions · 2026-02-14T07:08:52Z

Your PR caused a change in the graphical output of an example or rendering test. This might be intentional, but it could also mean that something broke!
You can review it at https://pixel-eagle.com/project/B04F67C0-C054-4A6F-92EC-F599FEC2FD1D?filter=PR-22939

If it's expected, please add the M-Deliberate-Rendering-Change label.

If this change seems unrelated to your PR, you can consider updating your PR to target the latest main branch, either by rebasing or merging main into it.

github-actions · 2026-02-14T07:15:52Z

Your PR caused a change in the graphical output of an example or rendering test. This might be intentional, but it could also mean that something broke!
You can review it at https://pixel-eagle.com/project/B04F67C0-C054-4A6F-92EC-F599FEC2FD1D?filter=PR-22939

If it's expected, please add the M-Deliberate-Rendering-Change label.

If this change seems unrelated to your PR, you can consider updating your PR to target the latest main branch, either by rebasing or merging main into it.

github-actions · 2026-02-14T07:27:06Z

Your PR caused a change in the graphical output of an example or rendering test. This might be intentional, but it could also mean that something broke!
You can review it at https://pixel-eagle.com/project/B04F67C0-C054-4A6F-92EC-F599FEC2FD1D?filter=PR-22939

If it's expected, please add the M-Deliberate-Rendering-Change label.

If this change seems unrelated to your PR, you can consider updating your PR to target the latest main branch, either by rebasing or merging main into it.

crates/bevy_asset/src/uuid_map.rs

Trashtalk217

This review was kinda pushed to the back of my queue, so I'm sorry if it's late. I have two things I'd like to see addressed:

Use Mesh::from, over .into() as it makes debugging better
Eventually merge AssetCommands and Commands. I think it's technically possible, and the API is workable. Just not in this PR.

Trashtalk217 · 2026-02-20T22:20:07Z

examples/large_scenes/mipmap_generator/src/lib.rs

            Some(task_data) => {
                if let Some(mut image) = images.get_mut(image_h) {
-                    *image = task_data.image;
+                    ***image = task_data.image;


Triple Deref is a bit cursed.

Fixed this by manually implementing Deref/DerefMut and DetectChanges/DetectChangesMut to point directly to the inner A! Much better! This comment made me realize I could do that lol

crates/bevy_asset/src/lib.rs

Trashtalk217 · 2026-02-21T14:49:18Z

crates/bevy_asset/src/lib.rs

+
        let embedded = EmbeddedAssetRegistry::default();
+
+        let handle_provider = app.world().resource::<AssetHandleProvider>().clone();


What does this do? What does it replace?

Previously, each Assets resource would have its own handle provider, since each type had its own storage.

Now that we have one storage (the World), we need a shared handle provider that all assets use.

Put another way, previously we were initializing a handle provider per asset type in init_asset (through the Assets constructor). Now since our storage is shared, we don't need a handle provider per-type, we need one global handle provider.

As for why we need to clone here, it's because the AssetServer needs to be able to create handles remotely. Previously in init_asset we registered the asset type to the AssetServer, which would clone the type's handle provider.

Trashtalk217 · 2026-02-21T14:49:53Z

crates/bevy_asset/src/lib.rs

        let embedded = EmbeddedAssetRegistry::default();
+
+        let handle_provider = app.world().resource::<AssetHandleProvider>().clone();
+        let uuid_map = app.world().resource::<AssetUuidMap>().clone();


Same question.

Previously, the Assets resource stored a mapping from UUID to Asset. When you lookup a UUID handle, it would go to the Assets resource, go into the UUID storage, lookup the UUID, and give you the asset.

Now, we have the AssetUuidMap which stores a mapping from UUID to EntityHandle. So now when you lookup a UUID handle, it first goes to the AssetUuidMap, finds the EntityHandle, then lookups the Entity, and gives you the asset.

As for why we need to clone here, it's because the AssetServer needs an instance internally to resolve some handles.

crates/bevy_asset/src/uuid_map.rs

Trashtalk217 · 2026-02-21T20:04:14Z

crates/bevy_asset/src/handle.rs

-    pub(crate) drop_receiver: Receiver<DropEvent>,
-    pub(crate) type_id: TypeId,
+#[derive(Component)]
+pub struct AssetSelfHandle(pub(crate) Weak<StrongHandle>);


Some docs would be nice here.

Done! This definitely needed some docs haha.

…ut`.

…etCommands).

github-actions · 2026-04-08T05:14:21Z

Your PR caused a change in the graphical output of an example or rendering test. This might be intentional, but it could also mean that something broke!
You can review it at https://pixel-eagle.com/project/B04F67C0-C054-4A6F-92EC-F599FEC2FD1D?filter=PR-22939

If it's expected, please add the M-Deliberate-Rendering-Change label.

If this change seems unrelated to your PR, you can consider updating your PR to target the latest main branch, either by rebasing or merging main into it.

… Mut.

crates/bevy_asset/src/asset_changed.rs

                .unwrap();
            let mut asset = assets.get_mut(id).unwrap();
-            println!("setting new value for {}", asset.0);
+            println!("setting new value for {}", (*asset).0);


Co-authored-by: Trashtalk217

andriyDev

@Trashtalk217 I've replaced all the instances of .into() with *::from. It's possible I've missed one or two, but I literally went through all .into() instances lol.

As for combining Commands and AssetCommands, the regression that causes is way too big. Maybe if everything moves to BSN this won't be a problem? I'm extremely skeptical though.

crates/bevy_asset/src/lib.rs

andriyDev · 2026-04-09T23:48:09Z

crates/bevy_asset/src/lib.rs

        let embedded = EmbeddedAssetRegistry::default();
+
+        let handle_provider = app.world().resource::<AssetHandleProvider>().clone();
+        let uuid_map = app.world().resource::<AssetUuidMap>().clone();


Previously, the Assets resource stored a mapping from UUID to Asset. When you lookup a UUID handle, it would go to the Assets resource, go into the UUID storage, lookup the UUID, and give you the asset.

Now, we have the AssetUuidMap which stores a mapping from UUID to EntityHandle. So now when you lookup a UUID handle, it first goes to the AssetUuidMap, finds the EntityHandle, then lookups the Entity, and gives you the asset.

As for why we need to clone here, it's because the AssetServer needs an instance internally to resolve some handles.

andriyDev · 2026-04-09T23:52:31Z

crates/bevy_asset/src/lib.rs

+
        let embedded = EmbeddedAssetRegistry::default();
+
+        let handle_provider = app.world().resource::<AssetHandleProvider>().clone();


Previously, each Assets resource would have its own handle provider, since each type had its own storage.

Now that we have one storage (the World), we need a shared handle provider that all assets use.

Put another way, previously we were initializing a handle provider per asset type in init_asset (through the Assets constructor). Now since our storage is shared, we don't need a handle provider per-type, we need one global handle provider.

As for why we need to clone here, it's because the AssetServer needs to be able to create handles remotely. Previously in init_asset we registered the asset type to the AssetServer, which would clone the type's handle provider.

andriyDev · 2026-04-09T23:53:50Z

crates/bevy_asset/src/handle.rs

-    pub(crate) drop_receiver: Receiver<DropEvent>,
-    pub(crate) type_id: TypeId,
+#[derive(Component)]
+pub struct AssetSelfHandle(pub(crate) Weak<StrongHandle>);


Done! This definitely needed some docs haha.

Trashtalk217

For future reference. Merging Commands and AssetCommands would result in the following code:

commands.spawn((
  // BORROWING COMMANDS TWICE MUTABLY
  Mesh3d(commands.spawn_asset(Mesh::from(Cuboid::default()))),
));

which would break. However, I believe that we can do some API trick (probably with closures) that would allow this to be more manageble. Perhaps with some shortcuts for specific common operations. Also,

let a = Mesh3d(commands.spawn_asset(Mesh::from(Cuboid::default())));
commands.spawn(a);

Is really not that bad.

That all being said, given that there are also some technical hurdles and the current API is already a big improvement, I won't dwell on it any longer. As far as I'm concerned it's good to merge.

(After fixing merge conflicts)

github-project-automation bot added this to Assets Feb 13, 2026

github-project-automation bot moved this to Needs SME Triage in Assets Feb 13, 2026

andriyDev force-pushed the asset-v1 branch 7 times, most recently from 917c1a9 to 8448f5f Compare February 14, 2026 01:44

andriyDev force-pushed the asset-v1 branch from 8448f5f to cccb686 Compare February 14, 2026 03:12

andriyDev force-pushed the asset-v1 branch from 9318a79 to 0ff0d15 Compare February 14, 2026 06:47

andriyDev force-pushed the asset-v1 branch from 0ff0d15 to 6a11267 Compare February 14, 2026 06:59

andriyDev force-pushed the asset-v1 branch from 6a11267 to 28f2dd4 Compare February 14, 2026 07:09

andriyDev force-pushed the asset-v1 branch from 28f2dd4 to 8e176ec Compare February 14, 2026 07:20

github-advanced-security bot found potential problems Feb 14, 2026

View reviewed changes

crates/bevy_asset/src/uuid_map.rs Fixed Show fixed Hide fixed

andriyDev force-pushed the asset-v1 branch from 8e176ec to 03dc086 Compare February 14, 2026 08:17

Trashtalk217 suggested changes Apr 5, 2026

View reviewed changes

andriyDev added 2 commits April 6, 2026 21:24

Merge 'main' branch into asset-v1.

625eb3c

Fix up migration errors.

6735834

andriyDev force-pushed the asset-v1 branch from b3c6537 to a523cf1 Compare April 7, 2026 07:04

andriyDev added 5 commits April 7, 2026 00:38

Add some methods for making it easier to juggle Assets and `AssetsM…

ac0172f

…ut`.

Migrate bevy_scene to use assets-as-entities.

2df5388

Fix editable_text_system to use the deferred atlases.

7d3be54

Fix up bevy_gizmos_render to use assets-as-entities.

e0e5a77

Fix up any new/updated examples.

26bbc43

andriyDev force-pushed the asset-v1 branch from a523cf1 to 26bbc43 Compare April 7, 2026 07:40

andriyDev added 5 commits April 7, 2026 00:41

Merge 'main' branch into 'asset-v1'.

7ca3759

More random migrations.

1356f60

Fix accidentally ambiguous systems after adding Commands (through Ass…

29bbb97

…etCommands).

Merge 'main' branch into 'asset-v1'.

5d15b10

Fixup bevy_city.

29cff47

andriyDev force-pushed the asset-v1 branch from e9ca536 to 4937f0c Compare April 8, 2026 05:30

More migrations.

161fa3f

andriyDev force-pushed the asset-v1 branch from 4937f0c to 161fa3f Compare April 8, 2026 05:39

andriyDev added 3 commits April 8, 2026 20:41

Replace all .into() usages in spawn_asset to use A::from instead.

bd6fbe8

Implement Deref/DerefMut to deref into the asset type instead of into…

3be8021

… Mut.

Update accesses to AssetMut and remove triple derefs.

a8c86ea

github-advanced-security bot found potential problems Apr 9, 2026

View reviewed changes

andriyDev added 2 commits April 9, 2026 16:38

Add doc comments for AssetSelfHandle.

7227e12

Fixup doc comments in lib.rs.

a99ec9c

Co-authored-by: Trashtalk217

andriyDev commented Apr 9, 2026

View reviewed changes

Trashtalk217 approved these changes Apr 11, 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-Needs-Review Needs reviewer attention (from anyone!) to move forward labels Apr 11, 2026

alice-i-cecile added this to the 0.20 milestone Apr 11, 2026


		let embedded = EmbeddedAssetRegistry::default();

		let handle_provider = app.world().resource::<AssetHandleProvider>().clone();

Uh oh!

Conversation

andriyDev commented Feb 13, 2026 • edited by cart Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Objective

Solution

Testing

Uh oh!

github-actions bot commented Feb 14, 2026

Uh oh!

github-actions bot commented Feb 14, 2026

Uh oh!

github-actions bot commented Feb 14, 2026

Uh oh!

github-actions bot commented Feb 14, 2026

Uh oh!

github-actions bot commented Feb 14, 2026

Uh oh!

github-actions bot commented Feb 14, 2026

Uh oh!

github-actions bot commented Feb 14, 2026

Uh oh!

github-actions bot commented Feb 14, 2026

Uh oh!

Uh oh!

Trashtalk217 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!

Uh oh!

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!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Apr 8, 2026

Uh oh!

Check failure

Uh oh!

andriyDev left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

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!

Trashtalk217 left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

10 participants

andriyDev commented Feb 13, 2026 •

edited by cart

Loading