Struct EntityCloner

pub struct EntityCloner { /* private fields */ }

A configuration determining how to clone entities. This can be built using EntityCloner::build, which returns an EntityClonerBuilder.

After configuration is complete an entity can be cloned using Self::clone_entity.

 use bevy_ecs::prelude::*;
 use bevy_ecs::entity::EntityCloner;

 #[derive(Component, Clone, PartialEq, Eq)]
 struct A {
     field: usize,
 }

 let mut world = World::default();

 let component = A { field: 5 };

 let entity = world.spawn(component.clone()).id();
 let entity_clone = world.spawn_empty().id();

 EntityCloner::build(&mut world).clone_entity(entity, entity_clone);

 assert!(world.get::<A>(entity_clone).is_some_and(|c| *c == component));

Default cloning strategy

By default, all types that derive Component and implement either Clone or Reflect (with ReflectComponent) will be cloned (with Clone-based implementation preferred in case component implements both).

It should be noted that if Component is implemented manually or if Clone implementation is conditional (like when deriving Clone for a type with a generic parameter without Clone bound), the component will be cloned using the default cloning strategy. To use Clone-based handler (ComponentCloneBehavior::clone) in this case it should be set manually using one of the methods mentioned in the Clone Behaviors section

Here’s an example of how to do it using clone_behavior:

#[derive(Clone)]
struct SomeComponent;

impl Component for SomeComponent {
    const STORAGE_TYPE: StorageType = StorageType::Table;
    type Mutability = Mutable;
    fn clone_behavior() -> ComponentCloneBehavior {
        ComponentCloneBehavior::clone::<Self>()
    }
}

Clone Behaviors

EntityCloner clones entities by cloning components using ComponentCloneBehavior, and there are multiple layers to decide which handler to use for which component. The overall hierarchy looks like this (priority from most to least):

1. local overrides using EntityClonerBuilder::override_clone_behavior
2. component-defined handler using Component::clone_behavior
3. default handler override using EntityClonerBuilder::with_default_clone_fn.
4. reflect-based or noop default clone handler depending on if bevy_reflect feature is enabled or not.

Implementations

impl EntityCloner

pub fn build(world: &mut World) -> EntityClonerBuilder<'_>

Returns a new EntityClonerBuilder using the given world.

pub fn linked_cloning(&self) -> bool

Returns true if this cloner is configured to clone entities referenced in cloned components via RelationshipTarget::LINKED_SPAWN. This will produce “deep” / recursive clones of relationship trees that have “linked spawn”.

pub fn clone_entity( &mut self, world: &mut World, source: Entity, target: Entity, )

Clones and inserts components from the source entity into target entity using the stored configuration. If this EntityCloner has EntityCloner::linked_cloning, then it will recursively spawn entities as defined by RelationshipTarget components with RelationshipTarget::LINKED_SPAWN

pub fn spawn_clone(&mut self, world: &mut World, source: Entity) -> Entity

Clones and inserts components from the source entity into a newly spawned entity using the stored configuration. If this EntityCloner has EntityCloner::linked_cloning, then it will recursively spawn entities as defined by RelationshipTarget components with RelationshipTarget::LINKED_SPAWN

pub fn clone_entity_mapped( &mut self, world: &mut World, source: Entity, mapper: &mut dyn EntityMapper, ) -> Entity

Clones the entity into whatever entity mapper chooses for it.

Trait Implementations

impl Default for EntityCloner

fn default() -> EntityCloner

Returns the “default value” for a type.