Trait ComponentBridge 

pub trait ComponentBridge:
    Send
    + Sync
    + 'static {
    // Required methods
    fn bevy_type_id(&self) -> TypeId;
    fn py_type_ptr(&self) -> *const PyTypeObject;
    fn py_type<'py>(&self, py: Python<'py>) -> Bound<'py, PyType>;
    fn name(&self) -> &'static str;
    fn register(&self, world: &mut World) -> ComponentId;
    fn extract(
        &self,
        entity: &mut FilteredEntityMut<'_, '_>,
        component_id: ComponentId,
        validity: ValidityFlagWithMode,
        py: Python<'_>,
    ) -> PyResult<Py<PyAny>>;
    fn extract_fn(&self) -> ExtractFn;
    fn insert(
        &self,
        world: &mut World,
        entity: Entity,
        component: &Bound<'_, PyAny>,
    ) -> PyResult<()>;
    fn insert_into_entity(
        &self,
        entity: &mut EntityWorldMut<'_>,
        component: &Bound<'_, PyAny>,
    ) -> PyResult<()>;
    fn entity_contains(&self, entity: &EntityRef<'_>) -> bool;
    fn extract_from_entity_ref(
        &self,
        entity: &EntityRef<'_>,
        validity: ValidityFlagWithMode,
        py: Python<'_>,
    ) -> PyResult<Option<Py<PyAny>>>;
    fn extract_from_entity_mut(
        &self,
        entity: &mut EntityWorldMut<'_>,
        validity: ValidityFlagWithMode,
        py: Python<'_>,
    ) -> PyResult<Option<Py<PyAny>>>;

    // Provided methods
    fn insert_bulk_uniform(
        &self,
        component: &Bound<'_, PyAny>,
        entities: &[Entity],
        world: &mut World,
    ) -> PyResult<()> { ... }
    fn view_bridge(&self) -> Option<ViewBridge> { ... }
}

Trait that bridges a Bevy component to its Python wrapper.

Each feature crate implements this for its components. The trait provides all the methods needed for:

• Type identification (Rust TypeId, Python type object)
• Registration with Bevy world
• Extraction from entities (for Query)
• Insertion into entities (for Commands.spawn/insert)
• Containment checks

Safety

The extract method uses raw pointers internally. Implementations must ensure:

• The validity flag is checked before dereferencing
• The borrowed reference doesn’t outlive the system execution

Required Methods

fn bevy_type_id(&self) -> TypeId

Rust TypeId of the Bevy component

fn py_type_ptr(&self) -> *const PyTypeObject

Python type object pointer for type matching

Used for O(1) lookup in HashMap when dispatching from Python types.

fn py_type<'py>(&self, py: Python<'py>) -> Bound<'py, PyType>

Get Python type object

fn name(&self) -> &'static str

Human-readable name for error messages

fn register(&self, world: &mut World) -> ComponentId

Register component with Bevy world and return its ComponentId

fn extract( &self, entity: &mut FilteredEntityMut<'_, '_>, component_id: ComponentId, validity: ValidityFlagWithMode, py: Python<'_>, ) -> PyResult<Py<PyAny>>

Extract component from entity and return as Python object

Arguments

• entity - Mutable filtered entity reference from query iteration
• component_id - Pre-registered ComponentId for this component
• validity - Validity flag for borrowed reference tracking
• py - Python GIL token

Errors

Returns error if component extraction or Python conversion fails.

fn extract_fn(&self) -> ExtractFn

Get a function pointer for component extraction.

This allows caching the extract function directly to avoid vtable dispatch during per-entity iteration. The returned function pointer can be called directly without going through the trait object.

fn insert( &self, world: &mut World, entity: Entity, component: &Bound<'_, PyAny>, ) -> PyResult<()>

Insert component into entity via world access

Arguments

• world - Mutable world reference
• entity - Entity to insert component into
• component - Python object to convert and insert

Errors

Returns error if Python conversion or insertion fails.

fn insert_into_entity( &self, entity: &mut EntityWorldMut<'_>, component: &Bound<'_, PyAny>, ) -> PyResult<()>

Insert component directly into an EntityWorldMut

This is used by batch spawn to avoid double-mutable-borrow issues. Default implementation panics - bridges should override this.

Arguments

• entity - Mutable entity reference with world access
• component - Python object to convert and insert

Errors

Returns error if Python conversion or insertion fails.

fn entity_contains(&self, entity: &EntityRef<'_>) -> bool

Check if entity has this component type

fn extract_from_entity_ref( &self, entity: &EntityRef<'_>, validity: ValidityFlagWithMode, py: Python<'_>, ) -> PyResult<Option<Py<PyAny>>>

Extract component from an EntityRef (read-only access)

Used by world.get() for read-only component access. Returns None if the entity doesn’t have this component.

Safety

The returned Python object holds a borrowed reference to component data. The validity flag must be checked before dereferencing.

fn extract_from_entity_mut( &self, entity: &mut EntityWorldMut<'_>, validity: ValidityFlagWithMode, py: Python<'_>, ) -> PyResult<Option<Py<PyAny>>>

Extract component from an EntityWorldMut (mutable access)

Used by world.get_mut() for mutable component access. Returns None if the entity doesn’t have this component.

Safety

The returned Python object holds a borrowed reference to component data. The validity flag must be checked before dereferencing.

Provided Methods

fn insert_bulk_uniform( &self, component: &Bound<'_, PyAny>, entities: &[Entity], world: &mut World, ) -> PyResult<()>

Insert the same component into multiple entities (bulk uniform spawn).

Default loops insert_into_entity. Macro-generated bridges override this to extract the Python value once and clone in pure Rust.

fn view_bridge(&self) -> Option<ViewBridge>

Get View API bridge for this component (optional)

Returns Some(ViewBridge) if this component supports the View API, which enables batch field access for performance-critical operations.

Default implementation returns None (View API not supported).

Example

fn view_bridge(&self) -> Option<ViewBridge> {
    Some(ViewBridge {
        field_offset: PyTransform::field_offset,
        field_names: PyTransform::field_names,
        component_id: |world| world.register_component::<Transform>(),
    })
}

Implementors

impl ComponentBridge for ChildOfBridge

impl ComponentBridge for ChildrenBridge