Struct EntityCloner 

pub struct EntityCloner { /* private fields */ }

A configuration determining how to clone entities. This can be built using EntityCloner::build_opt_out/ opt_in, 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_opt_out(&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, Component)]
#[component(clone_behavior = clone::<Self>())]
struct SomeComponent;

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.

Moving components

EntityCloner can be configured to move components instead of cloning them by using EntityClonerBuilder::move_components. In this mode components will be moved - removed from source entity and added to the target entity.

Components with ComponentCloneBehavior::Ignore clone behavior will not be moved, while components that have a ComponentCloneBehavior::Custom clone behavior will be cloned using it and then removed from the source entity. All other components will be bitwise copied from the source entity onto the target entity and then removed without dropping.

Choosing to move components instead of cloning makes EntityClonerBuilder::with_default_clone_fn ineffective since it’s replaced by move handler for components that have ComponentCloneBehavior::Default clone behavior.

Note that moving components still triggers on_remove hooks/observers on source entity and on_insert/on_add hooks/observers on the target entity.

Implementations

impl EntityCloner

pub fn build_opt_out(world: &mut World) -> EntityClonerBuilder<'_, OptOut>

Returns a new EntityClonerBuilder using the given world with the OptOut configuration.

This builder tries to clone every component from the source entity except for components that were explicitly denied, for example by using the deny method.

Required components are not considered by denied components and must be explicitly denied as well if desired.

pub fn build_opt_in(world: &mut World) -> EntityClonerBuilder<'_, OptIn>

Returns a new EntityClonerBuilder using the given world with the OptIn configuration.

This builder tries to clone every component that was explicitly allowed from the source entity, for example by using the allow method.

Components allowed to be cloned through this builder would also allow their required components, which will be cloned from the source entity only if the target entity does not contain them already. To skip adding required components see without_required_components.

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.