Struct ComponentsQueuedRegistrator 

pub struct ComponentsQueuedRegistrator<'w> { /* private fields */ }

A type that enables queuing registration in Components.

Note

These queued registrations return ComponentIds. These ids are not yet valid, but they will become valid when either ComponentsRegistrator::apply_queued_registrations is called or the same registration is made directly. In either case, the returned ComponentIds will be correct, but they are not correct yet.

Generally, that means these ComponentIds can be safely used for read-only purposes. Modifying the contents of the world through these ComponentIds directly without waiting for them to be fully registered and without then confirming that they have been fully registered is not supported. Hence, extra care is needed with these ComponentIds to ensure all safety rules are followed.

As a rule of thumb, if you have mutable access to ComponentsRegistrator, prefer to use that instead. Use this only if you need to know the id of a component but do not need to modify the contents of the world based on that id.

Implementations

impl<'w> ComponentsQueuedRegistrator<'w>

pub unsafe fn new( components: &'w Components, ids: &'w ComponentIds, ) -> ComponentsQueuedRegistrator<'w>

Constructs a new ComponentsQueuedRegistrator.

Safety

The Components and ComponentIds must match. For example, they must be from the same world.

pub fn queue_register_component<T>(&self) -> ComponentId

where T: Component,

This is a queued version of ComponentsRegistrator::register_component. This will reserve an id and queue the registration. These registrations will be carried out at the next opportunity.

If this has already been registered or queued, this returns the previous ComponentId.

Note

Technically speaking, the returned ComponentId is not valid, but it will become valid later. See type level docs for details.

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

This is a queued version of ComponentsRegistrator::register_component_with_descriptor. This will reserve an id and queue the registration. These registrations will be carried out at the next opportunity.

This can also be used to register resources and non-send data.

Note

Technically speaking, the returned ComponentId is not valid, but it will become valid later. See type level docs for details.

Warning

When registering a custom resource be sure to add crate::resource::IsResource as a required component, Otherwise it will not function as a resource.

pub fn queue_register_non_send<T>(&self) -> ComponentId

where T: Any,

This is a queued version of ComponentsRegistrator::register_non_send. This will reserve an id and queue the registration. These registrations will be carried out at the next opportunity.

If this has already been registered or queued, this returns the previous ComponentId.

Note

Technically speaking, the returned ComponentId is not valid, but it will become valid later. See type level docs for details.

Methods from Deref<Target = Components>

pub fn len(&self) -> usize

Returns the number of components registered or queued with this instance.

pub fn is_empty(&self) -> bool

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

pub fn num_queued(&self) -> usize

Returns the number of components registered with this instance.

pub fn any_queued(&self) -> bool

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

pub fn num_registered(&self) -> usize

Returns the number of components registered with this instance.

pub fn any_registered(&self) -> bool

Returns true if there are any 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, if it is registered. This will return None if the id is not registered or is queued.

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 125)

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();
    let mut event_names = HashMap::<String, EventKey>::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}"),
                Some('e') => println!("{EVENT_PROMPT}"),
                Some('t') => println!("{EMIT_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 its 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,
                            true,
                            false,
                            ComponentCloneBehavior::Default,
                            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| {
                    let terms = filtered_entity
                        .access()
                        .try_iter_access()
                        .unwrap()
                        .map(|component_access| {
                            let id = *component_access.index();
                            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 matches!(component_access, ComponentAccessKind::Exclusive(_)) {
                                data.iter_mut().for_each(|data| {
                                    *data += 1;
                                });
                            }

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

                    println!("{}: {}", filtered_entity.id(), terms);
                });
            }
            "e" => {
                rest.split(',').for_each(|event| {
                    let name = event.trim();
                    if name.is_empty() {
                        return;
                    }

                    // Register a ComponentId for this event, no Rust type needed.
                    // SAFETY: ZST with no drop
                    let event_component_id = world.register_component_with_descriptor(unsafe {
                        ComponentDescriptor::new_with_layout(
                            format!("event:{name}"),
                            StorageType::Table,
                            Layout::new::<()>(),
                            None,
                            false,
                            false,
                            ComponentCloneBehavior::Ignore,
                            None,
                        )
                    });
                    // SAFETY: event_component_id was just registered for this event
                    let event_key = unsafe { EventKey::new(event_component_id) };
                    event_names.insert(name.to_string(), event_key);

                    // Build a dynamic observer that prints when the event fires.
                    let runner: ObserverRunner = |mut world, _observer, ctx, _event, _trigger| {
                        println!("  Observer fired!");
                        if let Some(mut counts) = world.get_resource_mut::<EventFireCount>() {
                            *counts.0.entry(ctx.event_key).or_insert(0) += 1;
                        }
                    };

                    // SAFETY: event_key was just registered, runner ignores pointers
                    let observer =
                        unsafe { Observer::with_dynamic_runner(runner).with_event_key(event_key) };
                    world.spawn(observer);

                    println!(
                        "Event '{name}' registered (key: {}) with a dynamic observer",
                        event_component_id.index()
                    );
                });

                // Ensure the counter resource exists.
                world.init_resource::<EventFireCount>();
            }
            "t" => {
                let name = rest.trim();
                let Some(&event_key) = event_names.get(name) else {
                    println!(
                        "Event '{name}' does not exist. Register it first with 'event {name}'"
                    );
                    continue;
                };

                let mut event_data = ();
                let mut trigger_data = ();
                // SAFETY: event_key was registered in this world, both pointers are valid ZSTs
                unsafe {
                    world.trigger_dynamic(
                        event_key,
                        PtrMut::from(&mut event_data),
                        PtrMut::from(&mut trigger_data),
                    );
                }

                let count = world
                    .get_resource::<EventFireCount>()
                    .map_or(0, |c| c.0.get(&event_key).copied().unwrap_or(0));
                println!("Event '{name}' triggered ({count} fires)");
            }
            _ => continue,
        }
    }
}

pub fn get_descriptor<'a>( &'a self, id: ComponentId, ) -> Option<Cow<'a, ComponentDescriptor>>

Gets the ComponentDescriptor of the component with this ComponentId if it is present. This will return None only if the id is neither registered nor queued to be registered.

Currently, the Cow will be Cow::Owned if and only if the component is queued. It will be Cow::Borrowed otherwise.

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 fn get_name<'a>(&'a self, id: ComponentId) -> Option<DebugName>

Gets the name of the component with this ComponentId if it is present. This will return None only if the id is neither registered nor queued to be registered.

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 and fully registered ComponentId.

pub fn is_id_valid(&self, id: ComponentId) -> bool

Returns true if the ComponentId is fully registered and valid. Ids may be invalid if they are still queued to be registered. Those ids are still correct, but they are not usable in every context yet.

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

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

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

where T: Component,

Returns the ComponentId of the given Component type T if it is fully registered. If you want to include queued registration, see Components::component_id().

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().valid_component_id::<ComponentA>().unwrap())

See also

• Components::get_valid_id()
• World::component_id()

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 ComponentsRegistrator::register_component() or ComponentsQueuedRegistrator::queue_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

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

pub fn iter_registered( &self, ) -> impl Iterator<Item = (ComponentId, &ComponentInfo)>

Gets an iterator over all components fully registered with this instance.

Trait Implementations

impl<'w> Clone for ComponentsQueuedRegistrator<'w>

fn clone(&self) -> ComponentsQueuedRegistrator<'w>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'w> Copy for ComponentsQueuedRegistrator<'w>

impl Deref for ComponentsQueuedRegistrator<'_>

type Target = Components

The resulting type after dereferencing.

fn deref(&self) -> &<ComponentsQueuedRegistrator<'_> as Deref>::Target

Dereferences the value.