Trait Component

Source

pub trait Component:
    Send
    + Sync
    + 'static {
    const STORAGE_TYPE: StorageType;

    // Provided methods
    fn register_component_hooks(_hooks: &mut ComponentHooks) { ... }
    fn register_required_components(
        _component_id: ComponentId,
        _components: &mut Components,
        _storages: &mut Storages,
        _required_components: &mut RequiredComponents,
        _inheritance_depth: u16,
    ) { ... }
}

Expand description

A data type that can be used to store data for an entity.

Component is a derivable trait: this means that a data type can implement it by applying a #[derive(Component)] attribute to it. However, components must always satisfy the Send + Sync + 'static trait bounds.

§Examples

Components can take many forms: they are usually structs, but can also be of every other kind of data type, like enums or zero sized types. The following examples show how components are laid out in code.

// A component can contain data...
#[derive(Component)]
struct LicensePlate(String);

// ... but it can also be a zero-sized marker.
#[derive(Component)]
struct Car;

// Components can also be structs with named fields...
#[derive(Component)]
struct VehiclePerformance {
    acceleration: f32,
    top_speed: f32,
    handling: f32,
}

// ... or enums.
#[derive(Component)]
enum WheelCount {
    Two,
    Three,
    Four,
}

§Component and data access

See the entity module level documentation to learn how to add or remove components from an entity.

See the documentation for Query to learn how to access component data from a system.

§Choosing a storage type

Components can be stored in the world using different strategies with their own performance implications. By default, components are added to the Table storage, which is optimized for query iteration.

Alternatively, components can be added to the SparseSet storage, which is optimized for component insertion and removal. This is achieved by adding an additional #[component(storage = "SparseSet")] attribute to the derive one:

#[derive(Component)]
#[component(storage = "SparseSet")]
struct ComponentA;

§Required Components

Components can specify Required Components. If some Component A requires Component B, then when A is inserted, B will also be initialized and inserted (if it was not manually specified).

The Default constructor will be used to initialize the component, by default:

#[derive(Component)]
#[require(B)]
struct A;

#[derive(Component, Default, PartialEq, Eq, Debug)]
struct B(usize);

// This will implicitly also insert B with the Default constructor
let id = world.spawn(A).id();
assert_eq!(&B(0), world.entity(id).get::<B>().unwrap());

// This will _not_ implicitly insert B, because it was already provided
world.spawn((A, B(11)));

Components can have more than one required component:

#[derive(Component)]
#[require(B, C)]
struct A;

#[derive(Component, Default, PartialEq, Eq, Debug)]
#[require(C)]
struct B(usize);

#[derive(Component, Default, PartialEq, Eq, Debug)]
struct C(u32);

// This will implicitly also insert B and C with their Default constructors
let id = world.spawn(A).id();
assert_eq!(&B(0), world.entity(id).get::<B>().unwrap());
assert_eq!(&C(0), world.entity(id).get::<C>().unwrap());

You can also define a custom constructor function or closure:

#[derive(Component)]
#[require(C(init_c))]
struct A;

#[derive(Component, PartialEq, Eq, Debug)]
#[require(C(|| C(20)))]
struct B;

#[derive(Component, PartialEq, Eq, Debug)]
struct C(usize);

fn init_c() -> C {
    C(10)
}

// This will implicitly also insert C with the init_c() constructor
let id = world.spawn(A).id();
assert_eq!(&C(10), world.entity(id).get::<C>().unwrap());

// This will implicitly also insert C with the `|| C(20)` constructor closure
let id = world.spawn(B).id();
assert_eq!(&C(20), world.entity(id).get::<C>().unwrap());

Required components are recursive. This means, if a Required Component has required components, those components will also be inserted if they are missing:

#[derive(Component)]
#[require(B)]
struct A;

#[derive(Component, Default, PartialEq, Eq, Debug)]
#[require(C)]
struct B(usize);

#[derive(Component, Default, PartialEq, Eq, Debug)]
struct C(u32);

// This will implicitly also insert B and C with their Default constructors
let id = world.spawn(A).id();
assert_eq!(&B(0), world.entity(id).get::<B>().unwrap());
assert_eq!(&C(0), world.entity(id).get::<C>().unwrap());

Note that cycles in the “component require tree” will result in stack overflows when attempting to insert a component.

This “multiple inheritance” pattern does mean that it is possible to have duplicate requires for a given type at different levels of the inheritance tree:

#[derive(Component)]
struct X(usize);

#[derive(Component, Default)]
#[require(X(|| X(1)))]
struct Y;

#[derive(Component)]
#[require(
    Y,
    X(|| X(2)),
)]
struct Z;

// In this case, the x2 constructor is used for X
let id = world.spawn(Z).id();
assert_eq!(2, world.entity(id).get::<X>().unwrap().0);

In general, this shouldn’t happen often, but when it does the algorithm for choosing the constructor from the tree is simple and predictable:

A constructor from a direct #[require()], if one exists, is selected with priority.
Otherwise, perform a Depth First Search on the tree of requirements and select the first one found.

From a user perspective, just think about this as the following:

Specifying a required component constructor for Foo directly on a spawned component Bar will result in that constructor being used (and overriding existing constructors lower in the inheritance tree). This is the classic “inheritance override” behavior people expect.
For cases where “multiple inheritance” results in constructor clashes, Components should be listed in “importance order”. List a component earlier in the requirement list to initialize its inheritance tree earlier.

§Registering required components at runtime

In most cases, required components should be registered using the require attribute as shown above. However, in some cases, it may be useful to register required components at runtime.

This can be done through World::register_required_components or World::register_required_components_with for the Default and custom constructors respectively:

#[derive(Component)]
struct A;

#[derive(Component, Default, PartialEq, Eq, Debug)]
struct B(usize);

#[derive(Component, PartialEq, Eq, Debug)]
struct C(u32);

// Register B as required by A and C as required by B.
world.register_required_components::<A, B>();
world.register_required_components_with::<B, C>(|| C(2));

// This will implicitly also insert B with its Default constructor
// and C with the custom constructor defined by B.
let id = world.spawn(A).id();
assert_eq!(&B(0), world.entity(id).get::<B>().unwrap());
assert_eq!(&C(2), world.entity(id).get::<C>().unwrap());

Similar rules as before apply to duplicate requires fer a given type at different levels of the inheritance tree. A requiring C directly would take precedence over indirectly requiring it through A requiring B and B requiring C.

Unlike with the require attribute, directly requiring the same component multiple times for the same component will result in a panic. This is done to prevent conflicting constructors and confusing ordering dependencies.

Note that requirements must currently be registered before the requiring component is inserted into the world for the first time. Registering requirements after this will lead to a panic.

§Adding component’s hooks

See ComponentHooks for a detailed explanation of component’s hooks.

Alternatively to the example shown in ComponentHooks’ documentation, hooks can be configured using following attributes:

#[component(on_add = on_add_function)]
#[component(on_insert = on_insert_function)]
#[component(on_replace = on_replace_function)]
#[component(on_remove = on_remove_function)]

#[derive(Component)]
#[component(on_add = my_on_add_hook)]
#[component(on_insert = my_on_insert_hook)]
// Another possible way of configuring hooks:
// #[component(on_add = my_on_add_hook, on_insert = my_on_insert_hook)]
//
// We don't have a replace or remove hook, so we can leave them out:
// #[component(on_replace = my_on_replace_hook, on_remove = my_on_remove_hook)]
struct ComponentA;

fn my_on_add_hook(world: DeferredWorld, entity: Entity, id: ComponentId) {
    // ...
}

// You can also omit writing some types using generics.
fn my_on_insert_hook<T1, T2>(world: DeferredWorld, _: T1, _: T2) {
    // ...
}

§Implementing the trait for foreign types

As a consequence of the orphan rule, it is not possible to separate into two different crates the implementation of Component from the definition of a type. This means that it is not possible to directly have a type defined in a third party library as a component. This important limitation can be easily worked around using the newtype pattern: this makes it possible to locally define and implement Component for a tuple struct that wraps the foreign type. The following example gives a demonstration of this pattern.

// `Component` is defined in the `bevy_ecs` crate.
use bevy_ecs::component::Component;

// `Duration` is defined in the `std` crate.
use std::time::Duration;

// It is not possible to implement `Component` for `Duration` from this position, as they are
// both foreign items, defined in an external crate. However, nothing prevents to define a new
// `Cooldown` type that wraps `Duration`. As `Cooldown` is defined in a local crate, it is
// possible to implement `Component` for it.
#[derive(Component)]
struct Cooldown(Duration);

§`!Sync` Components

A !Sync type cannot implement Component. However, it is possible to wrap a Send but not Sync type in SyncCell or the currently unstable Exclusive to make it Sync. This forces only having mutable access (&mut T only, never &T), but makes it safe to reference across multiple threads.

This will fail to compile since RefCell is !Sync.

#[derive(Component)]
struct NotSync {
   counter: RefCell<usize>,
}

This will compile since the RefCell is wrapped with SyncCell.

use bevy_utils::synccell::SyncCell;

// This will compile.
#[derive(Component)]
struct ActuallySync {
   counter: SyncCell<RefCell<usize>>,
}

Required Associated Constants§

Source

const STORAGE_TYPE: StorageType

A constant indicating the storage type used for this component.

Provided Methods§

Source

fn register_component_hooks(_hooks: &mut ComponentHooks)

Called when registering this component, allowing mutable access to its ComponentHooks.

Source

fn register_required_components( _component_id: ComponentId, _components: &mut Components, _storages: &mut Storages, _required_components: &mut RequiredComponents, _inheritance_depth: u16, )

Registers required components.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Trait ComponentCopy item path

§Examples

§Component and data access

§Choosing a storage type

§Required Components

§Registering required components at runtime

§Adding component’s hooks

§Implementing the trait for foreign types

§!Sync Components

Required Associated Constants§

const STORAGE_TYPE: StorageType

Provided Methods§

fn register_component_hooks(_hooks: &mut ComponentHooks)

fn register_required_components( _component_id: ComponentId, _components: &mut Components, _storages: &mut Storages, _required_components: &mut RequiredComponents, _inheritance_depth: u16, )

Dyn Compatibility§

Implementors§

impl Component for DependencyLoadStatewhere DependencyLoadState: Send + Sync + 'static,

const STORAGE_TYPE: StorageType = bevy_ecs::component::StorageType::Table

impl Component for LoadStatewhere LoadState: Send + Sync + 'static,

const STORAGE_TYPE: StorageType = bevy_ecs::component::StorageType::Table

impl Component for RecursiveDependencyLoadStatewhere RecursiveDependencyLoadState: Send + Sync + 'static,

const STORAGE_TYPE: StorageType = bevy_ecs::component::StorageType::Table

impl Component for DepthOfFieldPipelineswhere DepthOfFieldPipelines: Send + Sync + 'static,

const STORAGE_TYPE: StorageType = bevy_ecs::component::StorageType::Table

impl Component for DebandDitherwhere DebandDither: Send + Sync + 'static,

const STORAGE_TYPE: StorageType = bevy_ecs::component::StorageType::Table

impl Component for Tonemappingwhere Tonemapping: Send + Sync + 'static,

const STORAGE_TYPE: StorageType = bevy_ecs::component::StorageType::Table

impl Component for HierarchyEventwhere HierarchyEvent: Send + Sync + 'static,

const STORAGE_TYPE: StorageType = bevy_ecs::component::StorageType::SparseSet

impl Component for GamepadEventwhere GamepadEvent: Send + Sync + 'static,

const STORAGE_TYPE: StorageType = bevy_ecs::component::StorageType::SparseSet

impl Component for GamepadRumbleRequestwhere GamepadRumbleRequest: Send + Sync + 'static,

const STORAGE_TYPE: StorageType = bevy_ecs::component::StorageType::SparseSet

impl Component for RawGamepadEventwhere RawGamepadEvent: Send + Sync + 'static,

const STORAGE_TYPE: StorageType = bevy_ecs::component::StorageType::SparseSet

impl Component for ClusterConfigwhere ClusterConfig: Send + Sync + 'static,

const STORAGE_TYPE: StorageType = bevy_ecs::component::StorageType::Table

impl Component for LightEntitywhere LightEntity: Send + Sync + 'static,

const STORAGE_TYPE: StorageType = bevy_ecs::component::StorageType::Table

impl Component for ShadowFilteringMethodwhere ShadowFilteringMethod: Send + Sync + 'static,

const STORAGE_TYPE: StorageType = bevy_ecs::component::StorageType::Table

impl Component for PickingInteractionwhere PickingInteraction: Send + Sync + 'static,

const STORAGE_TYPE: StorageType = bevy_ecs::component::StorageType::Table

impl Component for PointerIdwhere PointerId: Send + Sync + 'static,

const STORAGE_TYPE: StorageType = bevy_ecs::component::StorageType::Table

impl Component for AppExitwhere AppExit: Send + Sync + 'static,

const STORAGE_TYPE: StorageType = bevy_ecs::component::StorageType::SparseSet

impl Component for FileDragAndDropwhere FileDragAndDrop: Send + Sync + 'static,

const STORAGE_TYPE: StorageType = bevy_ecs::component::StorageType::SparseSet

impl Component for Imewhere Ime: Send + Sync + 'static,

const STORAGE_TYPE: StorageType = bevy_ecs::component::StorageType::SparseSet

impl Component for Interactionwhere Interaction: Send + Sync + 'static,

const STORAGE_TYPE: StorageType = bevy_ecs::component::StorageType::Table

impl Component for Msaawhere Msaa: Send + Sync + 'static,

const STORAGE_TYPE: StorageType = bevy_ecs::component::StorageType::Table

impl Component for Projectionwhere Projection: Send + Sync + 'static,

const STORAGE_TYPE: StorageType = bevy_ecs::component::StorageType::Table

impl Component for UiAntiAliaswhere UiAntiAlias: Send + Sync + 'static,

const STORAGE_TYPE: StorageType = bevy_ecs::component::StorageType::Table

impl Component for Visibilitywhere Visibility: Send + Sync + 'static,

const STORAGE_TYPE: StorageType = bevy_ecs::component::StorageType::Table

impl Component for Readbackwhere Readback: Send + Sync + 'static,

const STORAGE_TYPE: StorageType = bevy_ecs::component::StorageType::Table

impl Component for Anchorwhere Anchor: Send + Sync + 'static,

const STORAGE_TYPE: StorageType = bevy_ecs::component::StorageType::Table

impl Component for FocusPolicywhere FocusPolicy: Send + Sync + 'static,

const STORAGE_TYPE: StorageType = bevy_ecs::component::StorageType::Table

impl Component for AppLifecyclewhere AppLifecycle: Send + Sync + 'static,

const STORAGE_TYPE: StorageType = bevy_ecs::component::StorageType::SparseSet

impl Component for WindowEventwhere WindowEvent: Send + Sync + 'static,

const STORAGE_TYPE: StorageType = bevy_ecs::component::StorageType::SparseSet

impl Component for CursorIconwhere CursorIcon: Send + Sync + 'static,

const STORAGE_TYPE: StorageType = bevy_ecs::component::StorageType::Table

impl Component for AccessibilityNodewhere AccessibilityNode: Send + Sync + 'static,

const STORAGE_TYPE: StorageType = bevy_ecs::component::StorageType::Table

impl Component for ActionRequestwhere ActionRequest: Send + Sync + 'static,

const STORAGE_TYPE: StorageType = bevy_ecs::component::StorageType::SparseSet

impl Component for AnimationTargetwhere AnimationTarget: Send + Sync + 'static,

const STORAGE_TYPE: StorageType = bevy_ecs::component::StorageType::Table

Trait Component

§`!Sync` Components

impl Component for DependencyLoadState
where DependencyLoadState: Send + Sync + 'static,

impl Component for LoadState
where LoadState: Send + Sync + 'static,

impl Component for RecursiveDependencyLoadState
where RecursiveDependencyLoadState: Send + Sync + 'static,

impl Component for DepthOfFieldPipelines
where DepthOfFieldPipelines: Send + Sync + 'static,

impl Component for DebandDither
where DebandDither: Send + Sync + 'static,

impl Component for Tonemapping
where Tonemapping: Send + Sync + 'static,

impl Component for HierarchyEvent
where HierarchyEvent: Send + Sync + 'static,

impl Component for GamepadEvent
where GamepadEvent: Send + Sync + 'static,

impl Component for GamepadRumbleRequest
where GamepadRumbleRequest: Send + Sync + 'static,

impl Component for RawGamepadEvent
where RawGamepadEvent: Send + Sync + 'static,

impl Component for ClusterConfig
where ClusterConfig: Send + Sync + 'static,

impl Component for LightEntity
where LightEntity: Send + Sync + 'static,

impl Component for ShadowFilteringMethod
where ShadowFilteringMethod: Send + Sync + 'static,

impl Component for PickingInteraction
where PickingInteraction: Send + Sync + 'static,

impl Component for PointerId
where PointerId: Send + Sync + 'static,

impl Component for AppExit
where AppExit: Send + Sync + 'static,

impl Component for FileDragAndDrop
where FileDragAndDrop: Send + Sync + 'static,

impl Component for Ime
where Ime: Send + Sync + 'static,

impl Component for Interaction
where Interaction: Send + Sync + 'static,

impl Component for Msaa
where Msaa: Send + Sync + 'static,

impl Component for Projection
where Projection: Send + Sync + 'static,

impl Component for UiAntiAlias
where UiAntiAlias: Send + Sync + 'static,

impl Component for Visibility
where Visibility: Send + Sync + 'static,

impl Component for Readback
where Readback: Send + Sync + 'static,

impl Component for Anchor
where Anchor: Send + Sync + 'static,

impl Component for FocusPolicy
where FocusPolicy: Send + Sync + 'static,

impl Component for AppLifecycle
where AppLifecycle: Send + Sync + 'static,

impl Component for WindowEvent
where WindowEvent: Send + Sync + 'static,

impl Component for CursorIcon
where CursorIcon: Send + Sync + 'static,

impl Component for AccessibilityNode
where AccessibilityNode: Send + Sync + 'static,

impl Component for ActionRequest
where ActionRequest: Send + Sync + 'static,

impl Component for AnimationTarget
where AnimationTarget: Send + Sync + 'static,

impl Component for UntypedAssetLoadFailedEvent
where UntypedAssetLoadFailedEvent: Send + Sync + 'static,

impl Component for AutoExposure
where AutoExposure: Send + Sync + 'static,

impl Component for Bloom
where Bloom: Send + Sync + 'static,

impl Component for ContrastAdaptiveSharpening
where ContrastAdaptiveSharpening: Send + Sync + 'static,

impl Component for DenoiseCas
where DenoiseCas: Send + Sync + 'static,

impl Component for ViewCasPipeline
where ViewCasPipeline: Send + Sync + 'static,

impl Component for ViewTransmissionTexture
where ViewTransmissionTexture: Send + Sync + 'static,

impl Component for DeferredLightingIdDepthTexture
where DeferredLightingIdDepthTexture: Send + Sync + 'static,

impl Component for AuxiliaryDepthOfFieldTexture
where AuxiliaryDepthOfFieldTexture: Send + Sync + 'static,

impl Component for DepthOfField
where DepthOfField: Send + Sync + 'static,

impl Component for DepthOfFieldUniform
where DepthOfFieldUniform: Send + Sync + 'static,

impl Component for ViewDepthOfFieldBindGroupLayouts
where ViewDepthOfFieldBindGroupLayouts: Send + Sync + 'static,

impl Component for TemporalAntiAliasing
where TemporalAntiAliasing: Send + Sync + 'static,

impl Component for CameraFxaaPipeline
where CameraFxaaPipeline: Send + Sync + 'static,

impl Component for Fxaa
where Fxaa: Send + Sync + 'static,

impl Component for MotionBlurPipelineId
where MotionBlurPipelineId: Send + Sync + 'static,

impl Component for MotionBlur
where MotionBlur: Send + Sync + 'static,

impl Component for MsaaWritebackBlitPipeline
where MsaaWritebackBlitPipeline: Send + Sync + 'static,

impl Component for OitResolvePipelineId
where OitResolvePipelineId: Send + Sync + 'static,

impl Component for OrderIndependentTransparencySettingsOffset
where OrderIndependentTransparencySettingsOffset: Send + Sync + 'static,

impl Component for ChromaticAberration
where ChromaticAberration: Send + Sync + 'static,

impl Component for PostProcessingPipelineId
where PostProcessingPipelineId: Send + Sync + 'static,

impl Component for PostProcessingUniformBufferOffsets
where PostProcessingUniformBufferOffsets: Send + Sync + 'static,

impl Component for DeferredPrepass
where DeferredPrepass: Send + Sync + 'static,

impl Component for DepthPrepass
where DepthPrepass: Send + Sync + 'static,

impl Component for MotionVectorPrepass
where MotionVectorPrepass: Send + Sync + 'static,

impl Component for NormalPrepass
where NormalPrepass: Send + Sync + 'static,

impl Component for PreviousViewData
where PreviousViewData: Send + Sync + 'static,

impl Component for PreviousViewUniformOffset
where PreviousViewUniformOffset: Send + Sync + 'static,

impl Component for ViewPrepassTextures
where ViewPrepassTextures: Send + Sync + 'static,