Struct FilteredResourcesMut

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

Provides mutable access to a set of Resources defined by the contained Access.

Use FilteredResources if you only need read-only access to resources.

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

Examples

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

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

fn resource_system(mut res: FilteredResourcesMut) {
    // The resource exists, but we have no access, so we can't read it or write it.
    assert!(res.get::<A>().is_none());
    assert!(res.get_mut::<A>().is_none());
    // The resource doesn't exist, so we can't read it or write it.
    assert!(res.get::<B>().is_none());
    assert!(res.get_mut::<B>().is_none());
    // The resource exists and we have read access, so we can read it but not write it.
    let c = res.get::<C>().unwrap();
    assert!(res.get_mut::<C>().is_none());
    // The resource exists and we have write access, so we can read it or write it.
    let d = res.get::<D>().unwrap();
    let d = res.get_mut::<D>().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 = (
    FilteredResourcesMutParamBuilder::new(|builder| {
        builder.add_read::<A>().add_write::<B>();
    }),
    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 C.
// Write access to B does not conflict with access to A or C.
fn resource_system(mut filtered: FilteredResourcesMut, res_a: Res<A>, res_mut_c: ResMut<C>) {
    let res_a_2: Ref<A> = filtered.get::<A>().unwrap();
    let res_mut_b: Mut<B> = filtered.get_mut::<B>().unwrap();
}

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

let system = (
    FilteredResourcesMutParamBuilder::new(|builder| {
        builder.add_write::<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: FilteredResourcesMut, res_a: Res<A>) { }

Implementations

impl<'w, 's> FilteredResourcesMut<'w, 's>

pub fn as_readonly(&self) -> FilteredResources<'_, 's>

Gets read-only access to all of the resources this FilteredResourcesMut can access.

pub fn reborrow(&mut self) -> FilteredResourcesMut<'_, 's>

Returns a new instance with a shorter lifetime. This is useful if you have &mut FilteredResourcesMut, but you need FilteredResourcesMut.

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 read access to the given resource. Note that Self::get() may still return None if the resource does not exist.

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

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

pub fn get<R: Resource>(&self) -> Option<Ref<'_, 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<'_>>

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

pub fn get_mut<R: Resource>(&mut self) -> Option<Mut<'_, R>>

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

pub fn get_mut_by_id( &mut self, component_id: ComponentId, ) -> Option<MutUntyped<'_>>

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

pub fn into_mut<R: Resource>(self) -> Option<Mut<'w, R>>

Consumes self and gets mutable access to resource of the given type with the world 'w lifetime if it exists and the FilteredResources has access to it.

pub fn into_mut_by_id(self, component_id: ComponentId) -> Option<MutUntyped<'w>>

Consumes self and gets mutable access to resource with the given ComponentId with the world 'w lifetime if it exists and the FilteredResources has access to it.

Trait Implementations

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 mut World> for FilteredResourcesMut<'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 FilteredResourcesMut<'_, '_>

type State = Access<ComponentId>

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

type Item<'world, 'state> = FilteredResourcesMut<'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 FilteredResourcesMutBuilder<'_>)> SystemParamBuilder<FilteredResourcesMut<'w, 's>> for FilteredResourcesMutParamBuilder<T>

fn build( self, world: &mut World, meta: &mut SystemMeta, ) -> <FilteredResourcesMut<'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.