Struct Instance

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

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: Kind> Instance<T>

pub const PLACEHOLDER: Self

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

pub unsafe fn from_entity_unchecked(entity: Entity) -> Self

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: Kind>(self) -> Instance<U>

where 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>.

See [kind] macro for usage examples.

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: Kind>(self) -> Instance<U>

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 using [kind] macro and use Instance::cast_into instead of this.

Safety

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

impl<T: Component> Instance<T>

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

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: Component> AsRef<Instance<T>> for InstanceMut<'_, T>

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

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

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

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

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

impl<T: Kind> Clone for Instance<T>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: Kind> Debug for Instance<T>

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

Formats the value using the given formatter.

impl<T: Kind> Deref for Instance<T>

type Target = Entity

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<T: Kind> Display for Instance<T>

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

Formats the value using the given formatter.

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

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

Converts to this type from the input type.

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

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

Converts to this type from the input type.

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

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

Converts to this type from the input type.

impl From<Entity> for Instance<Any>

fn from(entity: Entity) -> Self

Converts to this type from the input type.

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

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

Converts to this type from the input type.

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

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

Converts to this type from the input type.

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

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

Converts to this type from the input type.

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

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

Converts to this type from the input type.

impl<T> FromReflect for Instance<T>

where Instance<T>: Any + Send + Sync, T: TypePath + Kind, Entity: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn from_reflect(reflect: &dyn PartialReflect) -> Option<Self>

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 Instance<T>: Any + Send + Sync, T: TypePath + Kind, Entity: 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<T: Kind> Hash for Instance<T>

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

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

Updates all Entity references stored inside using entity_mapper.

impl<T: Kind> Ord for Instance<T>

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<T: Kind> PartialEq<Entity> for Instance<T>

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

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

const 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: Kind> PartialEq<Instance<T>> for Entity

fn eq(&self, other: &Instance<T>) -> bool

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

const 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: Kind> PartialEq for Instance<T>

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

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

const 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: Kind> PartialOrd for Instance<T>

fn partial_cmp(&self, other: &Self) -> 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 Instance<T>: Any + Send + Sync, T: TypePath + Kind, Entity: 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) -> 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<Self>) -> ReflectOwned

Returns an owned enumeration of “kinds” of type.

fn try_into_reflect( self: Box<Self>, ) -> 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>

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

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

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

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

Casts this type to a boxed, reflected value.

fn as_partial_reflect(&self) -> &dyn PartialReflect

Casts this type to a reflected value.

fn as_partial_reflect_mut(&mut self) -> &mut dyn PartialReflect

Casts this type to a mutable, reflected value.

fn reflect_partial_eq(&self, value: &dyn PartialReflect) -> 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 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 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: Kind> QueryData for Instance<T>

const IS_READ_ONLY: bool = true

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

type ReadOnly = Instance<T>

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

type Item<'a> = 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, 'wshort>( item: Self::Item<'wlong>, ) -> Self::Item<'wshort>

This function manually implements subtyping for the query items.

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

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

where Instance<T>: Any + Send + Sync, T: TypePath + Kind, Entity: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

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

Returns the value as a Box<dyn Any>.

fn as_any(&self) -> &dyn Any

Returns the value as a &dyn Any.

fn as_any_mut(&mut self) -> &mut dyn Any

Returns the value as a &mut dyn Any.

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

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

fn as_reflect(&self) -> &dyn Reflect

Casts this type to a fully-reflected value.

fn as_reflect_mut(&mut self) -> &mut dyn Reflect

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: Kind> RelationshipSourceCollection for Instance<T>

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

The type of iterator returned by the iter method.

fn new() -> Self

Creates a new empty instance.

fn with_capacity(_capacity: usize) -> Self

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) -> Self::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 is_empty(&self) -> bool

Returns true if the collection contains no entities.

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

Add multiple entities to collection at once.

impl<T> TupleStruct for Instance<T>

where Instance<T>: Any + Send + Sync, T: TypePath + Kind, Entity: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

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

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>

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

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

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 Instance<T>: Any + Send + Sync, T: TypePath + Kind, Entity: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn type_info() -> &'static TypeInfo

Returns the compile-time info for the underlying type.

impl<T: Kind> WorldQuery for Instance<T>

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, 'wshort>( fetch: Self::Fetch<'wlong>, ) -> Self::Fetch<'wshort>

This function manually implements subtyping for the query fetches.

unsafe fn init_fetch<'w>( world: UnsafeWorldCell<'w>, state: &Self::State, last_change_tick: Tick, change_tick: 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>( fetch: &mut Self::Fetch<'w>, state: &Self::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 Self::Fetch<'w>, state: &Self::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: &Self::State, access: &mut FilteredAccess<ComponentId>, )

Adds any component accesses used by this WorldQuery to access.

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

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

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

Creates and initializes a State for this WorldQuery type.

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.

fn set_access(_state: &mut Self::State, _access: &FilteredAccess<ComponentId>)

Sets available accesses for implementors with dynamic access such as FilteredEntityRef or FilteredEntityMut.

impl<T: Kind> Copy for Instance<T>

impl<T: Kind> Eq for Instance<T>

impl<T: Kind> ReadOnlyQueryData for Instance<T>