[Merged by Bors] - Implement `Bundle` for `Component`. Use `Bundle` tuples for insertion #2975

DJMcNab · 2021-10-15T21:33:16Z

@BoxyUwU this is your fault.

Also cart didn't arrive in time to tell us not to do this.

Objective

Fix Implement Bundle for every component and simplify API #2974

Solution

The first commit just does the actual change
Follow up commits do steps to prove that this method works to unify as required, but this does not remove insert_bundle.

This change opens the doors to a smaller / simpler / more ergonomic set of Entity construction apis: in a follow up PR, we can add one unified insert(bundle) and remove(bundle) API, instead of the split insert(component) and insert_bundle(bundle) APIs.

This change also enables users to consolidate their inserts and removes, which can significantly reduce the number of expensive archetype moves.

Changelog

Changed

Nested bundles now collapse automatically, and every Component now implements Bundle.
This means that you can combine bundles and components arbitrarily, for example:

// before:
.insert(A).insert_bundle(MyBBundle{..})
// after:
.insert_bundle((A, MyBBundle {..}))

Note that there will be a follow up PR that removes the current insert impl and renames insert_bundle to insert.

Removed

The bundle attribute in derive(Bundle).

Migration guide

In derive(Bundle), the bundle attribute has been removed. Nested bundles are not collapsed automatically. You should remove #[bundle] attributes.

BoxyUwU

Can I approve this 🤣 I might be biased

crates/bevy_ecs/src/reflect.rs

VVishion · 2021-10-15T22:55:42Z

I cant say much about the implementation consequences, but generalized concepts are good and ergonomic, imo. Furthermore, is it not hard to grasp that a component can been seen as a bundle.

djeedai

Not an expert by any means, so can't much judge content, but the change looks economic and very useful for all types of users.

Nilirad · 2021-10-16T07:48:32Z

Why no insertion/removal API included?

DJMcNab · 2021-10-16T08:15:36Z

I don't understand the question @Nilirad

Nilirad · 2021-10-16T08:21:16Z

In the PR description you specified that it doesn't remove insert_bundle. Having insert handle bundles would work both for bundles and components.

DJMcNab · 2021-10-16T08:37:43Z

Because I want this pr to be reviewable, not just a mess of insert_bundlr->insert renamings

If this gets approved we can change them over in a follow up pr

crates/bevy_ecs/src/bundle.rs

alice-i-cecile · 2021-10-16T13:12:47Z

crates/bevy_ecs/src/bundle.rs

@@ -129,6 +130,25 @@ macro_rules! tuple_impl {

 all_tuples!(tuple_impl, 0, 15, C);

+// Implement `Bundle` for all `Component`s, as any component is trivially a bundle of itself
+unsafe impl<T: Component> Bundle for T {


Technically, this is missing SAFETY comments. I'm really not sure I care.

alice-i-cecile · 2021-10-16T13:14:45Z

examples/2d/contributors.rs

-        .insert(ContributorDisplay)
-        .insert_bundle(TextBundle {
+    commands.spawn().insert((
+        ContributorDisplay,


Wow, that's wild how much cleaner this change looks.

alice-i-cecile

LGTM! I'm impressed at how simple this change is.

There's a minor docs nit to explain how bundle nesting works, but I would not be upset to see this merged without it.

I would prefer to remove insert_bundle and remove_bundle in the same PR so it doesn't get forgotten, but I'm fine if you want to split it (or wait until after @cart reviews and approves this). It certainly is easier to read the diff in the current form.

crates/bevy_ecs/src/bundle.rs

alice-i-cecile · 2021-10-16T17:55:32Z

crates/bevy_ecs/src/bundle.rs

-///
-/// You can nest bundles:
+/// There is a derive macro for [`Bundle`]. This can be used to create your own bundles from a struct of
+/// other bundles:


This needs to explain how this will cause all components across all of the bundles to be flattened.

It should also mention that including the same component more than once will cause the last value to overwrite all previous values for that type.

Bundles which contain the same type multiple times will currently panic when 'initialised'

cart · 2022-09-20T20:16:46Z

Resolved merge conflicts with main, removed a sentence fragment, renamed the PR ("fix" both minimized the impact of this change and implied that the current approach is "broken", which it definitely is not), and edited the PR description because the changelog section included the not-implemented-in-this-pr insert changes.

My reservations due to the uncertainty around how Bundle interacts with the future scene/prefab changes still exist, but we've largely reached consensus that this is a very safe bet. And the ergonomics and performance wins are very compelling (being able to combine component and bundle inserts means that users have the ability to hugely cut down the number of archetype moves).

Lets merge this thing!

cart · 2022-09-20T20:16:51Z

bors r+

@BoxyUwU

#2975) @BoxyUwU this is your fault. Also cart didn't arrive in time to tell us not to do this. # Objective - Fix #2974 ## Solution - The first commit just does the actual change - Follow up commits do steps to prove that this method works to unify as required, but this does not remove `insert_bundle`. ## Changelog ### Changed Nested bundles now collapse automatically, and every `Component` now implements `Bundle`. This means that you can combine bundles and components arbitrarily, for example: ```rust // before: .insert(A).insert_bundle(MyBBundle{..}) // after: .insert_bundle((A, MyBBundle {..})) ``` Note that there will be a follow up PR that removes the current `insert` impl and renames `insert_bundle` to `insert`. ### Removed The `bundle` attribute in `derive(Bundle)`. ## Migration guide In `derive(Bundle)`, the `bundle` attribute has been removed. Nested bundles are not collapsed automatically. You should remove `#[bundle]` attributes. Co-authored-by: Carter Anderson <mcanders1@gmail.com>

bors · 2022-09-20T20:35:12Z

Pull request successfully merged into main.

Build succeeded:

…6039) # Objective Take advantage of the "impl Bundle for Component" changes in #2975 / add the follow up changes discussed there. ## Solution - Change `insert` and `remove` to accept a Bundle instead of a Component (for both Commands and World) - Deprecate `insert_bundle`, `remove_bundle`, and `remove_bundle_intersection` - Add `remove_intersection` --- ## Changelog - Change `insert` and `remove` now accept a Bundle instead of a Component (for both Commands and World) - `insert_bundle` and `remove_bundle` are deprecated ## Migration Guide Replace `insert_bundle` with `insert`: ```rust // Old (0.8) commands.spawn().insert_bundle(SomeBundle::default()); // New (0.9) commands.spawn().insert(SomeBundle::default()); ``` Replace `remove_bundle` with `remove`: ```rust // Old (0.8) commands.entity(some_entity).remove_bundle::<SomeBundle>(); // New (0.9) commands.entity(some_entity).remove::<SomeBundle>(); ``` Replace `remove_bundle_intersection` with `remove_intersection`: ```rust // Old (0.8) world.entity_mut(some_entity).remove_bundle_intersection::<SomeBundle>(); // New (0.9) world.entity_mut(some_entity).remove_intersection::<SomeBundle>(); ``` Consider consolidating as many operations as possible to improve ergonomics and cut down on archetype moves: ```rust // Old (0.8) commands.spawn() .insert_bundle(SomeBundle::default()) .insert(SomeComponent); // New (0.9) - Option 1 commands.spawn().insert(( SomeBundle::default(), SomeComponent, )) // New (0.9) - Option 2 commands.spawn_bundle(( SomeBundle::default(), SomeComponent, )) ``` ## Next Steps Consider changing `spawn` to accept a bundle and deprecate `spawn_bundle`.

# Objective Now that we can consolidate Bundles and Components under a single insert (thanks to #2975 and #6039), almost 100% of world spawns now look like `world.spawn().insert((Some, Tuple, Here))`. Spawning an entity without any components is an extremely uncommon pattern, so it makes sense to give spawn the "first class" ergonomic api. This consolidated api should be made consistent across all spawn apis (such as World and Commands). ## Solution All `spawn` apis (`World::spawn`, `Commands:;spawn`, `ChildBuilder::spawn`, and `WorldChildBuilder::spawn`) now accept a bundle as input: ```rust // before: commands .spawn() .insert((A, B, C)); world .spawn() .insert((A, B, C); // after commands.spawn((A, B, C)); world.spawn((A, B, C)); ``` All existing instances of `spawn_bundle` have been deprecated in favor of the new `spawn` api. A new `spawn_empty` has been added, replacing the old `spawn` api. By allowing `world.spawn(some_bundle)` to replace `world.spawn().insert(some_bundle)`, this opened the door to removing the initial entity allocation in the "empty" archetype / table done in `spawn()` (and subsequent move to the actual archetype in `.insert(some_bundle)`). This improves spawn performance by over 10%: ![image](https://user-images.githubusercontent.com/2694663/191627587-4ab2f949-4ccd-4231-80eb-80dd4d9ad6b9.png) To take this measurement, I added a new `world_spawn` benchmark. Unfortunately, optimizing `Commands::spawn` is slightly less trivial, as Commands expose the Entity id of spawned entities prior to actually spawning. Doing the optimization would (naively) require assurances that the `spawn(some_bundle)` command is applied before all other commands involving the entity (which would not necessarily be true, if memory serves). Optimizing `Commands::spawn` this way does feel possible, but it will require careful thought (and maybe some additional checks), which deserves its own PR. For now, it has the same performance characteristics of the current `Commands::spawn_bundle` on main. **Note that 99% of this PR is simple renames and refactors. The only code that needs careful scrutiny is the new `World::spawn()` impl, which is relatively straightforward, but it has some new unsafe code (which re-uses battle tested BundlerSpawner code path).** --- ## Changelog - All `spawn` apis (`World::spawn`, `Commands:;spawn`, `ChildBuilder::spawn`, and `WorldChildBuilder::spawn`) now accept a bundle as input - All instances of `spawn_bundle` have been deprecated in favor of the new `spawn` api - World and Commands now have `spawn_empty()`, which is equivalent to the old `spawn()` behavior. ## Migration Guide ```rust // Old (0.8): commands .spawn() .insert_bundle((A, B, C)); // New (0.9) commands.spawn((A, B, C)); // Old (0.8): commands.spawn_bundle((A, B, C)); // New (0.9) commands.spawn((A, B, C)); // Old (0.8): let entity = commands.spawn().id(); // New (0.9) let entity = commands.spawn_empty().id(); // Old (0.8) let entity = world.spawn().id(); // New (0.9) let entity = world.spawn_empty(); ```

maccesch · 2022-09-28T23:44:20Z

@alice-i-cecile @cart With this merged what should I do with #5628 which adds #[bundle(ignore)]? Is this still needed?

alice-i-cecile · 2022-09-28T23:45:59Z

@maccesch I think this is still needed: I don't think that this PR changes the story at all around PhantomData in bundles for example.

maccesch · 2022-09-28T23:46:51Z

Cool. So I simply get rid of #[bundle(flatten)]

@BoxyUwU

bevyengine#2975) @BoxyUwU this is your fault. Also cart didn't arrive in time to tell us not to do this. # Objective - Fix bevyengine#2974 ## Solution - The first commit just does the actual change - Follow up commits do steps to prove that this method works to unify as required, but this does not remove `insert_bundle`. ## Changelog ### Changed Nested bundles now collapse automatically, and every `Component` now implements `Bundle`. This means that you can combine bundles and components arbitrarily, for example: ```rust // before: .insert(A).insert_bundle(MyBBundle{..}) // after: .insert_bundle((A, MyBBundle {..})) ``` Note that there will be a follow up PR that removes the current `insert` impl and renames `insert_bundle` to `insert`. ### Removed The `bundle` attribute in `derive(Bundle)`. ## Migration guide In `derive(Bundle)`, the `bundle` attribute has been removed. Nested bundles are not collapsed automatically. You should remove `#[bundle]` attributes. Co-authored-by: Carter Anderson <mcanders1@gmail.com>

…evyengine#6039) # Objective Take advantage of the "impl Bundle for Component" changes in bevyengine#2975 / add the follow up changes discussed there. ## Solution - Change `insert` and `remove` to accept a Bundle instead of a Component (for both Commands and World) - Deprecate `insert_bundle`, `remove_bundle`, and `remove_bundle_intersection` - Add `remove_intersection` --- ## Changelog - Change `insert` and `remove` now accept a Bundle instead of a Component (for both Commands and World) - `insert_bundle` and `remove_bundle` are deprecated ## Migration Guide Replace `insert_bundle` with `insert`: ```rust // Old (0.8) commands.spawn().insert_bundle(SomeBundle::default()); // New (0.9) commands.spawn().insert(SomeBundle::default()); ``` Replace `remove_bundle` with `remove`: ```rust // Old (0.8) commands.entity(some_entity).remove_bundle::<SomeBundle>(); // New (0.9) commands.entity(some_entity).remove::<SomeBundle>(); ``` Replace `remove_bundle_intersection` with `remove_intersection`: ```rust // Old (0.8) world.entity_mut(some_entity).remove_bundle_intersection::<SomeBundle>(); // New (0.9) world.entity_mut(some_entity).remove_intersection::<SomeBundle>(); ``` Consider consolidating as many operations as possible to improve ergonomics and cut down on archetype moves: ```rust // Old (0.8) commands.spawn() .insert_bundle(SomeBundle::default()) .insert(SomeComponent); // New (0.9) - Option 1 commands.spawn().insert(( SomeBundle::default(), SomeComponent, )) // New (0.9) - Option 2 commands.spawn_bundle(( SomeBundle::default(), SomeComponent, )) ``` ## Next Steps Consider changing `spawn` to accept a bundle and deprecate `spawn_bundle`.

# Objective Now that we can consolidate Bundles and Components under a single insert (thanks to bevyengine#2975 and bevyengine#6039), almost 100% of world spawns now look like `world.spawn().insert((Some, Tuple, Here))`. Spawning an entity without any components is an extremely uncommon pattern, so it makes sense to give spawn the "first class" ergonomic api. This consolidated api should be made consistent across all spawn apis (such as World and Commands). ## Solution All `spawn` apis (`World::spawn`, `Commands:;spawn`, `ChildBuilder::spawn`, and `WorldChildBuilder::spawn`) now accept a bundle as input: ```rust // before: commands .spawn() .insert((A, B, C)); world .spawn() .insert((A, B, C); // after commands.spawn((A, B, C)); world.spawn((A, B, C)); ``` All existing instances of `spawn_bundle` have been deprecated in favor of the new `spawn` api. A new `spawn_empty` has been added, replacing the old `spawn` api. By allowing `world.spawn(some_bundle)` to replace `world.spawn().insert(some_bundle)`, this opened the door to removing the initial entity allocation in the "empty" archetype / table done in `spawn()` (and subsequent move to the actual archetype in `.insert(some_bundle)`). This improves spawn performance by over 10%: ![image](https://user-images.githubusercontent.com/2694663/191627587-4ab2f949-4ccd-4231-80eb-80dd4d9ad6b9.png) To take this measurement, I added a new `world_spawn` benchmark. Unfortunately, optimizing `Commands::spawn` is slightly less trivial, as Commands expose the Entity id of spawned entities prior to actually spawning. Doing the optimization would (naively) require assurances that the `spawn(some_bundle)` command is applied before all other commands involving the entity (which would not necessarily be true, if memory serves). Optimizing `Commands::spawn` this way does feel possible, but it will require careful thought (and maybe some additional checks), which deserves its own PR. For now, it has the same performance characteristics of the current `Commands::spawn_bundle` on main. **Note that 99% of this PR is simple renames and refactors. The only code that needs careful scrutiny is the new `World::spawn()` impl, which is relatively straightforward, but it has some new unsafe code (which re-uses battle tested BundlerSpawner code path).** --- ## Changelog - All `spawn` apis (`World::spawn`, `Commands:;spawn`, `ChildBuilder::spawn`, and `WorldChildBuilder::spawn`) now accept a bundle as input - All instances of `spawn_bundle` have been deprecated in favor of the new `spawn` api - World and Commands now have `spawn_empty()`, which is equivalent to the old `spawn()` behavior. ## Migration Guide ```rust // Old (0.8): commands .spawn() .insert_bundle((A, B, C)); // New (0.9) commands.spawn((A, B, C)); // Old (0.8): commands.spawn_bundle((A, B, C)); // New (0.9) commands.spawn((A, B, C)); // Old (0.8): let entity = commands.spawn().id(); // New (0.9) let entity = commands.spawn_empty().id(); // Old (0.8) let entity = world.spawn().id(); // New (0.9) let entity = world.spawn_empty(); ```

@BoxyUwU

bevyengine#2975) @BoxyUwU this is your fault. Also cart didn't arrive in time to tell us not to do this. # Objective - Fix bevyengine#2974 ## Solution - The first commit just does the actual change - Follow up commits do steps to prove that this method works to unify as required, but this does not remove `insert_bundle`. ## Changelog ### Changed Nested bundles now collapse automatically, and every `Component` now implements `Bundle`. This means that you can combine bundles and components arbitrarily, for example: ```rust // before: .insert(A).insert_bundle(MyBBundle{..}) // after: .insert_bundle((A, MyBBundle {..})) ``` Note that there will be a follow up PR that removes the current `insert` impl and renames `insert_bundle` to `insert`. ### Removed The `bundle` attribute in `derive(Bundle)`. ## Migration guide In `derive(Bundle)`, the `bundle` attribute has been removed. Nested bundles are not collapsed automatically. You should remove `#[bundle]` attributes. Co-authored-by: Carter Anderson <mcanders1@gmail.com>

…evyengine#6039) # Objective Take advantage of the "impl Bundle for Component" changes in bevyengine#2975 / add the follow up changes discussed there. ## Solution - Change `insert` and `remove` to accept a Bundle instead of a Component (for both Commands and World) - Deprecate `insert_bundle`, `remove_bundle`, and `remove_bundle_intersection` - Add `remove_intersection` --- ## Changelog - Change `insert` and `remove` now accept a Bundle instead of a Component (for both Commands and World) - `insert_bundle` and `remove_bundle` are deprecated ## Migration Guide Replace `insert_bundle` with `insert`: ```rust // Old (0.8) commands.spawn().insert_bundle(SomeBundle::default()); // New (0.9) commands.spawn().insert(SomeBundle::default()); ``` Replace `remove_bundle` with `remove`: ```rust // Old (0.8) commands.entity(some_entity).remove_bundle::<SomeBundle>(); // New (0.9) commands.entity(some_entity).remove::<SomeBundle>(); ``` Replace `remove_bundle_intersection` with `remove_intersection`: ```rust // Old (0.8) world.entity_mut(some_entity).remove_bundle_intersection::<SomeBundle>(); // New (0.9) world.entity_mut(some_entity).remove_intersection::<SomeBundle>(); ``` Consider consolidating as many operations as possible to improve ergonomics and cut down on archetype moves: ```rust // Old (0.8) commands.spawn() .insert_bundle(SomeBundle::default()) .insert(SomeComponent); // New (0.9) - Option 1 commands.spawn().insert(( SomeBundle::default(), SomeComponent, )) // New (0.9) - Option 2 commands.spawn_bundle(( SomeBundle::default(), SomeComponent, )) ``` ## Next Steps Consider changing `spawn` to accept a bundle and deprecate `spawn_bundle`.

# Objective Now that we can consolidate Bundles and Components under a single insert (thanks to bevyengine#2975 and bevyengine#6039), almost 100% of world spawns now look like `world.spawn().insert((Some, Tuple, Here))`. Spawning an entity without any components is an extremely uncommon pattern, so it makes sense to give spawn the "first class" ergonomic api. This consolidated api should be made consistent across all spawn apis (such as World and Commands). ## Solution All `spawn` apis (`World::spawn`, `Commands:;spawn`, `ChildBuilder::spawn`, and `WorldChildBuilder::spawn`) now accept a bundle as input: ```rust // before: commands .spawn() .insert((A, B, C)); world .spawn() .insert((A, B, C); // after commands.spawn((A, B, C)); world.spawn((A, B, C)); ``` All existing instances of `spawn_bundle` have been deprecated in favor of the new `spawn` api. A new `spawn_empty` has been added, replacing the old `spawn` api. By allowing `world.spawn(some_bundle)` to replace `world.spawn().insert(some_bundle)`, this opened the door to removing the initial entity allocation in the "empty" archetype / table done in `spawn()` (and subsequent move to the actual archetype in `.insert(some_bundle)`). This improves spawn performance by over 10%: ![image](https://user-images.githubusercontent.com/2694663/191627587-4ab2f949-4ccd-4231-80eb-80dd4d9ad6b9.png) To take this measurement, I added a new `world_spawn` benchmark. Unfortunately, optimizing `Commands::spawn` is slightly less trivial, as Commands expose the Entity id of spawned entities prior to actually spawning. Doing the optimization would (naively) require assurances that the `spawn(some_bundle)` command is applied before all other commands involving the entity (which would not necessarily be true, if memory serves). Optimizing `Commands::spawn` this way does feel possible, but it will require careful thought (and maybe some additional checks), which deserves its own PR. For now, it has the same performance characteristics of the current `Commands::spawn_bundle` on main. **Note that 99% of this PR is simple renames and refactors. The only code that needs careful scrutiny is the new `World::spawn()` impl, which is relatively straightforward, but it has some new unsafe code (which re-uses battle tested BundlerSpawner code path).** --- ## Changelog - All `spawn` apis (`World::spawn`, `Commands:;spawn`, `ChildBuilder::spawn`, and `WorldChildBuilder::spawn`) now accept a bundle as input - All instances of `spawn_bundle` have been deprecated in favor of the new `spawn` api - World and Commands now have `spawn_empty()`, which is equivalent to the old `spawn()` behavior. ## Migration Guide ```rust // Old (0.8): commands .spawn() .insert_bundle((A, B, C)); // New (0.9) commands.spawn((A, B, C)); // Old (0.8): commands.spawn_bundle((A, B, C)); // New (0.9) commands.spawn((A, B, C)); // Old (0.8): let entity = commands.spawn().id(); // New (0.9) let entity = commands.spawn_empty().id(); // Old (0.8) let entity = world.spawn().id(); // New (0.9) let entity = world.spawn_empty(); ```

# Objective Bevy still has many instances of using single-tuples `(T,)` to create a bundle. Due to #2975, this is no longer necessary. ## Solution Search for regex `\(.+\s*,\)`. This should have found every instance.

@BoxyUwU

bevyengine#2975) @BoxyUwU this is your fault. Also cart didn't arrive in time to tell us not to do this. # Objective - Fix bevyengine#2974 ## Solution - The first commit just does the actual change - Follow up commits do steps to prove that this method works to unify as required, but this does not remove `insert_bundle`. ## Changelog ### Changed Nested bundles now collapse automatically, and every `Component` now implements `Bundle`. This means that you can combine bundles and components arbitrarily, for example: ```rust // before: .insert(A).insert_bundle(MyBBundle{..}) // after: .insert_bundle((A, MyBBundle {..})) ``` Note that there will be a follow up PR that removes the current `insert` impl and renames `insert_bundle` to `insert`. ### Removed The `bundle` attribute in `derive(Bundle)`. ## Migration guide In `derive(Bundle)`, the `bundle` attribute has been removed. Nested bundles are not collapsed automatically. You should remove `#[bundle]` attributes. Co-authored-by: Carter Anderson <mcanders1@gmail.com>

…evyengine#6039) # Objective Take advantage of the "impl Bundle for Component" changes in bevyengine#2975 / add the follow up changes discussed there. ## Solution - Change `insert` and `remove` to accept a Bundle instead of a Component (for both Commands and World) - Deprecate `insert_bundle`, `remove_bundle`, and `remove_bundle_intersection` - Add `remove_intersection` --- ## Changelog - Change `insert` and `remove` now accept a Bundle instead of a Component (for both Commands and World) - `insert_bundle` and `remove_bundle` are deprecated ## Migration Guide Replace `insert_bundle` with `insert`: ```rust // Old (0.8) commands.spawn().insert_bundle(SomeBundle::default()); // New (0.9) commands.spawn().insert(SomeBundle::default()); ``` Replace `remove_bundle` with `remove`: ```rust // Old (0.8) commands.entity(some_entity).remove_bundle::<SomeBundle>(); // New (0.9) commands.entity(some_entity).remove::<SomeBundle>(); ``` Replace `remove_bundle_intersection` with `remove_intersection`: ```rust // Old (0.8) world.entity_mut(some_entity).remove_bundle_intersection::<SomeBundle>(); // New (0.9) world.entity_mut(some_entity).remove_intersection::<SomeBundle>(); ``` Consider consolidating as many operations as possible to improve ergonomics and cut down on archetype moves: ```rust // Old (0.8) commands.spawn() .insert_bundle(SomeBundle::default()) .insert(SomeComponent); // New (0.9) - Option 1 commands.spawn().insert(( SomeBundle::default(), SomeComponent, )) // New (0.9) - Option 2 commands.spawn_bundle(( SomeBundle::default(), SomeComponent, )) ``` ## Next Steps Consider changing `spawn` to accept a bundle and deprecate `spawn_bundle`.

# Objective Now that we can consolidate Bundles and Components under a single insert (thanks to bevyengine#2975 and bevyengine#6039), almost 100% of world spawns now look like `world.spawn().insert((Some, Tuple, Here))`. Spawning an entity without any components is an extremely uncommon pattern, so it makes sense to give spawn the "first class" ergonomic api. This consolidated api should be made consistent across all spawn apis (such as World and Commands). ## Solution All `spawn` apis (`World::spawn`, `Commands:;spawn`, `ChildBuilder::spawn`, and `WorldChildBuilder::spawn`) now accept a bundle as input: ```rust // before: commands .spawn() .insert((A, B, C)); world .spawn() .insert((A, B, C); // after commands.spawn((A, B, C)); world.spawn((A, B, C)); ``` All existing instances of `spawn_bundle` have been deprecated in favor of the new `spawn` api. A new `spawn_empty` has been added, replacing the old `spawn` api. By allowing `world.spawn(some_bundle)` to replace `world.spawn().insert(some_bundle)`, this opened the door to removing the initial entity allocation in the "empty" archetype / table done in `spawn()` (and subsequent move to the actual archetype in `.insert(some_bundle)`). This improves spawn performance by over 10%: ![image](https://user-images.githubusercontent.com/2694663/191627587-4ab2f949-4ccd-4231-80eb-80dd4d9ad6b9.png) To take this measurement, I added a new `world_spawn` benchmark. Unfortunately, optimizing `Commands::spawn` is slightly less trivial, as Commands expose the Entity id of spawned entities prior to actually spawning. Doing the optimization would (naively) require assurances that the `spawn(some_bundle)` command is applied before all other commands involving the entity (which would not necessarily be true, if memory serves). Optimizing `Commands::spawn` this way does feel possible, but it will require careful thought (and maybe some additional checks), which deserves its own PR. For now, it has the same performance characteristics of the current `Commands::spawn_bundle` on main. **Note that 99% of this PR is simple renames and refactors. The only code that needs careful scrutiny is the new `World::spawn()` impl, which is relatively straightforward, but it has some new unsafe code (which re-uses battle tested BundlerSpawner code path).** --- ## Changelog - All `spawn` apis (`World::spawn`, `Commands:;spawn`, `ChildBuilder::spawn`, and `WorldChildBuilder::spawn`) now accept a bundle as input - All instances of `spawn_bundle` have been deprecated in favor of the new `spawn` api - World and Commands now have `spawn_empty()`, which is equivalent to the old `spawn()` behavior. ## Migration Guide ```rust // Old (0.8): commands .spawn() .insert_bundle((A, B, C)); // New (0.9) commands.spawn((A, B, C)); // Old (0.8): commands.spawn_bundle((A, B, C)); // New (0.9) commands.spawn((A, B, C)); // Old (0.8): let entity = commands.spawn().id(); // New (0.9) let entity = commands.spawn_empty().id(); // Old (0.8) let entity = world.spawn().id(); // New (0.9) let entity = world.spawn_empty(); ```

# Objective Bevy still has many instances of using single-tuples `(T,)` to create a bundle. Due to bevyengine#2975, this is no longer necessary. ## Solution Search for regex `\(.+\s*,\)`. This should have found every instance.

github-actions bot added the S-Needs-Triage This issue needs to be labelled label Oct 15, 2021

BoxyUwU approved these changes Oct 15, 2021

View reviewed changes

crates/bevy_ecs/src/reflect.rs Outdated Show resolved Hide resolved

djeedai approved these changes Oct 16, 2021

View reviewed changes

DJMcNab added A-ECS Entities, components, systems, and events C-Usability A simple quality-of-life change that makes Bevy easier to use S-Needs-Review and removed S-Needs-Triage This issue needs to be labelled labels Oct 16, 2021

BoxyUwU approved these changes Oct 16, 2021

View reviewed changes

DJMcNab changed the title ~~Implement Bundle in the Component derive.~~ Implement Bundle for every Component Oct 16, 2021

DJMcNab requested review from alice-i-cecile and TheRawMeatball October 16, 2021 11:42

TheRawMeatball approved these changes Oct 16, 2021

View reviewed changes

alice-i-cecile reviewed Oct 16, 2021

View reviewed changes

crates/bevy_ecs/src/bundle.rs Outdated Show resolved Hide resolved

alice-i-cecile reviewed Oct 16, 2021

View reviewed changes

alice-i-cecile approved these changes Oct 16, 2021

View reviewed changes

DJMcNab mentioned this pull request Oct 16, 2021

[Merged by Bors] - Fix double drop in BlobVec::replace_unchecked (#2597) #2848

Closed

DJMcNab requested a review from alice-i-cecile October 16, 2021 14:50

alice-i-cecile reviewed Oct 16, 2021

View reviewed changes

crates/bevy_ecs/src/bundle.rs Outdated Show resolved Hide resolved

alice-i-cecile reviewed Oct 16, 2021

View reviewed changes

DJMcNab requested a review from alice-i-cecile October 17, 2021 20:47

alice-i-cecile approved these changes Oct 17, 2021

View reviewed changes

alice-i-cecile added the S-Needs-Migration-Guide label Oct 22, 2021

alice-i-cecile approved these changes Oct 24, 2021

View reviewed changes

bors bot changed the title ~~Implement Bundle for Component. Use Bundle tuples for insertion~~ [Merged by Bors] - Implement Bundle for Component. Use Bundle tuples for insertion Sep 20, 2022

bors bot closed this Sep 20, 2022

irate-devil mentioned this pull request Sep 20, 2022

[Merged by Bors] - Use SpatialBundle/TransformBundle in examples #6002

Closed

cart mentioned this pull request Sep 20, 2022

[Merged by Bors] - Accept Bundles for insert and remove. Deprecate insert/remove_bundle #6039

Closed

cart mentioned this pull request Sep 21, 2022

[Merged by Bors] - Spawn now takes a Bundle #6054

Closed

james7132 mentioned this pull request Oct 19, 2022

Merge bundles together #792

Closed

JoJoJet mentioned this pull request Oct 29, 2022

[Merged by Bors] - Remove outdated uses of single-tuple bundles #6406

Closed

james7132 mentioned this pull request Dec 4, 2022

Enforce type-uniqueness of Bundles #2387

Closed

alice-i-cecile mentioned this pull request Mar 9, 2023

Deprecate App::add_system in favor of allowing single systems to be passed into add_systems #7992

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Merged by Bors] - Implement `Bundle` for `Component`. Use `Bundle` tuples for insertion #2975

[Merged by Bors] - Implement `Bundle` for `Component`. Use `Bundle` tuples for insertion #2975

DJMcNab commented Oct 15, 2021 •

edited by cart

BoxyUwU left a comment

VVishion commented Oct 15, 2021

djeedai left a comment

Nilirad commented Oct 16, 2021

DJMcNab commented Oct 16, 2021

Nilirad commented Oct 16, 2021

DJMcNab commented Oct 16, 2021

alice-i-cecile Oct 16, 2021 •

edited

alice-i-cecile Oct 16, 2021

alice-i-cecile left a comment

alice-i-cecile Oct 16, 2021

DJMcNab Oct 16, 2021 •

edited

cart commented Sep 20, 2022

cart commented Sep 20, 2022

bors bot commented Sep 20, 2022

maccesch commented Sep 28, 2022 •

edited

alice-i-cecile commented Sep 28, 2022

maccesch commented Sep 28, 2022

[Merged by Bors] - Implement Bundle for Component. Use Bundle tuples for insertion #2975

[Merged by Bors] - Implement Bundle for Component. Use Bundle tuples for insertion #2975

Conversation

DJMcNab commented Oct 15, 2021 • edited by cart

Objective

Solution

Changelog

Changed

Removed

Migration guide

BoxyUwU left a comment

Choose a reason for hiding this comment

VVishion commented Oct 15, 2021

djeedai left a comment

Choose a reason for hiding this comment

Nilirad commented Oct 16, 2021

DJMcNab commented Oct 16, 2021

Nilirad commented Oct 16, 2021

DJMcNab commented Oct 16, 2021

alice-i-cecile Oct 16, 2021 • edited

Choose a reason for hiding this comment

alice-i-cecile Oct 16, 2021

Choose a reason for hiding this comment

alice-i-cecile left a comment

Choose a reason for hiding this comment

alice-i-cecile Oct 16, 2021

Choose a reason for hiding this comment

DJMcNab Oct 16, 2021 • edited

Choose a reason for hiding this comment

cart commented Sep 20, 2022

cart commented Sep 20, 2022

bors bot commented Sep 20, 2022

maccesch commented Sep 28, 2022 • edited

alice-i-cecile commented Sep 28, 2022

maccesch commented Sep 28, 2022

[Merged by Bors] - Implement `Bundle` for `Component`. Use `Bundle` tuples for insertion #2975

[Merged by Bors] - Implement `Bundle` for `Component`. Use `Bundle` tuples for insertion #2975

DJMcNab commented Oct 15, 2021 •

edited by cart

alice-i-cecile Oct 16, 2021 •

edited

DJMcNab Oct 16, 2021 •

edited

maccesch commented Sep 28, 2022 •

edited