[Merged by Bors] - Add component_id function to World and Components

crates/bevy_ecs/src/component.rs

@@ -138,6 +138,24 @@ impl ComponentInfo {
     }
 }
 
+/// A [`ComponentId`] is an semi-opaque value which uniquely identifies the type of
+/// a [`Component`] within a [`World`](crate::world::World).
+///
+/// Each time a new [`Component`] type is registered within a [`World`](crate::world::World)
+/// using [`World::init_component`](crate::world::World::init_component) or
+/// [`World::init_component_with_descriptor`](crate::world::World::init_component_with_descriptor),
+/// a corresponding [`ComponentId`] is created to track it.
+///
+/// While the distinction between [`ComponentId`] and [`TypeId`] may seem superficial, breaking them
+/// in to two separate but related concepts allows Bevy components to exist outside of Rust's type system.
+/// Each Rust type registered as a [`Component`] will have a corresponding [`ComponentId`], but additional
+/// [`ComponentId`]s may exist in a [`World`](crate::world::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`](crate::world::World).
+/// Attempting to use a [`ComponentId`] from one [`World`](crate::world::World) to access the metadata
+/// of a [`Component`] in a different [`World`](crate::world::World) is undefined behaviour and should
+/// not be attempted.
 #[derive(Debug, Copy, Clone, Hash, Ord, PartialOrd, Eq, PartialEq)]
 pub struct ComponentId(usize);
 
@@ -346,11 +364,34 @@ impl Components {
         self.components.get_unchecked(id.0)
     }
 
+    /// Type-erased equivalent of [`Components::component_id`].
     #[inline]
     pub fn get_id(&self, type_id: TypeId) -> Option<ComponentId> {
         self.indices.get(&type_id).map(|index| ComponentId(*index))
     }
 
+    /// Retrieves the [`ComponentId`] of the given [`Component`] type in
+    /// this [`Components`] instance.
+    ///
+    /// Returns [`None`] if the [`Component`] type has not
+    /// yet been initialized using [`Components::init_component`].
+    /// ```rust
+    /// use bevy_ecs::prelude::*;
+    ///
+    /// let mut world = World::new();
+    ///
+    /// #[derive(Component)]
+    /// struct ComponentA {}
+    ///
+    /// let component_a_id = world.init_component::<ComponentA>();
+    ///
+    ///assert_eq!(component_a_id, world.components().component_id::<ComponentA>().unwrap())
+    /// ```
+    #[inline]
+    pub fn component_id<T: Component>(&self) -> Option<ComponentId> {
+        self.get_id(TypeId::of::<T>())
+    }
+
     #[inline]
     pub fn get_resource_id(&self, type_id: TypeId) -> Option<ComponentId> {
         self.resource_indices

crates/bevy_ecs/src/world/mod.rs

@@ -177,10 +177,23 @@ impl World {
         WorldCell::new(self)
     }
 
+    /// Initializes a new [`Component`] type within this [`World`] and returns the
+    /// [`ComponentId`] assigned to it.
     pub fn init_component<T: Component>(&mut self) -> ComponentId {
         self.components.init_component::<T>(&mut self.storages)
     }
 
+    /// Initializes a new Component type within this [`World`] and returns the
+    /// [`ComponentId`] assigned to it.
+    ///
+    /// [`World::init_component_with_descriptor`] differs from [`World::init_component`] in
+    /// that it uses a [`ComponentDescriptor`] to initialize the new component type instead
+    /// of statically available type information. This enables the dynamic initialization of
+    /// new component definitions at runtime for advanced use cases.
+    ///
+    /// While [`World::init_component_with_descriptor`] is useful in type-erased contexts,
+    /// the standard [`World::init_component`] function should always be used instead
+    /// when type information is available at compile time.
     pub fn init_component_with_descriptor(
         &mut self,
         descriptor: ComponentDescriptor,
@@ -189,6 +202,28 @@ impl World {
             .init_component_with_descriptor(&mut self.storages, descriptor)
     }
 
+    /// Retrieves the [`ComponentId`] of the given [`Component`] type in
+    /// this [`World`].
+    ///
+    /// Returns [`None`] if the [`Component`] type has not
+    /// yet been initialized within the [`World`] using [`World::init_component`].
+    /// ```rust
+    /// use bevy_ecs::prelude::*;
+    ///
+    /// let mut world = World::new();
+    ///
+    /// #[derive(Component)]
+    /// struct ComponentA {}
+    ///
+    /// let component_a_id = world.init_component::<ComponentA>();
+    ///
+    ///assert_eq!(component_a_id, world.component_id::<ComponentA>().unwrap())
+    /// ```
+    #[inline]
+    pub fn component_id<T: Component>(&self) -> Option<ComponentId> {
+        self.components.component_id::<T>()
+    }
+
     /// Retrieves an [`EntityRef`] that exposes read-only operations for the given `entity`.
     /// This will panic if the `entity` does not exist. Use [`World::get_entity`] if you want
     /// to check for entity existence instead of implicitly panic-ing.