Struct Expect 

pub struct Expect<T>(/* private fields */);

A QueryData decorator which panics if its inner query does not match.

Usage

As a query parameter, this decorator is useful for preventing systems from silently skipping over entities which may erroneously not match the query.

Consider the following erroneous example:

use bevy::prelude::*;

#[derive(Component)]
struct A;

#[derive(Component)]
struct B;

// A and B are always expected to be inserted together:
#[derive(Bundle)]
struct AB {
    a: A,
    b: B,
}

fn bad_system(mut commands: Commands) {
    commands.spawn(A); // Spawn A without B!
}

fn unsafe_system(q: Query<(&A, &B)>) {
    for _ in q.iter() {
        // An instance of `A` does exist.
        // But because `A` does not exist *with* `B`, this system skips over it silently.
    }
}

This problem can be solved with Expect:

use moonshine_util::expect::Expect;

fn safe_system(q: Query<(&A, Expect<&B>)>) {
    for _ in q.iter() {
       // This system will panic if it finds an instance of `A` without `B`.
    }
}

Component Requirements

When used as a Component, this decorator will panic if the given component type T does not exist on the entity. This is especially useful as a component requirement:

use moonshine_util::expect::Expect;

#[derive(Component)]
struct A;

#[derive(Component)]
#[require(Expect<A>)]
struct B;

fn unsafe_system(mut commands: Commands) {
   commands.spawn(B); // Spawn B without A! This will panic!
}

Trait Implementations

impl<T> Component for Expect<T>

where T: Component,

const STORAGE_TYPE: StorageType = StorageType::SparseSet

A constant indicating the storage type used for this component.

type Mutability = Immutable

A marker type to assist Bevy with determining if this component is mutable, or immutable. Mutable components will have Component<Mutability = Mutable>, while immutable components will instead have Component<Mutability = Immutable>.

fn on_add() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_add ComponentHook for this Component if one is defined.

fn on_insert() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_insert ComponentHook for this Component if one is defined.

fn on_replace() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_replace ComponentHook for this Component if one is defined.

fn on_remove() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_remove ComponentHook for this Component if one is defined.

fn on_despawn() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_despawn ComponentHook for this Component if one is defined.

fn register_required_components( _component_id: ComponentId, _required_components: &mut RequiredComponentsRegistrator<'_, '_>, )

Registers required components.

fn clone_behavior() -> ComponentCloneBehavior

Called when registering this component, allowing to override clone function (or disable cloning altogether) for this component.

fn map_entities<E>(_this: &mut Self, _mapper: &mut E)

where E: EntityMapper,

Maps the entities on this component using the given EntityMapper. This is used to remap entities in contexts like scenes and entity cloning. When deriving Component, this is populated by annotating fields containing entities with #[entities]

fn relationship_accessor() -> Option<ComponentRelationshipAccessor<Self>>

Returns ComponentRelationshipAccessor required for working with relationships in dynamic contexts.

impl<T> Default for Expect<T>

where T: Component,

fn default() -> Expect<T>

Returns the “default value” for a type.

impl<T> QueryData for Expect<T>

where T: QueryData,

const IS_READ_ONLY: bool = true

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

const IS_ARCHETYPAL: bool = T::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 = Expect<<T as QueryData>::ReadOnly>

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

type Item<'w, 's> = <T as QueryData>::Item<'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, 's>( item: <Expect<T> as QueryData>::Item<'wlong, 's>, ) -> <Expect<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 <Expect<T> as WorldQuery>::State, fetch: &mut <Expect<T> as WorldQuery>::Fetch<'w>, entity: Entity, table_row: TableRow, ) -> Option<<Expect<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: &<Expect<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> WorldQuery for Expect<T>

where T: QueryData,

const IS_DENSE: bool = T::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<'w> = ExpectFetch<'w, T>

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

type State = <T 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: <Expect<T> as WorldQuery>::Fetch<'wlong>, ) -> <Expect<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: &<T as WorldQuery>::State, last_run: Tick, this_run: Tick, ) -> ExpectFetch<'w, T>

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 ExpectFetch<'w, T>, state: &<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 ExpectFetch<'w, T>, state: &<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: &<T as WorldQuery>::State, access: &mut FilteredAccess, )

Adds any component accesses used by this WorldQuery to access.

fn get_state( components: &Components, ) -> Option<<Expect<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) -> <T as WorldQuery>::State

Creates and initializes a State for this WorldQuery type.

fn matches_component_set( _state: &<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> ReadOnlyQueryData for Expect<T>

where T: ReadOnlyQueryData,