Struct ComponentId

pub struct ComponentId(/* private fields */);

A value which uniquely identifies the type of a Component or Resource within a World.

Each time a new Component type is registered within a World using e.g. World::register_component or World::register_component_with_descriptor or a Resource with e.g. World::init_resource, a corresponding ComponentId is created to track it.

While the distinction between ComponentId and TypeId may seem superficial, breaking them into two separate but related concepts allows components to exist outside of Rust’s type system. Each Rust type registered as a Component will have a corresponding ComponentId, but additional ComponentIds may exist in a World to track components which cannot be represented as Rust types for scripting or other advanced use-cases.

A ComponentId is tightly coupled to its parent World. Attempting to use a ComponentId from one World to access the metadata of a Component in a different World is undefined behavior and must not be attempted.

Given a type T which implements Component, the ComponentId for T can be retrieved from a World using World::component_id() or via Components::component_id(). Access to the ComponentId for a Resource is available via Components::resource_id().

Implementations

impl ComponentId

pub const fn new(index: usize) -> ComponentId

Creates a new ComponentId.

The index is a unique value associated with each type of component in a given world. Usually, this value is taken from a counter incremented for each type of component registered with the world.

pub fn index(self) -> usize

Returns the index of the current component.

Examples found in repository

examples/ecs/dynamic.rs (line 107)

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,
                            true,
                            ComponentCloneBehavior::Default,
                        )
                    });
                    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_component_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);
                });
            }
            _ => continue,
        }
    }
}

Trait Implementations

impl Clone for ComponentId

fn clone(&self) -> ComponentId

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for ComponentId

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

Formats the value using the given formatter.

impl DynamicComponentFetch for ComponentId

type Ref<'w> = Ptr<'w>

The read-only reference type returned by DynamicComponentFetch::fetch_ref.

type Mut<'w> = MutUntyped<'w>

The mutable reference type returned by DynamicComponentFetch::fetch_mut.

unsafe fn fetch_ref( self, cell: UnsafeEntityCell<'_>, ) -> Result<<ComponentId as DynamicComponentFetch>::Ref<'_>, EntityComponentError>

Returns untyped read-only reference(s) to the component(s) with the given ComponentIds, as determined by self.

unsafe fn fetch_mut( self, cell: UnsafeEntityCell<'_>, ) -> Result<<ComponentId as DynamicComponentFetch>::Mut<'_>, EntityComponentError>

Returns untyped mutable reference(s) to the component(s) with the given ComponentIds, as determined by self.

unsafe fn fetch_mut_assume_mutable( self, cell: UnsafeEntityCell<'_>, ) -> Result<<ComponentId as DynamicComponentFetch>::Mut<'_>, EntityComponentError>

Returns untyped mutable reference(s) to the component(s) with the given ComponentIds, as determined by self. Assumes all ComponentIds refer to mutable components.

impl<T> From<ComponentIdFor<'_, T>> for ComponentId

where T: Component,

fn from(to_component_id: ComponentIdFor<'_, T>) -> ComponentId

Converts to this type from the input type.

impl FromArg for &'static ComponentId

where ComponentId: Any + Send + Sync, usize: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

type This<'from_arg> = &'from_arg ComponentId

The type to convert into.

fn from_arg( arg: Arg<'_>, ) -> Result<<&'static ComponentId as FromArg>::This<'_>, ArgError>

Creates an item from an argument.

impl FromArg for &'static mut ComponentId

where ComponentId: Any + Send + Sync, usize: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

type This<'from_arg> = &'from_arg mut ComponentId

The type to convert into.

fn from_arg( arg: Arg<'_>, ) -> Result<<&'static mut ComponentId as FromArg>::This<'_>, ArgError>

Creates an item from an argument.

impl FromArg for ComponentId

where ComponentId: Any + Send + Sync, usize: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

type This<'from_arg> = ComponentId

The type to convert into.

fn from_arg( arg: Arg<'_>, ) -> Result<<ComponentId as FromArg>::This<'_>, ArgError>

Creates an item from an argument.

impl FromReflect for ComponentId

where ComponentId: Any + Send + Sync, usize: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn from_reflect(reflect: &(dyn PartialReflect + 'static)) -> Option<ComponentId>

Constructs a concrete instance of Self from a reflected value.

fn take_from_reflect( reflect: Box<dyn PartialReflect>, ) -> Result<Self, Box<dyn PartialReflect>>

Attempts to downcast the given value to Self using, constructing the value using from_reflect if that fails.

impl GetOwnership for &ComponentId

where ComponentId: Any + Send + Sync, usize: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn ownership() -> Ownership

Returns the ownership of Self.

impl GetOwnership for &mut ComponentId

where ComponentId: Any + Send + Sync, usize: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn ownership() -> Ownership

Returns the ownership of Self.

impl GetOwnership for ComponentId

where ComponentId: Any + Send + Sync, usize: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn ownership() -> Ownership

Returns the ownership of Self.

impl GetTypeRegistration for ComponentId

where ComponentId: Any + Send + Sync, usize: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn get_type_registration() -> TypeRegistration

Returns the default TypeRegistration for this type.

fn register_type_dependencies(registry: &mut TypeRegistry)

Registers other types needed by this type.

impl Hash for ComponentId

fn hash<__H>(&self, state: &mut __H)

where __H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl IntoReturn for &ComponentId

where ComponentId: Any + Send + Sync, usize: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn into_return<'into_return>(self) -> Return<'into_return>

where &ComponentId: 'into_return,

Converts Self into a Return value.

impl IntoReturn for &mut ComponentId

where ComponentId: Any + Send + Sync, usize: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn into_return<'into_return>(self) -> Return<'into_return>

where &mut ComponentId: 'into_return,

Converts Self into a Return value.

impl IntoReturn for ComponentId

where ComponentId: Any + Send + Sync, usize: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn into_return<'into_return>(self) -> Return<'into_return>

where ComponentId: 'into_return,

Converts Self into a Return value.

impl Ord for ComponentId

fn cmp(&self, other: &ComponentId) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for ComponentId

fn eq(&self, other: &ComponentId) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for ComponentId

fn partial_cmp(&self, other: &ComponentId) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl PartialReflect for ComponentId

where ComponentId: Any + Send + Sync, usize: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn get_represented_type_info(&self) -> Option<&'static TypeInfo>

Returns the TypeInfo of the type represented by this value.

fn try_apply( &mut self, value: &(dyn PartialReflect + 'static), ) -> Result<(), ApplyError>

Tries to apply a reflected value to this value.

fn reflect_kind(&self) -> ReflectKind

Returns a zero-sized enumeration of “kinds” of type.

fn reflect_ref(&self) -> ReflectRef<'_>

Returns an immutable enumeration of “kinds” of type.

fn reflect_mut(&mut self) -> ReflectMut<'_>

Returns a mutable enumeration of “kinds” of type.

fn reflect_owned(self: Box<ComponentId>) -> ReflectOwned

Returns an owned enumeration of “kinds” of type.

fn try_into_reflect( self: Box<ComponentId>, ) -> Result<Box<dyn Reflect>, Box<dyn PartialReflect>>

Attempts to cast this type to a boxed, fully-reflected value.

fn try_as_reflect(&self) -> Option<&(dyn Reflect + 'static)>

Attempts to cast this type to a fully-reflected value.

fn try_as_reflect_mut(&mut self) -> Option<&mut (dyn Reflect + 'static)>

Attempts to cast this type to a mutable, fully-reflected value.

fn into_partial_reflect(self: Box<ComponentId>) -> Box<dyn PartialReflect>

Casts this type to a boxed, reflected value.

fn as_partial_reflect(&self) -> &(dyn PartialReflect + 'static)

Casts this type to a reflected value.

fn as_partial_reflect_mut(&mut self) -> &mut (dyn PartialReflect + 'static)

Casts this type to a mutable, reflected value.

fn reflect_hash(&self) -> Option<u64>

Returns a hash of the value (which includes the type).

fn reflect_partial_eq( &self, value: &(dyn PartialReflect + 'static), ) -> Option<bool>

Returns a “partial equality” comparison result.

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

Debug formatter for the value.

fn reflect_clone(&self) -> Result<Box<dyn Reflect>, ReflectCloneError>

Attempts to clone Self using reflection.

fn apply(&mut self, value: &(dyn PartialReflect + 'static))

Applies a reflected value to this value.

fn clone_value(&self) -> Box<dyn PartialReflect>

👎Deprecated since 0.16.0: to clone reflected values, prefer using reflect_clone. To convert reflected values to dynamic ones, use to_dynamic.

Clones Self into its dynamic representation.

fn to_dynamic(&self) -> Box<dyn PartialReflect>

Converts this reflected value into its dynamic representation based on its kind.

fn is_dynamic(&self) -> bool

Indicates whether or not this type is a dynamic type.

impl Reflect for ComponentId

where ComponentId: Any + Send + Sync, usize: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn into_any(self: Box<ComponentId>) -> Box<dyn Any>

Returns the value as a Box<dyn Any>.

fn as_any(&self) -> &(dyn Any + 'static)

Returns the value as a &dyn Any.

fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)

Returns the value as a &mut dyn Any.

fn into_reflect(self: Box<ComponentId>) -> Box<dyn Reflect>

Casts this type to a boxed, fully-reflected value.

fn as_reflect(&self) -> &(dyn Reflect + 'static)

Casts this type to a fully-reflected value.

fn as_reflect_mut(&mut self) -> &mut (dyn Reflect + 'static)

Casts this type to a mutable, fully-reflected value.

fn set(&mut self, value: Box<dyn Reflect>) -> Result<(), Box<dyn Reflect>>

Performs a type-checked assignment of a reflected value to this value.

impl SparseSetIndex for ComponentId

fn sparse_set_index(&self) -> usize

Gets the sparse set index corresponding to this instance.

fn get_sparse_set_index(value: usize) -> ComponentId

Creates a new instance of this type with the specified index.

impl TriggerTargets for ComponentId

fn components(&self) -> impl Iterator<Item = ComponentId> + Clone

The components the trigger should target.

fn entities(&self) -> impl Iterator<Item = Entity> + Clone

The entities the trigger should target.

impl TupleStruct for ComponentId

where ComponentId: Any + Send + Sync, usize: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn field(&self, index: usize) -> Option<&(dyn PartialReflect + 'static)>

Returns a reference to the value of the field with index index as a &dyn Reflect.

fn field_mut( &mut self, index: usize, ) -> Option<&mut (dyn PartialReflect + 'static)>

Returns a mutable reference to the value of the field with index index as a &mut dyn Reflect.

fn field_len(&self) -> usize

Returns the number of fields in the tuple struct.

fn iter_fields(&self) -> TupleStructFieldIter<'_>

Returns an iterator over the values of the tuple struct’s fields.

fn to_dynamic_tuple_struct(&self) -> DynamicTupleStruct

Creates a new DynamicTupleStruct from this tuple struct.

fn clone_dynamic(&self) -> DynamicTupleStruct

👎Deprecated since 0.16.0: use to_dynamic_tuple_struct instead

Clones the struct into a DynamicTupleStruct.

fn get_represented_tuple_struct_info(&self) -> Option<&'static TupleStructInfo>

Will return None if TypeInfo is not available.

impl TypePath for ComponentId

where ComponentId: Any + Send + Sync,

fn type_path() -> &'static str

Returns the fully qualified path of the underlying type.

fn short_type_path() -> &'static str

Returns a short, pretty-print enabled path to the type.

fn type_ident() -> Option<&'static str>

Returns the name of the type, or None if it is anonymous.

fn crate_name() -> Option<&'static str>

Returns the name of the crate the type is in, or None if it is anonymous.

fn module_path() -> Option<&'static str>

Returns the path to the module the type is in, or None if it is anonymous.

impl Typed for ComponentId

where ComponentId: Any + Send + Sync, usize: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn type_info() -> &'static TypeInfo

Returns the compile-time info for the underlying type.

impl Copy for ComponentId

impl Eq for ComponentId

impl StructuralPartialEq for ComponentId