Skip to content

Add with_related_empty methods to EntityWorldMut and EntityCommands #20268

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from

Conversation

muddxyii
Copy link
Contributor

@muddxyii muddxyii commented Jul 23, 2025

Objective

  • Improve API for spawning entities with relationships but no additional components.
  • Currently this requires awkward syntax: commands.spawn_empty().with_related::<Children>(())
  • New syntax: commands.spawn_empty().with_related_empty::<Children>()
  • Fixes Allow for adding a relationship without a bundle. #19230

Solution

  • Added with_related_empty methods to both EntityWorldMut and EntityCommands

Testing

  • Added tests covering both EntityWorldMut and EntityCommands implementations

@muddxyii muddxyii marked this pull request as ready for review July 23, 2025 21:47
@alice-i-cecile alice-i-cecile added A-ECS Entities, components, systems, and events X-Contentious There are nontrivial implications that should be thought through labels Jul 23, 2025
@alice-i-cecile
Copy link
Member

I'm not sold that this is common enough to warrant a helper. @Freyja-moth, can you explain where you ran into this?

@alice-i-cecile alice-i-cecile added C-Usability A targeted quality-of-life change that makes Bevy easier to use D-Straightforward Simple bug fixes and API improvements, docs, test and examples S-Needs-Review Needs reviewer attention (from anyone!) to move forward labels Jul 23, 2025
@Freyja-moth
Copy link
Contributor

Freyja-moth commented Jul 24, 2025

I can't remember exactly where I ran into it (it's quite likely that I've replaced/removed the code), but it is useful for when the relationship has required components and no additional components are needed.

This is admittedly a bit of an arbitrary example, but I'm sure there are similar practical use cases that I just can't think of at the moment.

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

#[derive(Component)]
#[require(
    Name::new("Key"),
)]
#[relationship(relationship_target = HeldKeys)]
pub struct Key(Entity);

#[derive(Component)]
#[require(Name::new("Special Key")]
#[relationship(relationship_target = SpecialDoor)]
pub struct SpecialKey(pub Entity);

#[derive(Component)]
#[relationship_target(relationship = SpecialKey)]
pub struct SpecialDoor(Entity);

fn spawn_keys(mut commands: Commands, special_door: Single<Entity, With<SpecialDoor>>) {
    commands.spawn(Player)
        .with_related_empty::<HeldKeys>() // Generic key, can be used to open any door, but the special one, since there's no additional components needed beyond the required components it's easier to use the new method.
        .with_related::<HeldKeys>(SpecialKey(*special_door)); // Special key that can only be used to open a door with SpecialDoor
}

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-ECS Entities, components, systems, and events C-Usability A targeted quality-of-life change that makes Bevy easier to use D-Straightforward Simple bug fixes and API improvements, docs, test and examples S-Needs-Review Needs reviewer attention (from anyone!) to move forward X-Contentious There are nontrivial implications that should be thought through
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Allow for adding a relationship without a bundle.
3 participants