Command to clone entities #1515

alice-i-cecile · 2021-02-24T22:13:29Z

What problem does this solve or what need does it fill?

Creating copies of an entity is a powerful but simple abstraction. It's obviously useful for prefab workflows, but I'm also running into it when trying to create multiple copies of attacks and in similar gameplay code.

What solution would you like?

Create a fn clone_entity(entity: Entity) method for Commands. It would create a new entity with the same components and the same value of those components as the entity passed in.

What alternative(s) have you considered?

You can copy-paste the entity cloning code, but this is a lot of boilerplate and doesn't work well at all if the components in the entity aren't constant.

Additional context

Solving this is one of the proposed steps to resolve #1446.

This would only work on entities whose components all implement Clone, which is common and not onerous, but requires some cleverness to capture. Alternatively, it could clone only those components that do implement clone, although you'd want a warning there.

Initial discussion on solving this in Discord.

The text was updated successfully, but these errors were encountered:

alice-i-cecile · 2021-02-24T22:17:22Z

I think the correct behavior is actually to try to Clone every attached component, and then omit an error (that can either be handled or panic) if it fails. It's unfortunate that it probably has to be runtime, but it should fail very quickly, and you'll want clone on most of your components anyways.

You can further enhance safety by adding archetype invariants (#1481) to the components that can't implement Clone to make them incompatible with the components found on entities you'll want to clone.

alice-i-cecile · 2021-03-05T19:07:55Z

Desired API

/// Clones components from the each entity in `source_entities` onto a new entity
/// If the length of cloned_components is > 0, only the components in that bundle are cloned, if they exist
/// Otherwise, all clone-registered components are used
fn clone_entities(source_entities: Vec<Entity>, cloned_components: Vec<ComponentId>)

Components can be added to each cloned entity using a chained method with the builder pattern. This is commonly needed for differentiating the clone from the orginal.

Joint effort from @cart, @TheRawMeatball and myself on Discord.

alice-i-cecile · 2021-03-05T19:20:45Z

Mock-up implementation by @TheRawMeatball from Discord

type CloneRegistry = Vec<fn(&mut World, Entity, &mut Commands)>
// in impl AppBuilder
fn register_clonable<T: Clone>(&mut self) {
  self.get_resource_mut::<CloneRegistry>().push(|world, entity, commands| {
    if let Ok(c) = world.get::<T>(entity) {
      commands.with(c.clone());
    }
  })
}

struct CloneEntityCommand {
  list: Vec<Entity>
}

impl Command for CloneEntityCommand {
  fn apply(self: Box<Self>, world: &mut World) {
    let registry = world.get_resource_mut::<CloneRegistry>().clone();
    let mut commands = Commands::new();
    commands.spawn();
    for f in registry.into_iter() {
      for e in self.list.into_iter() {
        (f)(world, e, &mut commands);
      }
    }
  }
}

TheRawMeatball · 2021-03-05T23:21:13Z

Can you please use ```rust code fences?

alice-i-cecile · 2021-03-05T23:32:04Z

Can you please use ```rust code fences?

Done. I'd missed that "rs" works on Discord, but not on Github.

Davier · 2021-03-06T01:04:00Z

I think the Clone registration could be part of Reflect, like for Hash, PartialEq and Serialize

Davier · 2021-03-06T01:55:04Z

Actually, it may already be possible using this:

bevy/crates/bevy_ecs/src/reflect.rs

Line 57 in 3a2a688

pub fn copy_component(

It doesn't use Clone at all, instead it applies a reflected component on a new defaulted component.

alice-i-cecile · 2021-04-07T20:09:49Z

More follow-up on related ideas.

alice-i-cecile · 2021-04-10T21:54:07Z

Relevant discussion from Amethyst, discussing the traits needed to get asset serialization / deserialization working.

The ideas around component definitions and data transformation seem particularly transferrable here.

alice-i-cecile · 2021-05-09T18:43:48Z

Another Meatball-y draft impl:

struct EntityCloneSystems(Vec<fn(&mut World, Entity, Entity)>);

fn clone_system<T: Clone + Component>(world: &mut World, target: Entity, reference: Entity) {
    if let Some(v) = world.entity(reference).get::<T>() {
        let v = v.clone();
        world.entity_mut(target).insert(v);
    }
}

// do fancy trait method extension stuff instead
impl AppBuilder {
    pub fn register_clonable<T: Clone + Component>(&mut self) -> &mut Self {
        self.world_mut()
            .get_resource_mut::<EntityCloneSystems>()
            .unwrap()
            .0
            .push(clone_system::<T>);
        self
    }
}
struct CloneEntityCommand(Entity);

impl Command for CloneEntityCommand {
    fn write(self: Box<Self>, world: &mut World) {
        world.resource_scope(|world, systems: Mut<EntityCloneSystems>| {
            let target = world.spawn().id();
            for s in systems.0.iter() {
                s(world, target, self.0);
            }
        })
    }
}

You register a clonable component.
That pushes a cloning function into a resource.
When you go to clone each function is called and attempts to pull out a component, cloning it over if it exists.

GianpaoloBranca · 2023-04-01T09:30:42Z

For anyone struggling with this, here is a gist on how I solved this using the reflections API:
https://gist.github.com/GianpaoloBranca/17e5bd6ada9bdb04cca58182db8505d4

nwtnni · 2023-04-08T05:22:12Z

For anyone struggling with this, here is a gist on how I solved this using the reflections API: https://gist.github.com/GianpaoloBranca/17e5bd6ada9bdb04cca58182db8505d4

Thanks for the reference! I found a way to modify your solution to remove the unsafe code and the &World and &mut World aliasing, but at the cost of a lot more copying and allocating: https://gist.github.com/nwtnni/85d6b87ae75337a522166c500c9a8418.

In particular, this version has to:

Clone all of the source components' ReflectComponent structs (9 function pointers each at time of writing).
Clone each source component via clone_value and clone_dynamic, which seems expensive.

GianpaoloBranca · 2023-04-08T19:17:01Z

Nice approach! I did some quick benchmark and, at least for my use case, it's slower but it's not that slower. Cloning around 1000 entites with 2-4 components each takes roughly 3ms for the unsafe version and 8ms for the safe route.
The values scale linearly with more or less copies.

LIMachi · 2023-11-10T12:07:02Z

Minor fix for the safe version: the aggressive usage of unwrap on the type registry will result in a crash if a component is not reflect, here is a fix (and should probably send an optional warning): .filter_map(|type_id| { registry .get(type_id) .and_then(|registered_type| { registered_type.data::<ReflectComponent>() }) .map(|component| { component.clone() }) }) (by using a filtermap and removing the unwraps, I managed to skip invalid components, but I'm unsure if this the best way of doing this)

Multirious · 2024-02-16T14:43:50Z

I'ved modified the unsafe version a bit to account for children. The added part can be used for the safe version because it do not uses any unsafe block.

Updated clone_entity_components to skip parent and children component to stop from making invalid hierarchy.
Added clone_entity_recursive to clone an entity and their children.

https://gist.github.com/Multirious/ff049b368cfe7e9df130bdf59f14e777

Edit: after been using this for awhile, I've come across that there's some caveat like you cannot access the children in the same system with this method because of the Commands deferred nature.

Edit 2: Solved the above by creating empty entities and storing their ids to a tree data structure to be use by user.
Note: Clone components from the tree first before doing any modification to the destination entities!

https://gist.github.com/Multirious/f3fd24d4ce882085f295f80cffe4fe4e

blueforesticarus · 2024-04-23T14:13:58Z

Slightly different from this issue, but related and simpler: is there a way to merge entities.

ie. move all components of entity A into entity B, and destroy entity A

presumably this could work without reflect or even clone

alice-i-cecile · 2024-04-23T15:23:40Z

Not easily. Might be possible by playing with the internals however.

## Objective Fixes #1515 This PR implements a flexible entity cloning system. The primary use case for it is to clone dynamically-generated entities. Example: ```rs #[derive(Component, Clone)] pub struct Projectile; #[derive(Component, Clone)] pub struct Damage { value: f32, } fn player_input( mut commands: Commands, projectiles: Query<Entity, With<Projectile>>, input: Res<ButtonInput<KeyCode>>, ) { // Fire a projectile if input.just_pressed(KeyCode::KeyF) { commands.spawn((Projectile, Damage { value: 10.0 })); } // Triplicate all active projectiles if input.just_pressed(KeyCode::KeyT) { for projectile in projectiles.iter() { // To triplicate a projectile we need to create 2 more clones for _ in 0..2{ commands.clone_entity(projectile) } } } } ``` ## Solution ### Commands Add a `clone_entity` command to create a clone of an entity with all components that can be cloned. Components that can't be cloned will be ignored. ```rs commands.clone_entity(entity) ``` If there is a need to configure the cloning process (like set to clone recursively), there is a second command: ```rs commands.clone_entity_with(entity, |builder| { builder.recursive(true) }); ``` Both of these commands return `EntityCommands` of the cloned entity, so the copy can be modified afterwards. ### Builder All these commands use `EntityCloneBuilder` internally. If there is a need to clone an entity using `World` instead, it is also possible: ```rs let entity = world.spawn(Component).id(); let entity_clone = world.spawn_empty().id(); EntityCloneBuilder::new(&mut world).clone_entity(entity, entity_clone); ``` Builder has methods to `allow` or `deny` certain components during cloning if required and can be extended by implementing traits on it. This PR includes two `EntityCloneBuilder` extensions: `CloneEntityWithObserversExt` to configure adding cloned entity to observers of the original entity, and `CloneEntityRecursiveExt` to configure cloning an entity recursively. ### Clone implementations By default, all components that implement either `Clone` or `Reflect` will be cloned (with `Clone`-based implementation preferred in case component implements both). This can be overriden on a per-component basis: ```rs impl Component for SomeComponent { const STORAGE_TYPE: StorageType = StorageType::Table; fn get_component_clone_handler() -> ComponentCloneHandler { // Don't clone this component ComponentCloneHandler::Ignore } } ``` ### `ComponentCloneHandlers` Clone implementation specified in `get_component_clone_handler` will get registered in `ComponentCloneHandlers` (stored in `bevy_ecs::component::Components`) at component registration time. The clone handler implementation provided by a component can be overriden after registration like so: ```rs let component_id = world.components().component_id::<Component>().unwrap() world.get_component_clone_handlers_mut() .set_component_handler(component_id, ComponentCloneHandler::Custom(component_clone_custom)) ``` The default clone handler for all components that do not explicitly define one (or don't derive `Component`) is `component_clone_via_reflect` if `bevy_reflect` feature is enabled, and `component_clone_ignore` (noop) otherwise. Default handler can be overriden using `ComponentCloneHandlers::set_default_handler` ### Handlers Component clone handlers can be used to modify component cloning behavior. The general signature for a handler that can be used in `ComponentCloneHandler::Custom` is as follows: ```rs pub fn component_clone_custom( world: &mut DeferredWorld, entity_cloner: &EntityCloner, ) { // implementation } ``` The `EntityCloner` implementation (used internally by `EntityCloneBuilder`) assumes that after calling this custom handler, the `target` entity has the desired version of the component from the `source` entity. ### Builder handler overrides Besides component-defined and world-overriden handlers, `EntityCloneBuilder` also has a way to override handlers locally. It is mainly used to allow configuration methods like `recursive` and `add_observers`. ```rs // From observer clone handler implementation impl CloneEntityWithObserversExt for EntityCloneBuilder<'_> { fn add_observers(&mut self, add_observers: bool) -> &mut Self { if add_observers { self.override_component_clone_handler::<ObservedBy>(ComponentCloneHandler::Custom( component_clone_observed_by, )) } else { self.remove_component_clone_handler_override::<ObservedBy>() } } } ``` ## Testing Includes some basic functionality tests and doctests. Performance-wise this feature is the same as calling `clone` followed by `insert` for every entity component. There is also some inherent overhead due to every component clone handler having to access component data through `World`, but this can be reduced without breaking current public API in a later PR.

## Objective Fixes bevyengine#1515 This PR implements a flexible entity cloning system. The primary use case for it is to clone dynamically-generated entities. Example: ```rs #[derive(Component, Clone)] pub struct Projectile; #[derive(Component, Clone)] pub struct Damage { value: f32, } fn player_input( mut commands: Commands, projectiles: Query<Entity, With<Projectile>>, input: Res<ButtonInput<KeyCode>>, ) { // Fire a projectile if input.just_pressed(KeyCode::KeyF) { commands.spawn((Projectile, Damage { value: 10.0 })); } // Triplicate all active projectiles if input.just_pressed(KeyCode::KeyT) { for projectile in projectiles.iter() { // To triplicate a projectile we need to create 2 more clones for _ in 0..2{ commands.clone_entity(projectile) } } } } ``` ## Solution ### Commands Add a `clone_entity` command to create a clone of an entity with all components that can be cloned. Components that can't be cloned will be ignored. ```rs commands.clone_entity(entity) ``` If there is a need to configure the cloning process (like set to clone recursively), there is a second command: ```rs commands.clone_entity_with(entity, |builder| { builder.recursive(true) }); ``` Both of these commands return `EntityCommands` of the cloned entity, so the copy can be modified afterwards. ### Builder All these commands use `EntityCloneBuilder` internally. If there is a need to clone an entity using `World` instead, it is also possible: ```rs let entity = world.spawn(Component).id(); let entity_clone = world.spawn_empty().id(); EntityCloneBuilder::new(&mut world).clone_entity(entity, entity_clone); ``` Builder has methods to `allow` or `deny` certain components during cloning if required and can be extended by implementing traits on it. This PR includes two `EntityCloneBuilder` extensions: `CloneEntityWithObserversExt` to configure adding cloned entity to observers of the original entity, and `CloneEntityRecursiveExt` to configure cloning an entity recursively. ### Clone implementations By default, all components that implement either `Clone` or `Reflect` will be cloned (with `Clone`-based implementation preferred in case component implements both). This can be overriden on a per-component basis: ```rs impl Component for SomeComponent { const STORAGE_TYPE: StorageType = StorageType::Table; fn get_component_clone_handler() -> ComponentCloneHandler { // Don't clone this component ComponentCloneHandler::Ignore } } ``` ### `ComponentCloneHandlers` Clone implementation specified in `get_component_clone_handler` will get registered in `ComponentCloneHandlers` (stored in `bevy_ecs::component::Components`) at component registration time. The clone handler implementation provided by a component can be overriden after registration like so: ```rs let component_id = world.components().component_id::<Component>().unwrap() world.get_component_clone_handlers_mut() .set_component_handler(component_id, ComponentCloneHandler::Custom(component_clone_custom)) ``` The default clone handler for all components that do not explicitly define one (or don't derive `Component`) is `component_clone_via_reflect` if `bevy_reflect` feature is enabled, and `component_clone_ignore` (noop) otherwise. Default handler can be overriden using `ComponentCloneHandlers::set_default_handler` ### Handlers Component clone handlers can be used to modify component cloning behavior. The general signature for a handler that can be used in `ComponentCloneHandler::Custom` is as follows: ```rs pub fn component_clone_custom( world: &mut DeferredWorld, entity_cloner: &EntityCloner, ) { // implementation } ``` The `EntityCloner` implementation (used internally by `EntityCloneBuilder`) assumes that after calling this custom handler, the `target` entity has the desired version of the component from the `source` entity. ### Builder handler overrides Besides component-defined and world-overriden handlers, `EntityCloneBuilder` also has a way to override handlers locally. It is mainly used to allow configuration methods like `recursive` and `add_observers`. ```rs // From observer clone handler implementation impl CloneEntityWithObserversExt for EntityCloneBuilder<'_> { fn add_observers(&mut self, add_observers: bool) -> &mut Self { if add_observers { self.override_component_clone_handler::<ObservedBy>(ComponentCloneHandler::Custom( component_clone_observed_by, )) } else { self.remove_component_clone_handler_override::<ObservedBy>() } } } ``` ## Testing Includes some basic functionality tests and doctests. Performance-wise this feature is the same as calling `clone` followed by `insert` for every entity component. There is also some inherent overhead due to every component clone handler having to access component data through `World`, but this can be reduced without breaking current public API in a later PR.

alice-i-cecile added A-ECS Entities, components, systems, and events C-Feature A new feature, making something new possible C-Usability A targeted quality-of-life change that makes Bevy easier to use labels Feb 24, 2021

alice-i-cecile mentioned this issue Apr 7, 2021

Make Component opt-in #1843

Closed

alice-i-cecile added the A-Reflection Runtime information about types label Apr 14, 2021

alice-i-cecile added the S-Needs-Design-Doc This issue or PR is particularly complex, and needs an approved design doc before it can be merged label Apr 23, 2021

alice-i-cecile mentioned this issue Nov 30, 2021

Better tools for working with dynamic collections of components #3227

Open

alice-i-cecile mentioned this issue Dec 18, 2021

Reflection allows users to clone arbitrary reflected components, but Reflect does not have a Clone bound #3372

Closed

alice-i-cecile mentioned this issue Jan 16, 2022

Clone-able ECS storage #3703

Closed

This was referenced Feb 10, 2022

Add CloneBundle command #3820

Closed

Automatically register types for Reflect #3936

Open

alice-i-cecile mentioned this issue May 5, 2022

Schematics - An abstraction layer for stable scene representation and exposing ECS configuration in the editor #3877

Open

MrGVSV added this to Reflection Oct 15, 2022

MrGVSV moved this to Open in Reflection Oct 15, 2022

alice-i-cecile mentioned this issue Apr 15, 2024

Bevy's bundle types should implement Clone where possible #12985

Closed

alice-i-cecile mentioned this issue Apr 28, 2024

Add World::entity_scope to split the borrow on the World by extracting a single entity #13128

Open

eugineerd mentioned this issue Oct 28, 2024

Entity cloning #16132

Merged

alice-i-cecile mentioned this issue Nov 30, 2024

Add an API to clone worlds #16559

Open

alice-i-cecile closed this as completed in #16132 Dec 3, 2024

github-project-automation bot moved this from Open to Done in Reflection Dec 3, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Command to clone entities #1515

Command to clone entities #1515

alice-i-cecile commented Feb 24, 2021 •

edited

Loading

alice-i-cecile commented Feb 24, 2021

alice-i-cecile commented Mar 5, 2021 •

edited

Loading

alice-i-cecile commented Mar 5, 2021 •

edited

Loading

TheRawMeatball commented Mar 5, 2021

alice-i-cecile commented Mar 5, 2021

Davier commented Mar 6, 2021

Davier commented Mar 6, 2021

alice-i-cecile commented Apr 7, 2021

alice-i-cecile commented Apr 10, 2021

alice-i-cecile commented May 9, 2021

GianpaoloBranca commented Apr 1, 2023

nwtnni commented Apr 8, 2023

GianpaoloBranca commented Apr 8, 2023 •

edited

Loading

LIMachi commented Nov 10, 2023 •

edited

Loading

Multirious commented Feb 16, 2024 •

edited

Loading

blueforesticarus commented Apr 23, 2024 •

edited

Loading

alice-i-cecile commented Apr 23, 2024

Command to clone entities #1515

Command to clone entities #1515

Comments

alice-i-cecile commented Feb 24, 2021 • edited Loading

What problem does this solve or what need does it fill?

What solution would you like?

What alternative(s) have you considered?

Additional context

alice-i-cecile commented Feb 24, 2021

alice-i-cecile commented Mar 5, 2021 • edited Loading

Desired API

alice-i-cecile commented Mar 5, 2021 • edited Loading

TheRawMeatball commented Mar 5, 2021

alice-i-cecile commented Mar 5, 2021

Davier commented Mar 6, 2021

Davier commented Mar 6, 2021

alice-i-cecile commented Apr 7, 2021

alice-i-cecile commented Apr 10, 2021

alice-i-cecile commented May 9, 2021

GianpaoloBranca commented Apr 1, 2023

nwtnni commented Apr 8, 2023

GianpaoloBranca commented Apr 8, 2023 • edited Loading

LIMachi commented Nov 10, 2023 • edited Loading

Multirious commented Feb 16, 2024 • edited Loading

blueforesticarus commented Apr 23, 2024 • edited Loading

alice-i-cecile commented Apr 23, 2024

alice-i-cecile commented Feb 24, 2021 •

edited

Loading

alice-i-cecile commented Mar 5, 2021 •

edited

Loading

alice-i-cecile commented Mar 5, 2021 •

edited

Loading

GianpaoloBranca commented Apr 8, 2023 •

edited

Loading

LIMachi commented Nov 10, 2023 •

edited

Loading

Multirious commented Feb 16, 2024 •

edited

Loading

blueforesticarus commented Apr 23, 2024 •

edited

Loading