Trait valence::ecs::reflect::ReflectCommandExt

pub trait ReflectCommandExt {
    // Required methods
    fn insert_reflect(&mut self, component: Box<dyn Reflect>) -> &mut Self;
    fn insert_reflect_with_registry<T>(
        &mut self,
        component: Box<dyn Reflect>,
    ) -> &mut Self
       where T: Resource + AsRef<TypeRegistry>;
    fn remove_reflect(
        &mut self,
        component_type_name: impl Into<Cow<'static, str>>,
    ) -> &mut Self;
    fn remove_reflect_with_registry<T>(
        &mut self,
        component_type_name: impl Into<Cow<'static, str>>,
    ) -> &mut Self
       where T: Resource + AsRef<TypeRegistry>;
}
Expand description

An extension trait for EntityCommands for reflection related functions

Required Methods§

fn insert_reflect(&mut self, component: Box<dyn Reflect>) -> &mut Self

Adds the given boxed reflect component to the entity using the reflection data in AppTypeRegistry.

This will overwrite any previous component of the same type.

§Panics
  • If the entity doesn’t exist.
  • If AppTypeRegistry does not have the reflection data for the given Component.
  • If the component data is invalid. See [Reflect::apply] for further details.
  • If AppTypeRegistry is not present in the World.
§Note

Prefer to use the typed EntityCommands::insert if possible. Adding a reflected component is much slower.

§Example
// Note that you need to register the component type in the AppTypeRegistry prior to using
// reflection. You can use the helpers on the App with `app.register_type::<ComponentA>()`
// or write to the TypeRegistry directly to register all your components

// A resource that can hold any component that implements reflect as a boxed reflect component
#[derive(Resource)]
struct Prefab{
    component: Box<dyn Reflect>,
}
#[derive(Component, Reflect, Default)]
#[reflect(Component)]
struct ComponentA(u32);

#[derive(Component, Reflect, Default)]
#[reflect(Component)]
struct ComponentB(String);

fn insert_reflect_component(
    mut commands: Commands,
    mut prefab: ResMut<Prefab>
    ) {
    // Create a set of new boxed reflect components to use
    let boxed_reflect_component_a: Box<dyn Reflect> = Box::new(ComponentA(916));
    let boxed_reflect_component_b: Box<dyn Reflect>  = Box::new(ComponentB("NineSixteen".to_string()));

    // You can overwrite the component in the resource with either ComponentA or ComponentB
    prefab.component = boxed_reflect_component_a;
    prefab.component = boxed_reflect_component_b;
     
    // No matter which component is in the resource and without knowing the exact type, you can
    // use the insert_reflect entity command to insert that component into an entity.
    commands
        .spawn_empty()
        .insert_reflect(prefab.component.clone_value());
}

fn insert_reflect_with_registry<T>( &mut self, component: Box<dyn Reflect>, ) -> &mut Self
where T: Resource + AsRef<TypeRegistry>,

Same as insert_reflect, but using the T resource as type registry instead of AppTypeRegistry.

§Panics
§Note
  • The given Resource is removed from the World before the command is applied.

fn remove_reflect( &mut self, component_type_name: impl Into<Cow<'static, str>>, ) -> &mut Self

Removes from the entity the component with the given type name registered in AppTypeRegistry.

Does nothing if the entity does not have a component of the same type, if AppTypeRegistry does not contain the reflection data for the given component, or if the entity does not exist.

§Note

Prefer to use the typed EntityCommands::remove if possible. Removing a reflected component is much slower.

§Example
// Note that you need to register the component type in the AppTypeRegistry prior to using
// reflection. You can use the helpers on the App with `app.register_type::<ComponentA>()`
// or write to the TypeRegistry directly to register all your components


// A resource that can hold any component that implements reflect as a boxed reflect component
#[derive(Resource)]
struct Prefab{
    entity: Entity,
    component: Box<dyn Reflect>,
}
#[derive(Component, Reflect, Default)]
#[reflect(Component)]
struct ComponentA(u32);
#[derive(Component, Reflect, Default)]
#[reflect(Component)]
struct ComponentB(String);

fn remove_reflect_component(
    mut commands: Commands,
    prefab: Res<Prefab>
    ) {
    // Prefab can hold any boxed reflect component. In this case either
    // ComponentA or ComponentB. No matter which component is in the resource though,
    // we can attempt to remove any component of that same type from an entity.
    commands.entity(prefab.entity)
        .remove_reflect(prefab.component.reflect_type_path().to_owned());
}

fn remove_reflect_with_registry<T>( &mut self, component_type_name: impl Into<Cow<'static, str>>, ) -> &mut Self
where T: Resource + AsRef<TypeRegistry>,

Same as remove_reflect, but using the T resource as type registry instead of AppTypeRegistry.

Object Safety§

This trait is not object safe.

Implementors§