Trait Component
pub trait Component:
Send
+ Sync
+ 'static {
type Storage: ComponentStorage;
}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;§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 Types§
type Storage: ComponentStorage
type Storage: ComponentStorage
A marker type indicating the storage type used for this component.
This must be either [TableStorage] or [SparseStorage].