Proposal: Prefer Typed And Structured Names

[greeble-dev]

This is a proposal to nudge Bevy towards typed and structured names, making it less reliant on the Name component. The goal is to keep Name as an opt-in system for users, while avoiding the problems of Name as an ad-hoc API and debug tool.

The gist of the proposal is:

• Keep Name as it is.
• Add a new debug-only name component.
• In engine code, prefer to create debug-only names or typed names - avoid using Name as an API.
• Explore more structured naming solutions that could work alongside Name components (e.g. tags).

Background

Most 2D/3D engines, file formats and DCCs have some concept of "entity" or "object" or "node". These things can often be assigned a name. Names can be represented by a human readable string, but beyond that each system has different rules:

• Names can be required or optional.
• Names can be arbitrary strings, or can be restricted to certain characters.
• Names can sometimes have a formal hierarchical structure.
  • Many DCCs have a single or multi level namespace:name convention (e.g. player_character:head_joint).
  • An Unreal object's path name might be path/to/asset:object1.subobject2.foo, where foo is its short name.
• Names can have rules around uniqueness.
  • Many DCCs require unique full names within a scene.
    • Maya is a notable exception - it allows duplicate names except among siblings.
  • glTF allows duplicates everywhere.
• User control over names can vary.
  • Users might be able to set the whole name or part of it (e.g. only the short part of an Unreal object name is directly settable).
  • Sometimes names are programmatically generated and can't be controlled by users (e.g. the part of an Unreal full name that comes from the file name).

Problems

Names can be a convenient and powerful tool for for identifying things. When an engine creates them by default they're a standard way to reference and debug anything. When created by the user they're a flexible way to connect all kinds of things together.

But there's a price - in some situations names can be unreliable and inefficient, and that's because they're convenient and powerful.

• Names are a kind of untyped relationship/API.
  • The user often expects a name to identity a particular thing, but that intent isn't formally expressed in the name itself or structurally enforced.
  • This can be fine on a small scale and when the user controls their names.
  • But it can become a problem at larger scales, or if names are set by the engine or plugins that the user doesn't control.
  • Since names are untyped, it's difficult to work out where names are used and who controls them.
    • So when an engine/plugin intentionally uses them as an API, it's hard to tell what changing the API will do.
  • A particularly insidious case is when an engine/plugin assigns names for debugging or internal reasons, but users treat them as an API (Hyrum's Law).
    • This means any change to the naming behaviour can become an API break (e.g. Examples that modify gltf materials are broken #19322).
• Names are not expressive enough for many cases
  • Things can have multiple identities and relationships.
  • If an engine treats them as the primary form of identity, users will sometimes work around this by making names informally structured.
  • But that can be a nasty source of bugs.
    • The classic example would having player_1 and player_2 and doing let is_player = object.name.starts_with("player_").
    • This breaks when a scene has an object called player_spawn_point.
• Performance can be a major problem.
  • Names have to be stored in case users depend on them, even though most might be unused or only for debugging.
  • String compares are usually less efficient than integer IDs.
    • String interning and hashing can help, but only so much.
  • Informally structured names can means lots of string formatting and parsing.

Names are not inherently bad. But they can become a problem when systems rely on or encourage names as the primary form of identification.

Alternatives

Many systems have more structured ways to identify things while still using human readable strings.

• Typed names
  • A string with an explicit type, e.g. Bevy's GltfMaterialName.
  • Things can have multiple names if the names are of different types.
• Flat tags
  • A unordered list of strings, e.g. O3DE's tags
  • Things can be found by matching on a subset of the tags.
  • A thing tagged with ["cat", "animal"] can be found by searching for "animal" or "cat OR dog".
• Hierarchical tags
  • An ordered list of strings, e.g. Unreal's Gameplay Tags.
  • A thing tagged with Animal.Mammal.Cat can be found by searching for Animal or Animal.Mammal or *.Cat.
• Debug-only names
  • A string that's not supposed to be used as an identifier - it's just a debug helper, e.g. Godot's Node::editor_description.
  • Debug only names might be disabled in non-debug builds.

Names In Bevy

Bevy entities are not required to have a name. They're usually identified by the Entity struct, which is an opaque ID.

Bevy does provide a generic Name component as an optional identifier. A Name is an arbitrary UTF-8 string stored in a Cow<'static, str>, plus a hash for fast equality. Each entity can only have a single Name component, and names are not required to be unique.

Name components are often used as a debugging tool - most inspectors will default to displaying them as the main way to identify entities. But there's nothing to stop users from programmatically identifying entities with Name components.

Bevy engine code does not rely on Name components as a way of identifying entities (except for debugging and examples). But there are some cases where the engine automatically adds them:

• bevy_input adds a name to gamepad entities (gamepad_connection_system).
• bevy_gltf adds a name to most of its entities.
  • Nodes and lights get their glTF name.
  • Mesh primitives are named as "mesh.material" (see primitive_name).
  • As well as Name, bevy_gltf also uses typed name components like GltfMaterialName.

The current bevy_gltf use of Name as API has caused at least one bug with examples:

1. #19287 changed mesh primitive names from "mesh.mesh_index" to the current "mesh.material", which is nicer for debugging.
2. This broke several examples: #19322.
3. The fix was to add a typed GltfMeshName component that behaved like the old name (#19331).

Names In bevy_animation

I've seen a few comments along the lines of "bevy_animation relies on Name". This turns out to be untrue - skeleton joints from glTFs do get assigned a Name component (as do all glTF nodes), but bevy_animation doesn't use it directly.

To give some background, this section will go into entirely too much detail on skeletal animation and names - it's skippable if you want to get to the proposal.

Skeletal animation systems often rely on names to identify joints. A branch of the scene that's (usually) skinned to a mesh and animated as a unit is defined as a "skeleton". A simple character skeleton might look like this:

• torso
  • head
  • left_upperarm
    • left_forearm
      • left_hand
  • right_upperarm
    • etc.

Things within the skeleton are often required to have unique names, even when the system technically supports duplicate names. This is convenient for the user - a name will always resolve to a single joint within a skeleton. It's also common for names to be standardised across skeletons, so several different character skeletons might have different proportions but will always have a "head" bone. This allows sharing animations and other logic across multiple skeletons.

Bevy's animation system is unusual in that it doesn't define a skeleton - animations can be bound to any entity in the world. Animatable entities are identified by AnimationTargetId, which is a semi-opaque UUID. For glTF skeletal animations, the UUID is a hash of the joint's name and the names of all its ancestors within the glTF scene. So in the example skeleton, the id of head would be the hash of head and torso. This method means the AnimationTargetId will be unique within the glTF scene as long as there are no duplicate names among siblings. It also means that a different glTF with the same hierarchy will result in the same AnimationTargetId, so animations can be shared.

The glTF AnimationTargetId doesn't technically depend on entities having a Name component. The loader uses the Name struct as temporary storage, but it could easily be replaced by String (proof of concept).

AnimationTargetId is powerful since it's less reliant on name uniqueness. But it can be inconvenient - the glTF AnimationTargetId requires looking at the hierarchy (example), where other animation systems would only need a single joint/attribute name. It could also be a problem when animations are shared but limited to a sub-branch of the skeleton hierarchy (e.g. a face animation's root might be the head rather than the body root, leading to a different AnimationTargetId).

Proposal

Keep Name As It Is

Even though there's many ways to misuse it, Name can be the best choice for some cases. A game jam entry or a solo dev might not care about making their code scalable and reliable and performant - they can get away with if name.starts_with("player") just fine. So having a built-in and reasonably performant name component is a good thing.

Add A Debug-Only Name Component

The engine should have a component that's similar to Name, but for debugging only - it shouldn't be used as a programmatic identifier or API.

Accidentally using a debug name as an identifier will be discouraged by a limited interface, and user will have the option to compile it out. Inspectors and other debug tools should be changed to prefer this component over Name, or display them side by side.

I've had a crack at a proof of concept here: main...greeble-dev:bevy:debug-name-poc-zst

EDIT: Now a PR: #21509.

commands.spawn((DebugTag::new("player"), Transform::IDENTITY));

• The component is called DebugTag.
  • This name is infinitely bike-sheddable.
  • DebugName is taken by a similar struct in bevy_util.
• It's a Cow<'static, str>.
  • Same as Name but without the hash.
  • This is debatable. Could be String or other string internment options.
• If the debug_tag feature is not enabled, DebugTag becomes an empty struct.
  • This is very debatable.
    • Compiling it out completely would be safer and avoid allocating the component in the ECS.
    • But then the ergonomics around entity spawning and querying are rough - cases like the below would need ugly cfgs.
      • commands.spawn((DebugTag::new("example"), Transform::IDENTITY))
      • Query<(Entity, &DebugTag, Transform)>
    • Maybe there's a cleverer way, or maybe it should be a special ECS feature rather than a component.
  • DebugTag::new("example") is efficient - the "example" string is compiled out.
    • But more complicated cases like DebugTag::new(format!(...)) are not compiled out.
  • There's a debug_tag! macro that behaves like DebugTag::new but is guaranteed to compile out anything inside the macro.
    • Probably still fails for cases like let f = format!(...); let n = debug_name!(f).
• DebugTag only implements Debug.
  • No ToString, no Display, maybe not even Eq (controversial).
  • Basically, make it as hard as possible to accidentally use as an identifier.
  • When compiled out, Debug prints "[REDACTED]" (bike-sheddable)

Don't Create Names In Engine Code By Default

Engine code should never create Name components by default. The goal is that Name should be opt-in - any users who don't like it shouldn't have to worry about misuse creeping in.

The current uses of Name would be changed to typed names or DebugTag. This will be a bit annoying for users - they will have to track down uses of Name in their code. The blow could be softened by adding an option for glTF to generate Names as before.

Explore Alternatives

Name and DebugTag can exist alongside various alternatives:

• A basic typed string is trivial in Bevy.
  • It's just a struct MyString(String) component.
  • But they could be more efficient if backed by string interning.
• Basic flat tags and hierarchical tags are fairly easy.
  • But would really benefit from an implementation that can optimise lookups.
  • Making them first-party might have ecosystem benefits.
    • A third-party behaviour tree crate can hook tags into queries and have some confidence that other third-party crates will integrate with them.

Objection!

Wouldn't it be better to let users opt-out if they don't want Name components? Why make the simple case harder?

If the engine encourages using Name everywhere then in practice opt-out will become difficult. It'll be too tempting for the engine and third party crates to start relying on them. So that opt-out would become "well... you can try, but these crates you're using might randomly break".

Isn't this bad for inspectors and editors? What will they show instead of a name?

An engine that assigns names to everything does simplify the job of editors and inspectors - the name is usually the best thing to show. Object oriented engines have an obvious solution - use the class name instead. But Bevy is too flexible for that.

Maybe the solution is to slap DebugTags on everything? That could work... but it's annoying for users to do on their own entities, and might stress performance in development builds. Maybe it could be an opt-in.

Another option is heuristics that try to find a sensible description based on an entity's components - e.g. an entity with a Mesh3d and a SkinnedMesh can be usefully described by format!("SkinnedMesh:{:?}", mesh.handle). Plugins could register heuristics, and the engine expose a standard way for inspectors to use them. This could also tie into linting heuristics, like warning if an entity has a Mesh3d but no material component.

Don't typed names like GltfMeshMesh increase Bevy's coupling to glTF?

Yes. I don't have a great answer to this. Two options:

1. Add a more generic MeshName and MaterialName in bevy_mesh and bevy_material. These can be reused by all loaders.
2. Add a glTF loader option to output Name like before, defaulting to off.

Summary

1. Name should be strictly an opt-in for the user. The engine can provide it, and BSN and the editor may encourage it through ergonomics - but the user decides, and in the long-term they should also have the option of more structured approaches (hierarchical/flat tags, typed names).
2. If the engine automatically creates names then they must be typed names. The engine should never use Name as an ad-hoc API.
3. There should be a debug-only name component that can be compiled out. The engine can create them by default for convenience.

[greeble-dev]

In case it's useful, here's some random notes I accumulated about names in other systems:

• Unity
  • GameplayObject has a name and a single tag.
• Godot
  • Nodes have a name and an editor_description.
  • Names are non-unique, except siblings: https://docs.godotengine.org/en/latest/classes/class_node.html#description
• Unreal
  • Lots of complicated rules since object names are hierarchical and parts map to classes, files etc.
  • Objects are required to have a name. The short name defaults to the class name plus a number.
  • Changing the name usually means creating a new object.
  • Mostly built on FName, a non-GC'd interned string (very efficient comparisons).
  • Short names are FName, full names are usually strings.
• FBX
  • Names are UTF-8 strings.
  • I couldn't find any rules around uniqueness, although the docs hint they can be non-unique (FbxScene::FindNodeByName "Get the first node with this name")
  • Has utilities for a single level "namespace:name" convention.
• glTF
  • Nodes have optional names, non-unique.
• Blender
  • Pretty sure it requires unique names but I can't find any documentation.
• Maya
  • Non-unique names, except siblings: https://help.autodesk.com/view/MAYAUL/2026/ENU/?guid=GUID-23889AB4-8BA2-4157-876A-A929E4313913
  • Illegal name rules: https://help.autodesk.com/view/MAYAUL/2026/ENU/?guid=GUID-2D9A00AB-05FD-486B-A510-22C7F02FC5DE
• Max
  • Probably unique names + namespaces. Not verified.
• Motionbuilder
  • Probably unique names + single level namespace. Not verified.

[ChristopherBiscardi]

re: blender uniqueness. The default Blender cube scenes has two entities named Cube: The Object entity and the Mesh/Material entity. As far as I know, Blender doesn't not actually guarantee uniqueness (especially when using multiple blend file workflows) but does best-effort unique-per-type names within a single blend file.

[SanderMertens]

Prior art from Flecs, which is probably closer to Bevy than the other mentioned solutions:

• Hierarchical names
  • Must be unique amongst siblings, but can be the same across namespaces
  • Hierarchy is determined by ChildOf relationship
  • Scoped lookups (supports both world.lookup("parent::child") and parent.lookup("child"))
• Typed lookups
  • Entities can be associated with a type
  • Means an entity can be found both by doing world.entity<foo::bar>() and world.lookup("foo::bar")
• Annotations
  • Free form strings that can be associated with entities and don't have to be unique
  • Used for things like user friendly names, brief/detailed descriptions, debug color, link, icon, GUID