Entity cloning

[eugineerd]

Objective

Fixes #1515

This PR implements a flexible entity cloning system. The primary use case for it is to clone dynamically-generated entities.

Example:

#[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.

commands.clone_entity(entity)

If there is a need to configure the cloning process (like set to clone recursively), there is a second command:

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:

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:

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:

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:

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.

// 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]

I have wanted this feature for years. Thank you so much for taking a crack at it! I don't have time to thoroughly review this right now, but please pester me during 0.16 to make sure this gets merged.

[chescock]

This seems really useful! I have some nits and suggestions, but nothing that should block it.

[chescock]

Would it make sense to have a helper method that calls set_component_handler(id, component_clone_via_clone::<C>) with the correct id? You couldn't put it on ComponentCloneHandlers since you can't get the component_id from that, but you could put it on World or Components.

[eugineerd]

I'm not sure how useful that will be. I though that most users would not need to add component_clone_via_clone handlers at runtime, instead they would manually impl Clone for a component or set a handler in get_component_clone_handler. Is it for components with conditional Clone implementation with generics?

[chescock]

Yeah, I was thinking about the conditional Clone implementations. One of the reasons it seems perfectly fine to use default cloning in that case is that anyone who really needs component_clone_via_clone can just register it for the concrete component types! But I agree that's likely to be rare, so it's probably not worth adding extra methods for it unless we see folks doing that in the wild.

[eugineerd]

I did some basic profiling to see how cloning compares to just spawning an entity and performance is not that great (all time is relative to total runtime, as reported by perf):

• Spawning 100 000 entities with 10 Clone-able components took ~15% of runtime, while cloning the entities took ~80% of runtime.
• ComponentCloneHandlers::get_handler is surprisingly slow ~4.2% of runtime is spent there. This can be optimized by replacing HashMap by Vec and using ComponentId as index. This would increase the memory footprint a bit, but since Components uses the same trick to store ComponentInfo I think it should be fine.
• ~53% of time is spent inside EntityWorldMut::insert. This can be reduced by avoiding archetype moves with some unsafe code inserting all components using EntityWorldMut::insert_by_ids and changing ComponentCloneHandlers to do cloning by providing them with a pointer where to write the cloned value.
• ~8.2% of time is spent allocating a Vec for ComponentIds. This seems to go down to ~2.2% if I preallocate Vec using Archetype::component_count. Maybe Archetype::components doesn't give correct size hint to the iterator? I'm not sure.

I think optimizations for ComponentCloneHandlers::get_handler and ComponentId allocations can be added to this PR, but what about optimizing component insertion? Should it also be done in this PR or maybe this can be added later (along with batch cloning)?

[chescock]

• ~8.2% of time is spent allocating a Vec for ComponentIds. This seems to go down to ~2.2% if I preallocate Vec using Archetype::component_count. Maybe Archetype::components doesn't give correct size hint to the iterator? I'm not sure.

Oh, sorry, I bet this was due to my suggestion to use filter there!

Should it also be done in this PR or maybe this can be added later (along with batch cloning)?

I'm not a maintainer, but I vote for merging this first and doing performance improvements as a follow-up, especially if you don't expect the perf improvements to change the public API. That lets it get used sooner in places where the current perf is already good enough!

[eugineerd]

especially if you don't expect the perf improvements to change the public API.

I think from the current public API only custom clone handlers (ComponentCloneFn) and EntityCloner might not have enough information/are too flexible (giving &mut World to handlers) to implement cloning more efficiently. I have a prototype that 2x the cloning performance (and I expect there are ways to improve it even more), however it is very unsafe and I don't yet know how to implement it safely in user-friendly way.

Thinking about it a bit more though, maybe the current flexible API can co-exist with the new more optimized but limited API that will be implemented later.

[eugineerd]

Made all clone handlers use DeferredWorld instead of normal World in hopes of optimizing later without making breaking changes. Disallowing structural ECS changes would allow clone handlers to read component data from entity row in the table/sparse set without having to go through the World first. This requires a bit of unsafe and this PR already feels big enough, so I think it would be best to do that as a follow-up.

[alice-i-cecile]

Really impressive work: this is well-documented and engineered, and strikes a great balance between sensible defaults and the ability to configure more complex use cases. Merging! We can optimize this in follow-up.