Trait SystemParam

Source

pub unsafe trait SystemParam: Sized {
    type State: Send + Sync + 'static;
    type Item<'world, 'state>: SystemParam<State = Self::State>;

    // Required methods
    fn init_state(
        world: &mut World,
        system_meta: &mut SystemMeta,
    ) -> Self::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>;

    // Provided methods
    unsafe fn new_archetype(
        state: &mut Self::State,
        archetype: &Archetype,
        system_meta: &mut SystemMeta,
    ) { ... }
    fn apply(
        state: &mut Self::State,
        system_meta: &SystemMeta,
        world: &mut World,
    ) { ... }
    fn queue(
        state: &mut Self::State,
        system_meta: &SystemMeta,
        world: DeferredWorld<'_>,
    ) { ... }
}

Expand description

A parameter that can be used in a System.

§Derive

This trait can be derived with the super::SystemParam macro. This macro only works if each field on the derived struct implements SystemParam. Note: There are additional requirements on the field types. See the Generic SystemParams section for details and workarounds of the probable cause if this derive causes an error to be emitted.

Derived SystemParam structs may have two lifetimes: 'w for data stored in the World, and 's for data stored in the parameter’s state.

The following list shows the most common SystemParams and which lifetime they require

Query<'w, 's, Entity>,
Res<'w, SomeResource>,
ResMut<'w, SomeOtherResource>,
Local<'s, u8>,
Commands<'w, 's>,
EventReader<'w, 's, SomeEvent>,
EventWriter<'w, SomeEvent>

§`PhantomData`

PhantomData is a special type of SystemParam that does nothing. This is useful for constraining generic types or lifetimes.

§Example

use std::marker::PhantomData;
use bevy_ecs::system::SystemParam;

#[derive(SystemParam)]
struct MyParam<'w, Marker: 'static> {
    foo: Res<'w, SomeResource>,
    marker: PhantomData<Marker>,
}

fn my_system<T: 'static>(param: MyParam<T>) {
    // Access the resource through `param.foo`
}

§Generic `SystemParam`s

When using the derive macro, you may see an error in the form of:

expected ... [ParamType]
found associated type `<[ParamType] as SystemParam>::Item<'_, '_>`

where [ParamType] is the type of one of your fields. To solve this error, you can wrap the field of type [ParamType] with StaticSystemParam (i.e. StaticSystemParam<[ParamType]>).

§Details

The derive macro requires that the SystemParam implementation of each field F’s Item’s is itself F (ignoring lifetimes for simplicity). This assumption is due to type inference reasons, so that the derived SystemParam can be used as an argument to a function system. If the compiler cannot validate this property for [ParamType], it will error in the form shown above.

This will most commonly occur when working with SystemParams generically, as the requirement has not been proven to the compiler.

§Safety

The implementor must ensure the following is true.

SystemParam::init_state correctly registers all World accesses used by SystemParam::get_param with the provided system_meta.
None of the world accesses may conflict with any prior accesses registered on system_meta.

Required Associated Types§

Source

type State: Send + Sync + 'static

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

Source

type Item<'world, 'state>: SystemParam<State = Self::State>

The item type returned when constructing this system param. The value of this associated type should be Self, instantiated with new lifetimes.

You could think of SystemParam::Item<'w, 's> as being an operation that changes the lifetimes bound to Self.

Required Methods§

Source

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.

Source

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.

§Safety

The passed UnsafeWorldCell must have access to any world data registered in init_state.
world must be the same World that was used to initialize state.

Provided Methods§

Source

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

§Safety

archetype must be from the World used to initialize state in init_state.

Source

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.

Source

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

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

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Trait SystemParamCopy item path

§Derive

§PhantomData

§Example

§Generic SystemParams

§Details

§Safety

Required Associated Types§

type State: Send + Sync + 'static

type Item<'world, 'state>: SystemParam<State = Self::State>

Required Methods§

fn init_state(world: &mut World, system_meta: &mut SystemMeta) -> Self::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>

§Safety

Provided Methods§

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

§Safety

fn apply(state: &mut Self::State, system_meta: &SystemMeta, world: &mut World)

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

Dyn Compatibility§

Implementations on Foreign Types§

impl SystemParam for ()

type State = ()

type Item<'w, 's> = ()

fn init_state(_world: &mut World, _system_meta: &mut SystemMeta) -> Self::State

unsafe fn new_archetype( (): &mut Self::State, _archetype: &Archetype, _system_meta: &mut SystemMeta, )

fn apply((): &mut Self::State, _system_meta: &SystemMeta, _world: &mut World)

fn queue( (): &mut Self::State, _system_meta: &SystemMeta, _world: DeferredWorld<'_>, )

unsafe fn get_param<'w, 's>( state: &'s mut Self::State, _system_meta: &SystemMeta, _world: UnsafeWorldCell<'w>, _change_tick: Tick, ) -> Self::Item<'w, 's>

impl<'a, T: 'static> SystemParam for Option<NonSendMut<'a, T>>

type State = ComponentId

type Item<'w, 's> = Option<NonSendMut<'w, T>>

fn init_state(world: &mut World, system_meta: &mut SystemMeta) -> Self::State

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

impl<'a, T: Resource> SystemParam for Option<Res<'a, T>>

type State = ComponentId

type Item<'w, 's> = Option<Res<'w, T>>

fn init_state(world: &mut World, system_meta: &mut SystemMeta) -> Self::State

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

impl<'a, T: Resource> SystemParam for Option<ResMut<'a, T>>

type State = ComponentId

type Item<'w, 's> = Option<ResMut<'w, T>>

fn init_state(world: &mut World, system_meta: &mut SystemMeta) -> Self::State

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

impl<P0: SystemParam> SystemParam for (P0,)

type State = (<P0 as SystemParam>::State,)

type Item<'w, 's> = (<P0 as SystemParam>::Item<'w, 's>,)

fn init_state(_world: &mut World, _system_meta: &mut SystemMeta) -> Self::State

unsafe fn new_archetype( (P0): &mut Self::State, _archetype: &Archetype, _system_meta: &mut SystemMeta, )

fn apply((P0): &mut Self::State, _system_meta: &SystemMeta, _world: &mut World)

fn queue( (P0): &mut Self::State, _system_meta: &SystemMeta, _world: DeferredWorld<'_>, )

unsafe fn get_param<'w, 's>( state: &'s mut Self::State, _system_meta: &SystemMeta, _world: UnsafeWorldCell<'w>, _change_tick: Tick, ) -> Self::Item<'w, 's>

impl<P0: SystemParam, P1: SystemParam> SystemParam for (P0, P1)

type State = (<P0 as SystemParam>::State, <P1 as SystemParam>::State)

type Item<'w, 's> = (<P0 as SystemParam>::Item<'w, 's>, <P1 as SystemParam>::Item<'w, 's>)

fn init_state(_world: &mut World, _system_meta: &mut SystemMeta) -> Self::State

unsafe fn new_archetype( (P0, P1): &mut Self::State, _archetype: &Archetype, _system_meta: &mut SystemMeta, )

fn apply( (P0, P1): &mut Self::State, _system_meta: &SystemMeta, _world: &mut World, )

fn queue( (P0, P1): &mut Self::State, _system_meta: &SystemMeta, _world: DeferredWorld<'_>, )

unsafe fn get_param<'w, 's>( state: &'s mut Self::State, _system_meta: &SystemMeta, _world: UnsafeWorldCell<'w>, _change_tick: Tick, ) -> Self::Item<'w, 's>

impl<P0: SystemParam, P1: SystemParam, P2: SystemParam> SystemParam for (P0, P1, P2)

type State = (<P0 as SystemParam>::State, <P1 as SystemParam>::State, <P2 as SystemParam>::State)

type Item<'w, 's> = (<P0 as SystemParam>::Item<'w, 's>, <P1 as SystemParam>::Item<'w, 's>, <P2 as SystemParam>::Item<'w, 's>)

fn init_state(_world: &mut World, _system_meta: &mut SystemMeta) -> Self::State

unsafe fn new_archetype( (P0, P1, P2): &mut Self::State, _archetype: &Archetype, _system_meta: &mut SystemMeta, )

fn apply( (P0, P1, P2): &mut Self::State, _system_meta: &SystemMeta, _world: &mut World, )

fn queue( (P0, P1, P2): &mut Self::State, _system_meta: &SystemMeta, _world: DeferredWorld<'_>, )

unsafe fn get_param<'w, 's>( state: &'s mut Self::State, _system_meta: &SystemMeta, _world: UnsafeWorldCell<'w>, _change_tick: Tick, ) -> Self::Item<'w, 's>

impl<P0: SystemParam, P1: SystemParam, P2: SystemParam, P3: SystemParam> SystemParam for (P0, P1, P2, P3)

type State = (<P0 as SystemParam>::State, <P1 as SystemParam>::State, <P2 as SystemParam>::State, <P3 as SystemParam>::State)

type Item<'w, 's> = (<P0 as SystemParam>::Item<'w, 's>, <P1 as SystemParam>::Item<'w, 's>, <P2 as SystemParam>::Item<'w, 's>, <P3 as SystemParam>::Item<'w, 's>)

fn init_state(_world: &mut World, _system_meta: &mut SystemMeta) -> Self::State

unsafe fn new_archetype( (P0, P1, P2, P3): &mut Self::State, _archetype: &Archetype, _system_meta: &mut SystemMeta, )

fn apply( (P0, P1, P2, P3): &mut Self::State, _system_meta: &SystemMeta, _world: &mut World, )

fn queue( (P0, P1, P2, P3): &mut Self::State, _system_meta: &SystemMeta, _world: DeferredWorld<'_>, )

unsafe fn get_param<'w, 's>( state: &'s mut Self::State, _system_meta: &SystemMeta, _world: UnsafeWorldCell<'w>, _change_tick: Tick, ) -> Self::Item<'w, 's>

impl<P0: SystemParam, P1: SystemParam, P2: SystemParam, P3: SystemParam, P4: SystemParam> SystemParam for (P0, P1, P2, P3, P4)

type State = (<P0 as SystemParam>::State, <P1 as SystemParam>::State, <P2 as SystemParam>::State, <P3 as SystemParam>::State, <P4 as SystemParam>::State)

type Item<'w, 's> = (<P0 as SystemParam>::Item<'w, 's>, <P1 as SystemParam>::Item<'w, 's>, <P2 as SystemParam>::Item<'w, 's>, <P3 as SystemParam>::Item<'w, 's>, <P4 as SystemParam>::Item<'w, 's>)

fn init_state(_world: &mut World, _system_meta: &mut SystemMeta) -> Self::State

Trait SystemParam

§`PhantomData`

§Generic `SystemParam`s