Struct FilteredEntityRef

pub struct FilteredEntityRef<'w, 's> { /* private fields */ }

Provides read-only access to a single entity and some of its components defined by the contained Access.

To define the access when used as a QueryData, use a QueryBuilder or QueryParamBuilder. The FilteredEntityRef must be the entire QueryData, and not nested inside a tuple with other data.

// This gives the `FilteredEntityRef` access to `&A`.
let mut query = QueryBuilder::<FilteredEntityRef>::new(&mut world)
    .data::<&A>()
    .build();

let filtered_entity: FilteredEntityRef = query.single(&mut world).unwrap();
let component: &A = filtered_entity.get().unwrap();

Implementations

impl<'w, 's> FilteredEntityRef<'w, 's>

pub fn id(&self) -> Entity

Returns the ID of the current entity.

pub fn location(&self) -> EntityLocation

Gets metadata indicating the location where the current entity is stored.

pub fn archetype(&self) -> &Archetype

Returns the archetype that the current entity belongs to.

pub fn access(&self) -> &Access

Returns a reference to the underlying Access.

pub fn contains<T: Component>(&self) -> bool

Returns true if the current entity has a component of type T. Otherwise, this returns false.

Notes

If you do not know the concrete type of a component, consider using Self::contains_id or Self::contains_type_id.

pub fn contains_id(&self, component_id: ComponentId) -> bool

Returns true if the current entity has a component identified by component_id. Otherwise, this returns false.

Notes

• If you know the concrete type of the component, you should prefer Self::contains.
• If you know the component’s TypeId but not its ComponentId, consider using Self::contains_type_id.

pub fn contains_type_id(&self, type_id: TypeId) -> bool

Returns true if the current entity has a component with the type identified by type_id. Otherwise, this returns false.

Notes

• If you know the concrete type of the component, you should prefer Self::contains.
• If you have a ComponentId instead of a TypeId, consider using Self::contains_id.

pub fn get<T: Component>(&self) -> Option<&'w T>

Gets access to the component of type T for the current entity. Returns None if the entity does not have a component of type T.

pub fn get_ref<T: Component>(&self) -> Option<Ref<'w, T>>

Gets access to the component of type T for the current entity, including change detection information as a Ref.

Returns None if the entity does not have a component of type T.

pub fn get_change_ticks<T: Component>(&self) -> Option<ComponentTicks>

Retrieves the change ticks for the given component. This can be useful for implementing change detection in custom runtimes.

pub fn get_change_ticks_by_id( &self, component_id: ComponentId, ) -> Option<ComponentTicks>

Retrieves the change ticks for the given ComponentId. This can be useful for implementing change detection in custom runtimes.

You should prefer to use the typed API Self::get_change_ticks where possible and only use this in cases where the actual component types are not known at compile time.

pub fn get_by_id(&self, component_id: ComponentId) -> Option<Ptr<'w>>

Gets the component of the given ComponentId from the entity.

You should prefer to use the typed API Self::get where possible and only use this in cases where the actual component types are not known at compile time.

Unlike FilteredEntityRef::get, this returns a raw pointer to the component, which is only valid while the FilteredEntityRef is alive.

pub fn spawned_by(&self) -> MaybeLocation

Returns the source code location from which this entity has been spawned.

pub fn spawn_tick(&self) -> Tick

Returns the Tick at which this entity has been spawned.

Trait Implementations

impl<'w, 's> Clone for FilteredEntityRef<'w, 's>

fn clone(&self) -> FilteredEntityRef<'w, 's>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl ContainsEntity for FilteredEntityRef<'_, '_>

fn entity(&self) -> Entity

Returns the contained entity.

impl<'a> From<&'a EntityMut<'_>> for FilteredEntityRef<'a, 'static>

fn from(entity: &'a EntityMut<'_>) -> Self

Converts to this type from the input type.

impl<'a> From<&'a EntityRef<'_>> for FilteredEntityRef<'a, 'static>

fn from(entity: &'a EntityRef<'_>) -> Self

Converts to this type from the input type.

impl<'w, 's, B: Bundle> From<&'w EntityRefExcept<'_, 's, B>> for FilteredEntityRef<'w, 's>

fn from(value: &'w EntityRefExcept<'_, 's, B>) -> Self

Converts to this type from the input type.

impl<'a> From<&'a EntityWorldMut<'_>> for FilteredEntityRef<'a, 'static>

fn from(entity: &'a EntityWorldMut<'_>) -> Self

Converts to this type from the input type.

impl<'w, 's> From<&'w FilteredEntityMut<'_, 's>> for FilteredEntityRef<'w, 's>

fn from(entity: &'w FilteredEntityMut<'_, 's>) -> Self

Converts to this type from the input type.

impl<'a> From<EntityMut<'a>> for FilteredEntityRef<'a, 'static>

fn from(entity: EntityMut<'a>) -> Self

Converts to this type from the input type.

impl<'a> From<EntityRef<'a>> for FilteredEntityRef<'a, 'static>

fn from(entity: EntityRef<'a>) -> Self

Converts to this type from the input type.

impl<'a> From<EntityWorldMut<'a>> for FilteredEntityRef<'a, 'static>

fn from(entity: EntityWorldMut<'a>) -> Self

Converts to this type from the input type.

impl<'w, 's> From<FilteredEntityMut<'w, 's>> for FilteredEntityRef<'w, 's>

fn from(entity: FilteredEntityMut<'w, 's>) -> Self

Converts to this type from the input type.

impl Hash for FilteredEntityRef<'_, '_>

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

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 Ord for FilteredEntityRef<'_, '_>

fn cmp(&self, other: &Self) -> 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 FilteredEntityRef<'_, '_>

fn eq(&self, other: &Self) -> 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 FilteredEntityRef<'_, '_>

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

FilteredEntityRef’s comparison trait implementations match the underlying Entity, and cannot discern between different worlds.

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 QueryData for FilteredEntityRef<'_, '_>

SAFETY: Self is the same as Self::ReadOnly

const IS_READ_ONLY: bool = true

True if this query is read-only and may not perform mutable access.

type ReadOnly = FilteredEntityRef<'_, '_>

The read-only variant of this QueryData, which satisfies the ReadOnlyQueryData trait.

type Item<'w, 's> = FilteredEntityRef<'w, 's>

The item returned by this WorldQuery This will be the data retrieved by the query, and is visible to the end user when calling e.g. Query<Self>::get.

fn shrink<'wlong: 'wshort, 'wshort, 's>( item: Self::Item<'wlong, 's>, ) -> Self::Item<'wshort, 's>

This function manually implements subtyping for the query items.

fn provide_extra_access( state: &mut Self::State, access: &mut Access, available_access: &Access, )

Offers additional access above what we requested in update_component_access. Implementations may add additional access that is a subset of available_access and does not conflict with anything in access, and must update access to include that access.

unsafe fn fetch<'w, 's>( access: &'s Self::State, fetch: &mut Self::Fetch<'w>, entity: Entity, _table_row: TableRow, ) -> Self::Item<'w, 's>

Fetch Self::Item for either the given entity in the current Table, or for the given entity in the current Archetype. This must always be called after WorldQuery::set_table with a table_row in the range of the current Table or after WorldQuery::set_archetype with an entity in the current archetype. Accesses components registered in WorldQuery::update_component_access.

impl<'a> TryFrom<&'a FilteredEntityRef<'_, '_>> for EntityRef<'a>

type Error = TryFromFilteredError

The type returned in the event of a conversion error.

fn try_from(entity: &'a FilteredEntityRef<'_, '_>) -> Result<Self, Self::Error>

Performs the conversion.

impl<'a> TryFrom<FilteredEntityRef<'a, '_>> for EntityRef<'a>

type Error = TryFromFilteredError

The type returned in the event of a conversion error.

fn try_from(entity: FilteredEntityRef<'a, '_>) -> Result<Self, Self::Error>

Performs the conversion.

impl WorldQuery for FilteredEntityRef<'_, '_>

SAFETY: The accesses of Self::ReadOnly are a subset of the accesses of Self

const IS_DENSE: bool = false

Returns true if (and only if) every table of every archetype matched by this fetch contains all of the matched components.

type Fetch<'w> = EntityFetch<'w>

Per archetype/table state retrieved by this WorldQuery to compute Self::Item for each entity.

type State = Access

State used to construct a Self::Fetch. This will be cached inside QueryState, so it is best to move as much data / computation here as possible to reduce the cost of constructing Self::Fetch.

fn shrink_fetch<'wlong: 'wshort, 'wshort>( fetch: Self::Fetch<'wlong>, ) -> Self::Fetch<'wshort>

This function manually implements subtyping for the query fetches.

unsafe fn init_fetch<'w, 's>( world: UnsafeWorldCell<'w>, _state: &'s Self::State, last_run: Tick, this_run: Tick, ) -> Self::Fetch<'w>

Creates a new instance of Self::Fetch, by combining data from the World with the cached Self::State. Readonly accesses resources registered in WorldQuery::update_component_access.

unsafe fn set_archetype<'w, 's>( _fetch: &mut Self::Fetch<'w>, _state: &'s Self::State, _: &'w Archetype, _table: &Table, )

Adjusts internal state to account for the next Archetype. This will always be called on archetypes that match this WorldQuery.

unsafe fn set_table<'w, 's>( _fetch: &mut Self::Fetch<'w>, _state: &'s Self::State, _: &'w Table, )

Adjusts internal state to account for the next Table. This will always be called on tables that match this WorldQuery.

fn update_component_access( state: &Self::State, filtered_access: &mut FilteredAccess, )

Adds any component accesses used by this WorldQuery to access.

fn init_state(_world: &mut World) -> Self::State

Creates and initializes a State for this WorldQuery type.

fn get_state(_components: &Components) -> Option<Self::State>

Attempts to initialize a State for this WorldQuery type using read-only access to Components.

fn matches_component_set( _state: &Self::State, _set_contains_id: &impl Fn(ComponentId) -> bool, ) -> bool

Returns true if this query matches a set of components. Otherwise, returns false.

impl<'w, 's> Copy for FilteredEntityRef<'w, 's>

impl EntityEquivalent for FilteredEntityRef<'_, '_>

impl Eq for FilteredEntityRef<'_, '_>

impl ReadOnlyQueryData for FilteredEntityRef<'_, '_>

SAFETY: Access is read-only.