Struct Instance 

pub struct Instance<T>(/* private fields */)
where
    T: Kind;

Represents an Entity of Kind T.

Instance<Any> is functionally equivalent to an entity.

Usage

An Instance<T> can be used to access entities in a “kind-safe” manner to improve safety and readability.

This type is designed to behave exactly like an Entity.

This means you may use it as a Query parameter, pass it to Commands to access InstanceCommands<T>, or store it as a type-safe reference to an Entity.

Note that an Instance<T> has 'static lifetime and does not contain any Component data. It only contains type information.

Example

#[derive(Component)]
struct Apple;

#[derive(Component)]
struct Orange;

struct Fruit;

impl Kind for Fruit {
    type Filter = Or<(With<Apple>, With<Orange>)>;
}

#[derive(Resource, Deref, DerefMut)]
struct FruitBasket(Vec<Instance<Fruit>>);

fn collect_fruits(mut basket: ResMut<FruitBasket>, fruits: Query<Instance<Fruit>>) {
    for fruit in fruits.iter() {
        println!("{fruit:?}");
        basket.push(fruit);
    }
}

Implementations

impl<T> Instance<T>

where T: Kind,

pub const PLACEHOLDER: Instance<T>

Same as Entity::PLACEHOLDER, but for an Instance<T>.

pub unsafe fn from_entity_unchecked(entity: Entity) -> Instance<T>

Creates a new instance of kind T from some Entity.

Usage

This function is useful when you know an Entity is of a specific kind and you need an Instance<T> with no way to validate it.

See Instance::from_entity for a safer alternative.

Safety

Assumes entity is a valid instance of kind T.

Example

#[derive(Component)]
struct Apple;

fn init_apple(entity: Entity, commands: &mut Commands) -> Instance<Apple> {
    commands.entity(entity).insert(Apple);
    // SAFE: `entity` will be a valid instance of `Apple`.
    unsafe { Instance::from_entity_unchecked(entity) }
}

pub fn entity(&self) -> Entity

Returns the Entity of this instance.

pub fn cast_into<U>(self) -> Instance<U>

where U: Kind, T: CastInto<U>,

Converts this instance into an instance of another kind Kind U.

Usage

A kind T is safety convertible to another kind U if T implements CastInto<U>.

pub fn cast_into_any(self) -> Instance<Any>

Converts this instance into an instance of Kind Any.

Usage

Any Instance<T> can be safely cast into an Instance<Any> using this function.

pub unsafe fn cast_into_unchecked<U>(self) -> Instance<U>

where U: Kind,

Converts this instance into an instance of another kind Kind U without any validation.

Usage

This function is useful when you know an Instance<T> is convertible to a specific type and you need an Instance<U> with no way to validate it.

Always prefer to explicitly declare safe casts with the CastInto trait and use Instance::cast_into.

Safety

Assumes this instance is also a valid Instance<U>.

pub unsafe fn as_entity_mut(&mut self) -> &mut Entity

👎Deprecated: use Instance::<T>::from_entity_unchecked instead

Returns a mutable reference to the internal Entity of this Instance.

Safety

You are responsible to ensure the entity is still a valid instance of Kind T.

impl<T> Instance<T>

where T: Component,

pub fn from_entity(entity: EntityRef<'_>) -> Option<Instance<T>>

Creates a new instance of kind T from some EntityRef if the entity has a Component of type T.

Methods from Deref<Target = Entity>

pub const PLACEHOLDER: Entity

Trait Implementations

impl<T> AsRef<Instance<T>> for InstanceMut<'_, T>

where T: Component,

fn as_ref(&self) -> &Instance<T>

Converts this type into a shared reference of the (usually inferred) input type.

impl<T> AsRef<Instance<T>> for InstanceRef<'_, T>

where T: Component,

fn as_ref(&self) -> &Instance<T>

Converts this type into a shared reference of the (usually inferred) input type.

impl<T> Borrow<Entity> for Instance<T>

where T: Kind,

fn borrow(&self) -> &Entity

Immutably borrows from an owned value.

impl<T> Clone for Instance<T>

where T: Kind,

fn clone(&self) -> Instance<T>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T> ContainsEntity for Instance<T>

where T: Kind,

fn entity(&self) -> Entity

Returns the contained entity.

impl<T> Debug for Instance<T>

where T: Kind,

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

Formats the value using the given formatter.

impl<T> Deref for Instance<T>

where T: Kind,

type Target = Entity

The resulting type after dereferencing.

fn deref(&self) -> &<Instance<T> as Deref>::Target

Dereferences the value.

impl<T> Display for Instance<T>

where T: Kind,

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

Formats the value using the given formatter.

impl<'a, T> From<&InstanceCommands<'a, T>> for Instance<T>

where T: Kind,

fn from(commands: &InstanceCommands<'a, T>) -> Instance<T>

Converts to this type from the input type.

impl<T> From<&InstanceMut<'_, T>> for Instance<T>

where T: Component,

fn from(item: &InstanceMut<'_, T>) -> Instance<T>

Converts to this type from the input type.

impl<T> From<&InstanceRef<'_, T>> for Instance<T>

where T: Component,

fn from(item: &InstanceRef<'_, T>) -> Instance<T>

Converts to this type from the input type.

impl From<Entity> for Instance<Any>

fn from(entity: Entity) -> Instance<Any>

Converts to this type from the input type.

impl<T> From<Instance<T>> for Entity

where T: Kind,

fn from(instance: Instance<T>) -> Entity

Converts to this type from the input type.

impl<'a, T> From<InstanceCommands<'a, T>> for Instance<T>

where T: Kind,

fn from(commands: InstanceCommands<'a, T>) -> Instance<T>

Converts to this type from the input type.

impl<T> From<InstanceMut<'_, T>> for Instance<T>

where T: Component,

fn from(item: InstanceMut<'_, T>) -> Instance<T>

Converts to this type from the input type.

impl<T> From<InstanceRef<'_, T>> for Instance<T>

where T: Component,

fn from(item: InstanceRef<'_, T>) -> Instance<T>

Converts to this type from the input type.

impl<T> From<Object<'_, '_, '_, T>> for Instance<T>

where T: Kind,

fn from(object: Object<'_, '_, '_, T>) -> Instance<T>

Converts to this type from the input type.

impl<T> From<ObjectRef<'_, '_, '_, T>> for Instance<T>

where T: Kind,

fn from(object: ObjectRef<'_, '_, '_, T>) -> Instance<T>

Converts to this type from the input type.

impl<T> From<ObjectWorldRef<'_, T>> for Instance<T>

where T: Kind,

fn from(object: ObjectWorldRef<'_, T>) -> Instance<T>

Converts to this type from the input type.

impl<T> FromReflect for Instance<T>

where T: Kind + TypePath, Instance<T>: Any + Send + Sync,

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

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<T> GetTypeRegistration for Instance<T>

where T: Kind + TypePath, Instance<T>: Any + Send + Sync,

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<T> Hash for Instance<T>

where T: Kind,

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<T> MapEntities for Instance<T>

where T: Kind,

fn map_entities<M>(&mut self, entity_mapper: &mut M)

where M: EntityMapper,

Updates all Entity references stored inside using entity_mapper.

impl<T> Ord for Instance<T>

where T: Kind,

fn cmp(&self, other: &Instance<T>) -> 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<T> PartialEq<Entity> for Instance<T>

where T: Kind,

fn eq(&self, other: &Entity) -> 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<T> PartialEq<Instance<T>> for Entity

where T: Kind,

fn eq(&self, other: &Instance<T>) -> 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<T> PartialEq<Instance<T>> for Object<'_, '_, '_, T>

where T: Kind,

fn eq(&self, other: &Instance<T>) -> 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<T> PartialEq<Instance<T>> for ObjectWorldRef<'_, T>

where T: Kind,

fn eq(&self, other: &Instance<T>) -> 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<T, U> PartialEq<Instance<U>> for Instance<T>

where T: Kind, U: Kind,

fn eq(&self, other: &Instance<U>) -> 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<T> PartialEq<Object<'_, '_, '_, T>> for Instance<T>

where T: Kind,

fn eq(&self, other: &Object<'_, '_, '_, T>) -> 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<T> PartialEq<ObjectWorldRef<'_, T>> for Instance<T>

where T: Kind,

fn eq(&self, other: &ObjectWorldRef<'_, T>) -> 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<T> PartialOrd for Instance<T>

where T: Kind,

fn partial_cmp(&self, other: &Instance<T>) -> 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<T> PartialReflect for Instance<T>

where T: Kind + TypePath, Instance<T>: Any + Send + Sync,

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<Instance<T>>) -> ReflectOwned

Returns an owned enumeration of “kinds” of type.

fn try_into_reflect( self: Box<Instance<T>>, ) -> 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<Instance<T>>) -> 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_partial_eq( &self, value: &(dyn PartialReflect + 'static), ) -> Option<bool>

Returns a “partial equality” comparison result.

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 to_dynamic(&self) -> Box<dyn PartialReflect>

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

fn reflect_clone_and_take<T>(&self) -> Result<T, ReflectCloneError>

where T: 'static, Self: Sized + TypePath,

For a type implementing PartialReflect, combines reflect_clone and take in a useful fashion, automatically constructing an appropriate ReflectCloneError if the downcast fails.

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

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

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

Debug formatter for the value.

fn is_dynamic(&self) -> bool

Indicates whether or not this type is a dynamic type.

impl<T> QueryData for Instance<T>

where T: Kind,

const IS_READ_ONLY: bool = <Entity as QueryData>::IS_READ_ONLY

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

const IS_ARCHETYPAL: bool = <Entity as QueryData>::IS_ARCHETYPAL

Returns true if (and only if) this query data relies strictly on archetypes to limit which entities are accessed by the Query.

type ReadOnly = Instance<T>

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

type Item<'w, 's> = Instance<T>

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, 's>( item: <Instance<T> as QueryData>::Item<'wlong, 's>, ) -> <Instance<T> as QueryData>::Item<'wshort, 's>

where 'wlong: 'wshort,

This function manually implements subtyping for the query items.

unsafe fn fetch<'w, 's>( _state: &'s <Instance<T> as WorldQuery>::State, _fetch: &mut <Instance<T> as WorldQuery>::Fetch<'w>, entity: Entity, _table_row: TableRow, ) -> Option<<Instance<T> as QueryData>::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.

fn iter_access( _state: &<Instance<T> as WorldQuery>::State, ) -> impl Iterator<Item = EcsAccessType<'_>>

Returns an iterator over the access needed by QueryData::fetch. Access conflicts are usually checked in WorldQuery::update_component_access, but in certain cases this method can be useful to implement a way of checking for access conflicts in a non-allocating way.

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.

impl<T> Reflect for Instance<T>

where T: Kind + TypePath, Instance<T>: Any + Send + Sync,

fn into_any(self: Box<Instance<T>>) -> 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<Instance<T>>) -> 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<T> RelationshipSourceCollection for Instance<T>

where T: Kind,

type SourceIter<'a> = <Entity as RelationshipSourceCollection>::SourceIter<'a>

The type of iterator returned by the iter method.

fn new() -> Instance<T>

Creates a new empty instance.

fn with_capacity(_capacity: usize) -> Instance<T>

Returns an instance with the given pre-allocated entity capacity.

fn reserve(&mut self, additional: usize)

Reserves capacity for at least additional more entities to be inserted.

fn add(&mut self, entity: Entity) -> bool

Adds the given entity to the collection.

fn remove(&mut self, entity: Entity) -> bool

Removes the given entity from the collection.

fn iter(&self) -> <Instance<T> as RelationshipSourceCollection>::SourceIter<'_>

Iterates all entities in the collection.

fn len(&self) -> usize

Returns the current length of the collection.

fn clear(&mut self)

Clears the collection.

fn shrink_to_fit(&mut self)

Attempts to save memory by shrinking the capacity to fit the current length.

fn extend_from_iter(&mut self, entities: impl IntoIterator<Item = Entity>)

Add multiple entities to collection at once.

fn is_empty(&self) -> bool

Returns true if the collection contains no entities.

fn source_to_remove_before_add(&self) -> Option<Entity>

For one-to-one relationships, returns the entity that should be removed before adding a new one. Returns None for one-to-many relationships or when no entity needs to be removed.

impl<T> TupleStruct for Instance<T>

where T: Kind + TypePath, Instance<T>: Any + Send + Sync,

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 get_represented_tuple_struct_info(&self) -> Option<&'static TupleStructInfo>

Will return None if TypeInfo is not available.

impl<T> TypePath for Instance<T>

where T: Kind + TypePath, Instance<T>: 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<T> Typed for Instance<T>

where T: Kind + TypePath, Instance<T>: Any + Send + Sync,

fn type_info() -> &'static TypeInfo

Returns the compile-time info for the underlying type.

impl<T> WorldQuery for Instance<T>

where T: Kind,

const IS_DENSE: bool = <T::Filter as WorldQuery>::IS_DENSE

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

type Fetch<'a> = <<T as Kind>::Filter as WorldQuery>::Fetch<'a>

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

type State = <<T as Kind>::Filter as WorldQuery>::State

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>( fetch: <Instance<T> as WorldQuery>::Fetch<'wlong>, ) -> <Instance<T> as WorldQuery>::Fetch<'wshort>

where 'wlong: 'wshort,

This function manually implements subtyping for the query fetches.

unsafe fn init_fetch<'w>( world: UnsafeWorldCell<'w>, state: &<Instance<T> as WorldQuery>::State, last_change_tick: Tick, change_tick: Tick, ) -> <Instance<T> as WorldQuery>::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>( fetch: &mut <Instance<T> as WorldQuery>::Fetch<'w>, state: &<Instance<T> as WorldQuery>::State, archetype: &'w Archetype, table: &'w 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>( fetch: &mut <Instance<T> as WorldQuery>::Fetch<'w>, state: &<Instance<T> as WorldQuery>::State, table: &'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: &<Instance<T> as WorldQuery>::State, access: &mut FilteredAccess, )

Adds any component accesses used by this WorldQuery to access.

fn get_state( components: &Components, ) -> Option<<Instance<T> as WorldQuery>::State>

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

fn init_state(world: &mut World) -> <Instance<T> as WorldQuery>::State

Creates and initializes a State for this WorldQuery type.

fn matches_component_set( state: &<Instance<T> as WorldQuery>::State, set_contains_id: &impl Fn(ComponentId) -> bool, ) -> bool

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

impl<T> Copy for Instance<T>

where T: Kind,

impl<T> Eq for Instance<T>

where T: Kind,

impl<T> ReadOnlyQueryData for Instance<T>

where T: Kind,