feat: add insert_if_new (#14397)

[jpetkau]

Objective

Often there are reasons to insert some components (e.g. Transform) separately from the rest of a bundle (e.g. PbrBundle). However insert overwrites existing components, making this difficult.

See also issue #14397

Fixes #2054.

Solution

This PR adds the method insert_if_new to EntityMut and Commands, which is the same as insert except that the old component is kept in case of conflicts.

It also renames some internal enums (from ComponentStatus::Mutated to Existing), to reflect the possible change in meaning.

Testing

Did you test these changes? If so, how?

Added basic unit tests; used the new behavior in my project.

Are there any parts that need more testing?

There should be a test that the change time isn't set if a component is not overwritten; I wasn't sure how to write a test for that case.

How can other people (reviewers) test your changes? Is there anything specific they need to know?

cargo test in the bevy_ecs project.

If relevant, what platforms did you test these changes on, and are there any important ones you can't test?

Only tested on Windows, but it doesn't touch anything platform-specific.

[github-actions]

Welcome, new contributor!

Please make sure you've read our contributing guide and we look forward to reviewing your pull request shortly ✨

[alice-i-cecile]

Some cleanup to do, but I like the feature. The name is fine, and I'm not super concerned about introducing a branch here: there's already one, we're just adding another arm.

[jpetkau]

Apparently I messed something up when fixing conflicts with "Track source location in change detection (#14034)", unit tests are failing now. Looking into it.

[alice-i-cecile]

Excellent. There are a few more things that should be added:

• EntityWorldMut::try_insert_if_new
• EntityCommands::try_insert_if_new

Those can easily be done in follow-up though, so you have my approval.

[SkiFire13]

Overall looks good to me after CI is fixed.

[SIGSTACKFAULT]

Could you add an example which demonstrates it? not a blocker.

[jpetkau]

@alice-i-cecile currently I have the on_insert trigger not running if you call insert_if_new and the component already exists. (The logic being that this is a no-op, the component didn't change so nothing should happen). Does this seems like the right behavior?

[NEON725]

Wish I'd known about this before trying to adopt #9231. Regardless, that PR should probably be closed now as this PR deprecates it.

[alice-i-cecile]

@alice-i-cecile currently I have the on_insert trigger not running if you call insert_if_new and the component already exists. (The logic being that this is a no-op, the component didn't change so nothing should happen). Does this seems like the right behavior?

This is correct.

[alice-i-cecile]

Sorry, I swear I tried to merge this! We'll see if my merge conflict resolution worked out.

[alice-i-cecile]

@jpetkau once CI is green please ping me and I'll get this in.

[jpetkau]

@jpetkau once CI is green please ping me and I'll get this in.

@alice-i-cecile Ok it's green again

[alice-i-cecile]

Thank you to everyone involved with the authoring or reviewing of this PR! This work is relatively important and needs release notes! Head over to bevyengine/bevy-website#1675 if you'd like to help out.