Struct DynSystemParam

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

A SystemParam with a type that can be configured at runtime.

To be useful, this must be configured using a DynParamBuilder to build the system using a SystemParamBuilder.

Examples

// If the inner parameter doesn't require any special building, use `ParamBuilder`.
// Either specify the type parameter on `DynParamBuilder::new()` ...
let system = (DynParamBuilder::new::<Res<A>>(ParamBuilder),)
    .build_state(&mut world)
    .build_system(expects_res_a);

// ... or use a factory method on `ParamBuilder` that returns a specific type.
let system = (DynParamBuilder::new(ParamBuilder::resource::<A>()),)
    .build_state(&mut world)
    .build_system(expects_res_a);

fn expects_res_a(mut param: DynSystemParam) {
    // Use the `downcast` methods to retrieve the inner parameter.
    // They will return `None` if the type does not match.
    assert!(param.is::<Res<A>>());
    assert!(!param.is::<Res<B>>());
    assert!(param.downcast_mut::<Res<B>>().is_none());
    let res = param.downcast_mut::<Res<A>>().unwrap();
    // The type parameter can be left out if it can be determined from use.
    let res: Res<A> = param.downcast().unwrap();
}

let system = (
    // If the inner parameter also requires building,
    // pass the appropriate `SystemParamBuilder`.
    DynParamBuilder::new(LocalBuilder(10usize)),
    // `DynSystemParam` is just an ordinary `SystemParam`,
    // and can be combined with other parameters as usual!
    ParamBuilder::query(),
)
    .build_state(&mut world)
    .build_system(|param: DynSystemParam, query: Query<()>| {
        let local: Local<usize> = param.downcast::<Local<usize>>().unwrap();
        assert_eq!(*local, 10);
    });

Implementations

impl<'w, 's> DynSystemParam<'w, 's>

pub fn is<T: SystemParam>(&self) -> bool

where T::Item<'static, 'static>: SystemParam<Item<'w, 's> = T> + 'static,

Returns true if the inner system param is the same as T.

pub fn downcast<T: SystemParam>(self) -> Option<T>

where T::Item<'static, 'static>: SystemParam<Item<'w, 's> = T> + 'static,

Returns the inner system param if it is the correct type. This consumes the dyn param, so the returned param can have its original world and state lifetimes.

pub fn downcast_mut<'a, T: SystemParam>(&'a mut self) -> Option<T>

where T::Item<'static, 'static>: SystemParam<Item<'a, 'a> = T> + 'static,

Returns the inner system parameter if it is the correct type. This borrows the dyn param, so the returned param is only valid for the duration of that borrow.

pub fn downcast_mut_inner<'a, T: ReadOnlySystemParam>(&'a mut self) -> Option<T>

where T::Item<'static, 'static>: SystemParam<Item<'w, 'a> = T> + 'static,

Returns the inner system parameter if it is the correct type. This borrows the dyn param, so the returned param is only valid for the duration of that borrow, but since it only performs read access it can keep the original world lifetime. This can be useful with methods like Query::iter_inner() or Res::into_inner() to obtain references with the original world lifetime.

Trait Implementations

impl SystemParam for DynSystemParam<'_, '_>

type State = DynSystemParamState

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

type Item<'world, 'state> = DynSystemParam<'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 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.

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.

impl<'a, 'w, 's> SystemParamBuilder<DynSystemParam<'w, 's>> for DynParamBuilder<'a>

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