Struct Single 

pub struct Single<'w, 's, D: IterQueryData, F: QueryFilter = ()> { /* private fields */ }

System parameter that provides access to single entity’s components, much like Query::single/Query::single_mut.

This SystemParam fails validation if zero or more than one matching entity exists. This will cause the system to be skipped, according to the rules laid out in SystemParamValidationError.

Use Option<Single<D, F>> instead if zero or one matching entities can exist.

Note that Single is not used as a search optimization. It is used as a validation with slight overhead compared to Query.

See Query for more details.

Example

#[derive(Component)]
struct Hiding;

#[derive(Component)]
struct Boss {
   health: f32
};

#[derive(Component)]
struct EnemySize {
   height: f32
};

fn hurt_boss(mut boss: Single<&mut Boss, Without<Hiding>>) {
   boss.health -= 4.0;
}

fn hurt_and_shrink_boss(mut boss_and_size: Single<(&mut Boss, &mut EnemySize)>) {
   let (mut boss, mut size) = boss_and_size.into_inner();
   boss.health -= 4.0;
   size.height *= 0.5;
}

Note that because Single implements Deref and DerefMut, methods and fields like health can be accessed directly. You can also access the underlying data manually, by calling .deref/.deref_mut, or by using the * operator. When mutable elements appear in Single, use .into_inner to extract the tuple elements to mutate them.

Implementations

impl<'w, 's, D: IterQueryData, F: QueryFilter> Single<'w, 's, D, F>

pub fn into_inner(self) -> D::Item<'w, 's>

Returns the inner item with ownership.

Trait Implementations

impl<'w, 's, D: IterQueryData, F: QueryFilter> Deref for Single<'w, 's, D, F>

type Target = <D as QueryData>::Item<'w, 's>

The resulting type after dereferencing.

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

Dereferences the value.

impl<'w, 's, D: IterQueryData, F: QueryFilter> DerefMut for Single<'w, 's, D, F>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<'a, 'b, D: ReadOnlyQueryData + 'static, F: QueryFilter + 'static> ReadOnlySystemParam for Single<'a, 'b, D, F>

impl<'a, 'b, D: IterQueryData + 'static, F: QueryFilter + 'static> SystemParam for Single<'a, 'b, D, F>

type State = QueryState<D, F>

Used to store data which persists across invocations of a system.

type Item<'w, 's> = Single<'w, 's, D, F>

The item type returned when constructing this system param. The value of this associated type should be Self, instantiated with new lifetimes.

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

Creates a new instance of this param’s State.

fn init_access( state: &Self::State, system_meta: &mut SystemMeta, component_access_set: &mut FilteredAccessSet, world: &mut World, )

Registers any World access used by this SystemParam.

unsafe fn get_param<'w, 's>( state: &'s mut Self::State, system_meta: &SystemMeta, world: UnsafeWorldCell<'w>, change_tick: Tick, ) -> Result<Self::Item<'w, 's>, SystemParamValidationError>

Creates a parameter to be passed into a SystemParamFunction.

fn apply(state: &mut Self::State, system_meta: &SystemMeta, world: &mut World)

Applies any deferred mutations stored in this SystemParam’s state. This is used to apply Commands during ApplyDeferred.

fn queue( state: &mut Self::State, system_meta: &SystemMeta, world: DeferredWorld<'_>, )

Queues any deferred mutations to be applied at the next ApplyDeferred.