Repository navigation
Assets as Entities #11266
Description
What problem does this solve or what need does it fill?
The current asset system is stored in a single resource Assets. This means we need a bespoke ID system for assets, events to report changes to assets, different patterns for adding/removing assets, etc.
What solution would you like?
We can unify assets more tightly with the ECS by turning assets into entities.
- Each asset would be an entity holding an
Asset<MyAsset>component. - AssetIds would just be
Entitys (or a wrapper aroundEntity). - Change detection for assets would just be regular component change detection.
- Looking up an asset would just be a regular entity lookup.
- Asset lifetimes can be held in an
AssetLifetimecomponent. Handles would refer to the same reference count and a system would check for assets with a ref count of 0 to despawn that entity.
Possible issues
- Adding assets is no longer immediate. It requires calling
apply_deferred(although at least we can get the entity ID immediately so this is not too bad of an issue). - There's nothing stopping users from making "weird" asset entities. For example, one entity with two different asset types. When should the asset be cleaned up? Technically this is fine since as long as you hold handles to the same
AssetLifetimeref count, it doesn't matter the type. Treating the same entity as a mesh and an image would just be 2 references. - Users can add asset entities without the corresponding systems to manage them. Today, since pretty much all the handling must go through the
Assetsresource, it's fairly hard to have unmanaged assets. Does this matter? For example, you can do weird things without the right systems with events (never clearing, for example). This would just be more of that.
What alternative(s) have you considered?
Keep the system the same. The resource approach is very workable and is pretty nice to use. There are great guard rails (the types are very strong) and it's fairly hard to "break" it.
Additional context
This isn't originally my idea, I'm not sure whose it is though. I just remember hearing about this on Discord and wanted to document this.
Reacted by Mark Moissette, Alice Cecile, NyxAlexandra, Malek, te-king, Torstein Grindvik, Pete Hayman, Kristoffer Søholm, musjj, Eagster and 3 more
Activity
alice-i-cecile commentedon Jan 9, 2024
For historical context, this was (mostly) originally proposed by @cart, and detailed a bit in #8624.
clarfonthey commentedon Oct 4, 2024
Been poking around trying to think of ways to improve
Image, and it really feels like components are the way to go, since the different layers of configuration on top of how the image is drawn can just be components instead of all being part of the image asset.I'm not really sure where we are for accomplishing this, though. It appears that a decent chunk of the mentioned issues are solved now that we have required components, but I'm not entirely sure.
ElliottjPierce commentedon Jan 6, 2025
I know this isn't possible yet, but I have been thinking about this myself and wanted to quickly highlight some things that this would make feasible. They mostly center around Cart's point: "Extensible. Users can add arbitrary component data to assets."
Shiny Possibility 1: For item systems and other similar systems, item data could be kept modular. Storing health, damage, price, element, model, etc in components is much much more elegant that in a monolithic asset struct. This is especially true if modders want to add their own data to an item.
Shiny Possibility 2: Data could be added to assets as they are spawned/added. For example, when a new mesh is added, an AABB component could be attached to it. This could be much faster than generating AABBs when a Mesh is inserted into an entity (as I believe is done now). Many similar performance advantages may exist.
andriyDev commentedon Jan 7, 2025
One thing that worries me about that first idea (@ElliottjPierce) is that it really restricts what we can do with assets in async contexts. My PR #15813 would allow us to use assets in async, but having all the asset data be just directly on an entity would basically make that impossible. I don't think "monolothic" assets are bad since that's kinda how they are loaded today.
I do think adding computed data to assets would be pretty cool though!
alice-i-cecile commentedon Jan 12, 2025
I've written a write-up about the principles I think we should follow when doing *-as-entities refactors like this: https://hackmd.io/@bevy/SypE1qZP1l
ElliottjPierce commentedon Jan 13, 2025
That is well written and I completely agree after reading it.
I hadn't thought about async implications. I think you're right that async should take priority here; that's kinda important.
However, I don't love the idea of monolithic assets still. My primary concern is being able to add arbitrary data (component-like) to arbitrary assets (entity-like). For example, if item types were represented as monolithic assets, and a modder wanted to add a trading mechanic, they should be able to attach price data to assets that represent items. This would be super ergonomic with ECS, but there may be better ways of doing this.
Async should be the higher priority for assets, but if this functionality could work alongside it that would be awesome. I'm no asset expert, so I trust ya'll's opinions. Just throwing it out there.
andriyDev commentedon Jun 12, 2025
I just stumbled upon #10549 - another case where assets-as-entities would help us!
Stop using `AssetId` in the `AssetServer` and use `AssetIndex` instea…
Stop using `AssetId` in the `AssetServer` and use `AssetIndex` instea…
andriyDev commentedon Jan 24, 2026
With #18670 merged, the last blocker (afaik) is gone! So I'd like to lay out my plan for assets as entities (some of this comes from suggestions for others, I'm compiling these ideas here, but I don't remember who exactly suggested each of these):
1. Create a generic entity-reference-counting utility.
This should essentially be an Arc/Weak with an entity ID. Dropping the Arc should send a message or something to despawn the entity. Making this generic would be nice so we don't need to include this as part of assets-as-entities. Most of the behavior here doesn't need to care about anything asset specific.
I initially thought we'd need an asset-specific solution, since currently asset handles allow you to "recover" an asset if you load an asset after its handles have been dropped but before the asset actually gets dropped. After #22261 (comment), we can probably just drop this idea, and say dropping the handle definitely drops the asset - users that depend on this will need to come up with a solution to keeping their handles alive.
2. Create an index of uuid -> entity.
This allows us to continue supporting uuid handles. Ideally you just add a Uuid component to an asset and it registers things with hooks.
We can also make this generic (for use outside of the asset system). One complexity here is that today "default handles" are done using a particular UUID - this UUID is the same for every asset type. This works because asset storage is partitioned by type ID. If we make a uuid -> entity map, we may also need to partition it by type ID (not necessarily, if we come up with an alternative for default handles).
This map also needs to hold an entity reference count, so that Uuid assets don't get despawned.
3. Assets as entities v0
This should be as naive a port as possible - don't try to support anything new, just take the existing semantics and convert them to an ECS form. For example, we should stick to monolithic assets for this version.
This is gonna be a big PR, but hopefully the semantics being so similar will make it smooth to get merged fairly quickly. Attempting to solve problems in the same PR or getting every wishlist feature is going to blow up review time, and leave us with a git history where every bug gets bisected to "assets as entities". See the rest of the work I've written below for things I don't want in this PR.
So concretely, we'll take any data in
Assetsand represent it as components. We will also need to rewrite how we remove unused assets (some of this will look like #22261 I think, but without the multiple handles part), and of course how we allocate new handles.4. Non-monolithic assets (assets as entities v1)
I think we should probably just do this. I'm sad to give up on accessing assets in async (without blocking the ECS), but a lot of folks want to have multiple components for their asset data, and I didn't think anything like #15813 is happening.
This involves reworking our asset loader API to allow you to specify a bunch of components to attach to the entity. I haven't done much exploratory work here. Maybe
Assetshould just be a marker component? Also maybe if on reload the asset loader produces a different set of components, we should delete any previously added components??There's a ton of design decisions here (exactly why it should be a follow-up).
5. Everything else
Here's a random list of changes I've thought about that can be their own PRs (I think):
LoadedUntypedHandleand replace it with a handle that starts with no type (that gets populated when loaded)AssetEvent(currently it's a message) with events, so users can handle changes with observers.This isn't a complete list (and I might add to it if I come up with anything else).
cart commentedon Feb 24, 2026
Closing in favor of the Assets as Entities Goal: #23094
clarfonthey commentedon Feb 24, 2026
Your link there doesn't work; you just end up linking to an anchor here instead of the actual issue.