Struct FilteredResources

pub struct FilteredResources<'w, 's> { /* private fields */ }

Provides read-only access to a set of Resources defined by the contained Access.

Use FilteredResourcesMut if you need mutable access to some resources.

To be useful as a SystemParam, this must be configured using a FilteredResourcesParamBuilder to build the system using a SystemParamBuilder.

Examples

// Use `FilteredResourcesParamBuilder` to declare access to resources.
let system = (FilteredResourcesParamBuilder::new(|builder| {
    builder.add_read::<B>().add_read::<C>();
}),)
    .build_state(&mut world)
    .build_system(resource_system);

world.init_resource::<A>();
world.init_resource::<C>();

fn resource_system(res: FilteredResources) {
    // The resource exists, but we have no access, so we can't read it.
    assert!(res.get::<A>().is_none());
    // The resource doesn't exist, so we can't read it.
    assert!(res.get::<B>().is_none());
    // The resource exists and we have access, so we can read it.
    let c = res.get::<C>().unwrap();
    // The type parameter can be left out if it can be determined from use.
    let c: Ref<C> = res.get().unwrap();
}

This can be used alongside ordinary Res and ResMut parameters if they do not conflict.

let system = (
    FilteredResourcesParamBuilder::new(|builder| {
        builder.add_read::<A>();
    }),
    ParamBuilder,
    ParamBuilder,
)
    .build_state(&mut world)
    .build_system(resource_system);

// Read access to A does not conflict with read access to A or write access to B.
fn resource_system(filtered: FilteredResources, res_a: Res<A>, res_mut_b: ResMut<B>) {
    let res_a_2: Ref<A> = filtered.get::<A>().unwrap();
}

But it will conflict if it tries to read the same resource that another parameter writes.

let system = (
    FilteredResourcesParamBuilder::new(|builder| {
        builder.add_read::<A>();
    }),
    ParamBuilder,
)
    .build_state(&mut world)
    .build_system(invalid_resource_system);

// Read access to A conflicts with write access to A.
fn invalid_resource_system(filtered: FilteredResources, res_mut_a: ResMut<A>) { }

Implementations

impl<'w, 's> FilteredResources<'w, 's>

pub fn access(&self) -> &Access<ComponentId>

Returns a reference to the underlying Access.

pub fn has_read<R: Resource>(&self) -> bool

Returns true if the FilteredResources has access to the given resource. Note that Self::get() may still return None if the resource does not exist.

pub fn get<R: Resource>(&self) -> Option<Ref<'w, R>>

Gets a reference to the resource of the given type if it exists and the FilteredResources has access to it.

pub fn get_by_id(&self, component_id: ComponentId) -> Option<Ptr<'w>>

Gets a pointer to the resource with the given ComponentId if it exists and the FilteredResources has access to it.

Trait Implementations

impl<'w, 's> Clone for FilteredResources<'w, 's>

fn clone(&self) -> FilteredResources<'w, 's>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'w, 's> From<&'w FilteredResourcesMut<'_, 's>> for FilteredResources<'w, 's>

fn from(resources: &'w FilteredResourcesMut<'_, 's>) -> Self

Converts to this type from the input type.

impl<'w> From<&'w World> for FilteredResources<'w, 'static>

fn from(value: &'w World) -> Self

Converts to this type from the input type.

impl<'w> From<&'w mut World> for FilteredResources<'w, 'static>

fn from(value: &'w mut World) -> Self

Converts to this type from the input type.

impl<'w, 's> From<FilteredResourcesMut<'w, 's>> for FilteredResources<'w, 's>

fn from(resources: FilteredResourcesMut<'w, 's>) -> Self

Converts to this type from the input type.

impl SystemParam for FilteredResources<'_, '_>

type State = Access<ComponentId>

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

type Item<'world, 'state> = FilteredResources<'world, 'state>

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, _system_meta: &mut SystemMeta) -> Self::State

Registers any World access used by this SystemParam and creates a new instance of this param’s State.

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

Creates a parameter to be passed into a SystemParamFunction.

unsafe fn new_archetype( state: &mut Self::State, archetype: &Archetype, system_meta: &mut SystemMeta, )

For the specified Archetype, registers the components accessed by this SystemParam (if applicable).a

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

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

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

unsafe fn validate_param( _state: &Self::State, _system_meta: &SystemMeta, _world: UnsafeWorldCell<'_>, ) -> bool

Validates that the param can be acquired by the get_param. Built-in executors use this to prevent systems with invalid params from running. For nested SystemParams validation will fail if any delegated validation fails.

impl<'w, 's, T: FnOnce(&mut FilteredResourcesBuilder<'_>)> SystemParamBuilder<FilteredResources<'w, 's>> for FilteredResourcesParamBuilder<T>

fn build( self, world: &mut World, meta: &mut SystemMeta, ) -> <FilteredResources<'w, 's> as SystemParam>::State

Registers any World access used by this SystemParam and creates a new instance of this param’s State.

fn build_state(self, world: &mut World) -> SystemState<P>

Create a SystemState from a SystemParamBuilder. To create a system, call SystemState::build_system on the result.

impl<'w, 's> Copy for FilteredResources<'w, 's>

impl ReadOnlySystemParam for FilteredResources<'_, '_>