Struct Components

pub struct Components { /* private fields */ }

Stores metadata associated with each kind of Component in a given World.

Implementations

impl Components

pub fn register_component<T>(&mut self, storages: &mut Storages) -> ComponentId

where T: Component,

Registers a Component of type T with this instance. If a component of this type has already been registered, this will return the ID of the pre-existing component.

See also

• Components::component_id()
• Components::register_component_with_descriptor()

pub fn register_component_with_descriptor( &mut self, storages: &mut Storages, descriptor: ComponentDescriptor, ) -> ComponentId

Registers a component described by descriptor.

Note

If this method is called multiple times with identical descriptors, a distinct ComponentId will be created for each one.

See also

• Components::component_id()
• Components::register_component()

pub fn len(&self) -> usize

Returns the number of components registered with this instance.

pub fn is_empty(&self) -> bool

Returns true if there are no components registered with this instance. Otherwise, this returns false.

pub fn get_info(&self, id: ComponentId) -> Option<&ComponentInfo>

Gets the metadata associated with the given component.

This will return an incorrect result if id did not come from the same world as self. It may return None or a garbage value.

Examples found in repository

examples/ecs/dynamic.rs (line 96)

fn main() {
    let mut world = World::new();
    let mut lines = std::io::stdin().lines();
    let mut component_names = HashMap::<String, ComponentId>::new();
    let mut component_info = HashMap::<ComponentId, ComponentInfo>::new();

    println!("{PROMPT}");
    loop {
        print!("\n> ");
        let _ = std::io::stdout().flush();
        let Some(Ok(line)) = lines.next() else {
            return;
        };

        if line.is_empty() {
            return;
        };

        let Some((first, rest)) = line.trim().split_once(|c: char| c.is_whitespace()) else {
            match &line.chars().next() {
                Some('c') => println!("{COMPONENT_PROMPT}"),
                Some('s') => println!("{ENTITY_PROMPT}"),
                Some('q') => println!("{QUERY_PROMPT}"),
                _ => println!("{PROMPT}"),
            }
            continue;
        };

        match &first[0..1] {
            "c" => {
                rest.split(',').for_each(|component| {
                    let mut component = component.split_whitespace();
                    let Some(name) = component.next() else {
                        return;
                    };
                    let size = match component.next().map(str::parse) {
                        Some(Ok(size)) => size,
                        _ => 0,
                    };
                    // Register our new component to the world with a layout specified by it's size
                    // SAFETY: [u64] is Send + Sync
                    let id = world.register_component_with_descriptor(unsafe {
                        ComponentDescriptor::new_with_layout(
                            name.to_string(),
                            StorageType::Table,
                            Layout::array::<u64>(size).unwrap(),
                            None,
                        )
                    });
                    let Some(info) = world.components().get_info(id) else {
                        return;
                    };
                    component_names.insert(name.to_string(), id);
                    component_info.insert(id, info.clone());
                    println!("Component {} created with id: {:?}", name, id.index());
                });
            }
            "s" => {
                let mut to_insert_ids = Vec::new();
                let mut to_insert_data = Vec::new();
                rest.split(',').for_each(|component| {
                    let mut component = component.split_whitespace();
                    let Some(name) = component.next() else {
                        return;
                    };

                    // Get the id for the component with the given name
                    let Some(&id) = component_names.get(name) else {
                        println!("Component {name} does not exist");
                        return;
                    };

                    // Calculate the length for the array based on the layout created for this component id
                    let info = world.components().get_info(id).unwrap();
                    let len = info.layout().size() / size_of::<u64>();
                    let mut values: Vec<u64> = component
                        .take(len)
                        .filter_map(|value| value.parse::<u64>().ok())
                        .collect();
                    values.resize(len, 0);

                    // Collect the id and array to be inserted onto our entity
                    to_insert_ids.push(id);
                    to_insert_data.push(values);
                });

                let mut entity = world.spawn_empty();

                // Construct an `OwningPtr` for each component in `to_insert_data`
                let to_insert_ptr = to_owning_ptrs(&mut to_insert_data);

                // SAFETY:
                // - Component ids have been taken from the same world
                // - Each array is created to the layout specified in the world
                unsafe {
                    entity.insert_by_ids(&to_insert_ids, to_insert_ptr.into_iter());
                }

                println!("Entity spawned with id: {:?}", entity.id());
            }
            "q" => {
                let mut builder = QueryBuilder::<FilteredEntityMut>::new(&mut world);
                parse_query(rest, &mut builder, &component_names);
                let mut query = builder.build();

                query.iter_mut(&mut world).for_each(|filtered_entity| {
                    #[allow(deprecated)]
                    let terms = filtered_entity
                        .access()
                        .component_reads_and_writes()
                        .0
                        .map(|id| {
                            let ptr = filtered_entity.get_by_id(id).unwrap();
                            let info = component_info.get(&id).unwrap();
                            let len = info.layout().size() / size_of::<u64>();

                            // SAFETY:
                            // - All components are created with layout [u64]
                            // - len is calculated from the component descriptor
                            let data = unsafe {
                                std::slice::from_raw_parts_mut(
                                    ptr.assert_unique().as_ptr().cast::<u64>(),
                                    len,
                                )
                            };

                            // If we have write access, increment each value once
                            if filtered_entity.access().has_component_write(id) {
                                data.iter_mut().for_each(|data| {
                                    *data += 1;
                                });
                            }

                            format!("{}: {:?}", info.name(), data[0..len].to_vec())
                        })
                        .collect::<Vec<_>>()
                        .join(", ");

                    println!("{:?}: {}", filtered_entity.id(), terms);
                });
            }
            _ => continue,
        }
    }
}

pub fn get_name(&self, id: ComponentId) -> Option<&str>

Returns the name associated with the given component.

This will return an incorrect result if id did not come from the same world as self. It may return None or a garbage value.

pub unsafe fn get_info_unchecked(&self, id: ComponentId) -> &ComponentInfo

Gets the metadata associated with the given component.

Safety

id must be a valid ComponentId

pub fn get_id(&self, type_id: TypeId) -> Option<ComponentId>

Type-erased equivalent of Components::component_id().

pub fn component_id<T>(&self) -> Option<ComponentId>

where T: Component,

Returns the ComponentId of the given Component type T.

The returned ComponentId is specific to the Components instance it was retrieved from and should not be used with another Components instance.

Returns None if the Component type has not yet been initialized using Components::register_component().

use bevy_ecs::prelude::*;

let mut world = World::new();

#[derive(Component)]
struct ComponentA;

let component_a_id = world.register_component::<ComponentA>();

assert_eq!(component_a_id, world.components().component_id::<ComponentA>().unwrap())

See also

• Components::get_id()
• Components::resource_id()
• World::component_id()

pub fn get_resource_id(&self, type_id: TypeId) -> Option<ComponentId>

Type-erased equivalent of Components::resource_id().

pub fn resource_id<T>(&self) -> Option<ComponentId>

where T: Resource,

Returns the ComponentId of the given Resource type T.

The returned ComponentId is specific to the Components instance it was retrieved from and should not be used with another Components instance.

Returns None if the Resource type has not yet been initialized using Components::register_resource().

use bevy_ecs::prelude::*;

let mut world = World::new();

#[derive(Resource, Default)]
struct ResourceA;

let resource_a_id = world.init_resource::<ResourceA>();

assert_eq!(resource_a_id, world.components().resource_id::<ResourceA>().unwrap())

See also

• Components::component_id()
• Components::get_resource_id()

pub fn register_resource<T>(&mut self) -> ComponentId

where T: Resource,

Registers a Resource of type T with this instance. If a resource of this type has already been registered, this will return the ID of the pre-existing resource.

See also

• Components::resource_id()
• Components::register_resource_with_descriptor()

pub fn register_resource_with_descriptor( &mut self, descriptor: ComponentDescriptor, ) -> ComponentId

Registers a Resource described by descriptor.

Note

If this method is called multiple times with identical descriptors, a distinct ComponentId will be created for each one.

See also

• Components::resource_id()
• Components::register_resource()

pub fn register_non_send<T>(&mut self) -> ComponentId

where T: Any,

Registers a non-send resource of type T with this instance. If a resource of this type has already been registered, this will return the ID of the pre-existing resource.

pub fn iter(&self) -> impl Iterator<Item = &ComponentInfo>

Gets an iterator over all components registered with this instance.

Trait Implementations

impl Debug for Components

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for Components

fn default() -> Components

Returns the “default value” for a type.

impl<'a> SystemParam for &'a Components

type State = ()

Used to store data which persists across invocations of a system.

type Item<'w, 's> = &'w Components

The item type returned when constructing this system param. The value of this associated type should be Self, instantiated with new lifetimes.

fn init_state( _world: &mut World, _system_meta: &mut SystemMeta, ) -> <&'a Components as SystemParam>::State

Registers any World access used by this SystemParam and creates a new instance of this param’s State.

unsafe fn get_param<'w, 's>( _state: &'s mut <&'a Components as SystemParam>::State, _system_meta: &SystemMeta, world: UnsafeWorldCell<'w>, _change_tick: Tick, ) -> <&'a Components as SystemParam>::Item<'w, 's>

Creates a parameter to be passed into a SystemParamFunction.

unsafe fn new_archetype( state: &mut Self::State, archetype: &Archetype, system_meta: &mut SystemMeta, )

For the specified Archetype, registers the components accessed by this SystemParam (if applicable).a

fn apply(state: &mut Self::State, system_meta: &SystemMeta, world: &mut World)

Applies any deferred mutations stored in this SystemParam’s state. This is used to apply Commands during apply_deferred.

fn queue( state: &mut Self::State, system_meta: &SystemMeta, world: DeferredWorld<'_>, )

Queues any deferred mutations to be applied at the next apply_deferred.

unsafe fn validate_param( _state: &Self::State, _system_meta: &SystemMeta, _world: UnsafeWorldCell<'_>, ) -> bool

Validates that the param can be acquired by the get_param. Built-in executors use this to prevent systems with invalid params from running. For nested SystemParams validation will fail if any delegated validation fails.

impl<'a> ReadOnlySystemParam for &'a Components