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_err());
    assert!(res.get_mut::<A>().is_err());
    // The resource doesn't exist, so we can't read it or write it.
    assert!(res.get::<B>().is_err());
    assert!(res.get_mut::<B>().is_err());
    // 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_err());
    // 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

Returns a reference to the underlying [Access].

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

where R: Resource,

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

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

where R: Resource,

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

pub fn get<R>(&self) -> Result<Ref<'_, R>, ResourceFetchError>

where R: Resource,

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, ) -> Result<Ptr<'_>, ResourceFetchError>

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>(&mut self) -> Result<Mut<'_, R>, ResourceFetchError>

where R: Resource,

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, ) -> Result<MutUntyped<'_>, ResourceFetchError>

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>(self) -> Result<Mut<'w, R>, ResourceFetchError>

where R: Resource,

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, ) -> Result<MutUntyped<'w>, ResourceFetchError>

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>, ) -> FilteredResources<'w, 's>

Converts to this type from the input type.

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

fn from(value: &'w mut World) -> FilteredResourcesMut<'w, 'static>

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>) -> FilteredResources<'w, 's>

Converts to this type from the input type.

impl SystemParam for FilteredResourcesMut<'_, '_>

type State = Access

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, ) -> <FilteredResourcesMut<'_, '_> as SystemParam>::State

Creates a new instance of this param’s State.

fn init_access( access: &<FilteredResourcesMut<'_, '_> as SystemParam>::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<'world, 'state>( state: &'state mut <FilteredResourcesMut<'_, '_> as SystemParam>::State, system_meta: &SystemMeta, world: UnsafeWorldCell<'world>, change_tick: Tick, ) -> Result<<FilteredResourcesMut<'_, '_> as SystemParam>::Item<'world, 'state>, 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.

impl<'w, 's, T> SystemParamBuilder<FilteredResourcesMut<'w, 's>> for FilteredResourcesMutParamBuilder<T>

where T: FnOnce(&mut FilteredResourcesMutBuilder<'_>),

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

fn build_system<Marker, In, Out, Func>( self, func: Func, ) -> IntoBuilderSystem<Marker, In, Out, Func, Self>

where Self: 'static, Func: SystemParamFunction<Marker, Param = P>,

Create a System from a SystemParamBuilder directly.