Struct moonshine_kind::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 InstanceMutItem<'_, 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 copy of the value.

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<'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<&InstanceMutItem<'_, T>> for Instance<T>

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

Converts to this type from the input type.

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

fn from(item: &InstanceMutReadOnlyItem<'_, 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<InstanceMutItem<'_, T>> for Instance<T>

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

Converts to this type from the input type.

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

fn from(item: InstanceMutReadOnlyItem<'_, 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 Self: Any + Send + Sync, T: TypePath + Kind, Entity: FromReflect + TypePath + RegisterForReflection,

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

Constructs a concrete instance of Self from a reflected value.

fn take_from_reflect( reflect: Box<dyn Reflect>, ) -> Result<Self, Box<dyn Reflect>>

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 Self: Any + Send + Sync, T: TypePath + Kind, Entity: FromReflect + TypePath + 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 + PartialOrd,

Restrict a value to a certain interval.

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

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

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method 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

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method 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

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

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

type ReadOnly = Instance<T>

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

impl<T> Reflect for Instance<T>

where Self: Any + Send + Sync, T: TypePath + Kind, Entity: FromReflect + TypePath + RegisterForReflection,

fn get_represented_type_info(&self) -> Option<&'static TypeInfo>

Returns the TypeInfo of the type represented by this value.

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 reflected value.

fn as_reflect(&self) -> &dyn Reflect

Casts this type to a reflected value.

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

Casts this type to a mutable reflected value.

fn clone_value(&self) -> Box<dyn Reflect>

Clones the value as a Reflect trait object.

fn set(&mut self, value: Box<dyn Reflect>) -> Result<(), Box<dyn Reflect>>

Performs a type-checked assignment of a reflected value to this value.

fn try_apply(&mut self, value: &dyn Reflect) -> 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 reflect_partial_eq(&self, value: &dyn Reflect) -> Option<bool>

Returns a “partial equality” comparison result.

fn apply(&mut self, value: &(dyn Reflect + 'static))

Applies a reflected value to this value.

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 serializable(&self) -> Option<Serializable<'_>>

Returns a serializable version of the value.

fn is_dynamic(&self) -> bool

Indicates whether or not this type is a dynamic type.

impl<T> TupleStruct for Instance<T>

where Self: Any + Send + Sync, T: TypePath + Kind, Entity: FromReflect + TypePath + RegisterForReflection,

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

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 Reflect>

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 clone_dynamic(&self) -> DynamicTupleStruct

Clones the struct into a DynamicTupleStruct.

impl<T> TypePath for Instance<T>

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

fn type_info() -> &'static TypeInfo

Returns the compile-time info for the underlying type.

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

type Item<'a> = Instance<T>

The item returned by this WorldQuery For QueryData this will be the item returned by the query. For QueryFilter this will be either (), or a bool indicating whether the entity should be included or a tuple of such things.

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

Per archetype/table state used by this WorldQuery to fetch Self::Item

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

This function manually implements subtyping for the query items.

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 this fetch.

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. This is used to select a more efficient “table iterator” for “dense” queries. If this returns true, WorldQuery::set_table must be used before WorldQuery::fetch can be called for iterators. If this returns false, WorldQuery::set_archetype must be used before WorldQuery::fetch can be called for iterators.

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.

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 a entity in the current archetype.

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>