Entity path methods and bsn entity path resolving

_release-content/release-notes/entity_path_resolving.md

@@ -0,0 +1,37 @@
+---
+title: Feature name
+authors: ["@Freyja-moth"]
+pull_requests: [24018]
+---
+
+Paths can now be resolved to an entity and vice versa.
+These use the `Name` component, following the `ChildOf` relationship.
+
+```rust
+fn character(world: &mut World, player: Entity) -> Result {
+  let sword = world.get_entity_from_path("Items/Weapons/Sword", None)?;
+
+  world.entity_mut(player)
+    .add_one_related::<ItemOf>(sword);
+
+  // Relative paths can also be resolved 
+  let left_arm = world.get_entity_from_path("Arms/Left", Some(player))?; 
+
+  // You can even use custom relationships.
+  let apple = world.get_entity_from_relationship_path::<ItemOf>("Player/Satchel/Apple", None)?;
+
+  Ok(())
+}
+```
+
+With this a new variant has been added to `EntityTemplate` so that paths can be resolved in scenes
+
+```rust
+fn player() -> impl Scene {
+  bsn! {
+    #Player
+    Player
+    Wielding("Items/Weapons/Sword")
+  }
+}
+```

crates/bevy_ecs/src/template.rs

@@ -8,7 +8,7 @@ use crate::{
     resource::Resource,
     world::{EntityWorldMut, Mut, World},
 };
-use alloc::{vec, vec::Vec};
+use alloc::{string::String, vec, vec::Vec};
 use variadics_please::all_tuples;
 
 /// A [`Template`] is something that, given a spawn context (target [`Entity`], [`World`], etc), can produce a [`Template::Output`].
@@ -405,6 +405,8 @@ pub trait SpecializeFromTemplate: Sized {}
 pub enum EntityTemplate {
     /// A reference to a specific [`Entity`]
     Entity(Entity),
+    /// A path to a specific [`Entity`]. Resolved via [`World::get_entity_from_path::<ChildOf, Name>`]
+    EntityPath(String),
     /// A reference to an entity via a [`ScopedEntityIndex`]
     ScopedEntityIndex(ScopedEntityIndex),
 }
@@ -435,12 +437,25 @@ impl From<Entity> for EntityTemplate {
     }
 }
 
+impl From<String> for EntityTemplate {
+    fn from(path: String) -> Self {
+        Self::EntityPath(path)
+    }
+}
+
+impl From<&'static str> for EntityTemplate {
+    fn from(path: &'static str) -> Self {
+        Self::EntityPath(path.into())
+    }
+}
+
 impl Template for EntityTemplate {
     type Output = Entity;
 
     fn build_template(&self, context: &mut TemplateContext) -> Result<Self::Output> {
         Ok(match self {
             Self::Entity(entity) => *entity,
+            Self::EntityPath(path) => context.entity.world().get_entity_from_path(path, None)?,
             Self::ScopedEntityIndex(scoped_entity_index) => {
                 context.get_scoped_entity(*scoped_entity_index)
             }
@@ -450,6 +465,7 @@ impl Template for EntityTemplate {
     fn clone_template(&self) -> Self {
         match self {
             Self::Entity(entity) => Self::Entity(*entity),
+            Self::EntityPath(path) => Self::EntityPath(path.clone()),
             Self::ScopedEntityIndex(scoped_entity_index) => {
                 Self::ScopedEntityIndex(*scoped_entity_index)
             }

crates/bevy_ecs/src/world/error.rs

@@ -1,6 +1,6 @@
 //! Contains error types returned by bevy's schedule.
 
-use alloc::vec::Vec;
+use alloc::{string::String, vec::Vec};
 use bevy_utils::prelude::DebugName;
 
 use crate::{
@@ -75,6 +75,26 @@ pub enum ResourceFetchError {
     NoResourceAccess(ComponentId),
 }
 
+/// An error returned when a path cannot be resolved.
+#[derive(thiserror::Error, Debug, Clone, PartialEq, Eq)]
+pub enum EntityPathError {
+    /// Path is empty
+    #[error("Entity path is empty")]
+    EmptyPath,
+    /// Root entity is not an ancestor of the starting entity
+    #[error("{0} is not an ancestor of {1}")]
+    RootIsNotAncestor(Entity, Entity),
+    /// One of the entities along the path does not contain a `Name` component
+    #[error("{0}, or one of it's ancestors does not contain a `Name` component")]
+    BrokenPath(Entity),
+    /// No paths match the given path
+    #[error("{0} does not match any entity")]
+    NoMatchingPath(String),
+    /// More than one paths match the given path
+    #[error("{0} matches multiple entities")]
+    AmbiguousPath(String),
+}
+
 #[cfg(test)]
 mod tests {
     use crate::{