Subasset Aliases

[andriyDev]

What problem does this solve or what need does it fill?

Today, every subasset must have exactly one label. While this is unambiguous, there are some cases where it would be much more convenient to have multiple ways to identify a subasset. For example, GLTF subassets are referenced by index (e.g., my.gltf#Mesh0/Primitive0). While these are unique, it can be difficult to know what is the correct index, as much editors use names for meshes. It would be nice to say something like my.gltf#MeshCharacterBody/Primitive0 or soemthing to that effect (where CharacterBody is the name of the mesh in the GLTF file).

What solution would you like?

We should allow AssetLoaders to provide aliases for a subasset, and for loading an asset to "resolve" into a particular asset.

What alternative(s) have you considered?

Figure out another way to "lookup" the correct subassets from GLTFs. This would likely mean hand-crafting a solution for each kind of asset that needs this feature.

Also, it would be nice if we could even extend this to regular assets. For example:

let handle = asset_server.register_alias::<Animation>("dance_animation");

let other_handle = asset_server.load::<Animation>("dance_animation");
assert_eq!(handle, other_handle);

let target_handle = asset_server.load::<Animation>("some/internal/file/path.gltf#Animation1337");
asset_server.set_alias(handle, target_handle);
// `other_handle` refers to `target_handle`s animation when it loads.

[andriyDev]

#16529 has discussion on this topic. I will attempt to summarize it here.

---

First, #16529 attempted to change the label for GLTF subassets to include the name if it were present. However it turns out names are not necessarily unique. This could make some subassets inaccessible (or if we choose to prefer indices if there are non-unique names), some assets will arbitrarily become indices. More importantly this would break existing users that depend on indices if any of their subassets are named.

The main difficulty is that starting to load an asset already allocates its ID (and I believe space for it). This means loading a subasset by its alias is not distinguishable from loading a separate subasset. When the asset is finally loaded, it's not clear which handle to associate it with. Duplicating the data is also not great since that can lead to memory issues.

Another alternative rests in #15813. We could clone the arc'd subasset into its aliases. However, this would mean these aliased subassets would need to be cloned to be mutated, and more worrying, mutating would cause the data in each subasset alias to be different (so before mutation both aliases point to the same data, but after mutation, one alias will point to the old version of the data, and the second alias will point to the new version of the data).

[andriyDev]

I have an idea for how to do this at the cost of performance only for users of aliases. Today, Assets stores a Vec of Entry, where Entry is either None to indicate that an asset has no live handles, or Some to indicate that there are live handles. This Some variant includes an optional value which holds the asset when it has been loaded. This inner Option could be replaced with:

enum ValueState<A: Asset> {
    Unloaded,
    Loaded(A),
    Alias(Handle<A>),
}

When an asset is loaded, it just tells the Assets resource that this is an alias and fills in the "canonical" handle. When you load an asset, it goes through the normal flow through AssetInfos::path_to_id. When you request to access an asset, if it sees an Alias(Handle<A>), it recursively looks up this handle until it finds an Unloaded or Loaded variant.

The first risk is if users somehow make a cycle. We can verify this when the asset is loaded, so I don't think this is a big deal. The second risk is the performance cost. Accessing an asset can now require several hops. However, existing users don't need to pay any cost - only if you stumble upon an alias do you need to hop.

[andriyDev]

Alright I took a stab at this and while I think it is possible, I am going to shelve this.

The first difficulty is that all the APIs need to be redesigned. For example, should Assets::remove remove the alias, or the asset? Should Assets::len return the number of assets, or the number of assets + aliases? Should iter return just asset references, or also aliases? A lot of these can be resolved with some hand-crafted enums, but it's cumbersome.

The more concerning problem (and why I decided to shelve it) is asset events. When an alias' asset gets modified, we really should signal to users that something has happened. For example, if you load a GLTF file and use an alias to one of its mesh primitives, and then you modify that mesh primitive, there needs to be some event that signals that the alias has been updated. This is similar to the problem of texture mutations not triggering a material to update (#15595). Solving this manually is a pain, since we now need to keep an index of the relationships of aliases. This would be perfect as an observer, so we could just add an observer when an alias is created to listen for updates. Therefore, I think we should wait for #11266.