Self-referential relationships

[mrchantey]

Objective

Closes #18522

This pr allows entities to have, erm, self-relations..

By default pointing a relationship to its own entity will log a warning and remove the component. However, self-referential relationships are semantically valid in many cases: Likes(self), EmployedBy(self), TalkingTo(self), Healing(self).

Solution

• Added const ALLOW_SELF:bool = false to the Relationship trait,
• Updated section that disallows self-relations to check for this
• Added the allow_self flag to the macro

#[derive(Component)]
#[relationship(relationship_target = PeopleILike, allow_self)]
pub struct LikedBy(pub Entity);

#[derive(Component)]
#[relationship_target(relationship = LikedBy)]
pub struct PeopleILike(Vec<Entity>);

let entity = world.spawn_empty().id();
world.entity_mut(entity).insert(LikedBy(entity));

// The relationship is preserved
assert!(world.entity(entity).contains::<LikedBy>());
assert!(world.entity(entity).contains::<PeopleILike>());

Testing

• added insert/remove tests

---

Showcase

Relationships can now optionally point to their own entity by setting #[relationship(allow_self)].

By default pointing a relationship to its own entity will log a warning and remove the component. However, self-referential relationships are semantically valid in many cases: Likes(self), EmployedBy(self), TalkingTo(self), Healing(self), and many more.

Click to view usage

To allow a relationship to point to its own entity, add the allow_self attribute:

#[derive(Component)]
#[relationship(relationship_target = PeopleILike, allow_self)]
pub struct LikedBy(pub Entity);

#[derive(Component)]
#[relationship_target(relationship = LikedBy)]
pub struct PeopleILike(Vec<Entity>);

Now entities can have relationships that point to themselves:

let entity = world.spawn_empty().id();
world.entity_mut(entity).insert(LikedBy(entity));

// The relationship is preserved
assert!(world.entity(entity).contains::<LikedBy>());
assert!(world.entity(entity).contains::<PeopleILike>());

[Copilot]

Pull request overview

This PR enables entities to have self-referential relationships by adding an optional allow_self attribute to the #[relationship] macro. By default, relationships pointing to their own entity are rejected with a warning, but this can now be explicitly allowed for semantically valid use cases like Likes(self), EmployedBy(self), or Healing(self).

Key changes:

• Added ALLOW_SELF: bool = false constant to the Relationship trait with appropriate documentation warnings about infinite loops
• Extended the macro parser to accept the allow_self attribute alongside relationship_target
• Added comprehensive tests covering insertion and removal of self-referential relationships

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.

File	Description
release-content/release-notes/allow_self_relationships.md	Release notes documenting the new allow_self feature with usage examples
crates/bevy_ecs/src/relationship/mod.rs	Added ALLOW_SELF constant to trait, updated validation logic to check the flag, added documentation and tests
crates/bevy_ecs/macros/src/lib.rs	Added documentation examples for allow_self attribute and fixed existing typo in relationship_target example
crates/bevy_ecs/macros/src/component.rs	Extended parser to handle allow_self keyword and generate correct trait implementation

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[mrchantey]

apologies for the copilot noise, didnt realize this auto-review thing was on.

[hukasu]

I feel allow_self is not descriptive enough, so I would bike shed to have the attribute to be a bit more descriptive

[mrchantey]

how about allow_target_self

[Bleachfuel]

maybe allow_self_referential

[janhohenheim]

Some minor notes, but nothing blocking :) I personally would prefer keeping the short and sweet allow_self, but allow_self_referential is also fine.

[hukasu]

I was thinking, could it be changed to be Relationship<const Allow_Self: bool> so that Traversal can check for Relationship<false>

[hukasu]

No, wait, you should still be able to create traversal on self referential

[ickshonpe]

This is a definitely a really useful feature, but the allow_self name feels potentially confusing to me. Even though allow_self has obviously nothing to do with self parameters, they are so ubiquitous in Rust, I think it would be a struggle to disassociate the two things.

Maybe reflexive would be better. It's a bit more mathy but the word precisely means something that is self referential.