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<'_>,
    ) { ... }
    unsafe fn validate_param(
        _state: &Self::State,
        _system_meta: &SystemMeta,
        _world: UnsafeWorldCell<'_>,
    ) -> bool { ... }
}

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.

§Builders

If you want to use a SystemParamBuilder with a derived SystemParam implementation, add a #[system_param(builder)] attribute to the struct. This will generate a builder struct whose name is the param struct suffixed with Builder. The builder will not be pub, so you may want to expose a method that returns an impl SystemParamBuilder<T>.

mod custom_param {
    #[derive(SystemParam)]
    #[system_param(builder)]
    pub struct CustomParam<'w, 's> {
        query: Query<'w, 's, ()>,
        local: Local<'s, usize>,
    }

    impl<'w, 's> CustomParam<'w, 's> {
        pub fn builder(
            local: usize,
            query: impl FnOnce(&mut QueryBuilder<()>),
        ) -> impl SystemParamBuilder<Self> {
            CustomParamBuilder {
                local: LocalBuilder(local),
                query: QueryParamBuilder::new(query),
            }
        }
    }
}

use custom_param::CustomParam;

let system = (CustomParam::builder(100, |builder| {
    builder.with::<A>();
}),)
    .build_state(&mut world)
    .build_system(|param: CustomParam| {});

§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.
all world’s archetypes have been processed by new_archetype.

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 SystemParam::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.

Source

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.

However calling and respecting SystemParam::validate_param is not a strict requirement, SystemParam::get_param should provide it’s own safety mechanism to prevent undefined behavior.

The world can only be used to read param’s data and world metadata. No data can be written.

When using system parameters that require change_tick you can use UnsafeWorldCell::change_tick(). Even if this isn’t the exact same tick used for SystemParam::get_param, the world access ensures that the queried data will be the same in both calls.

This method has to be called directly before SystemParam::get_param with no other (relevant) world mutations inbetween. Otherwise, while it won’t lead to any undefined behavior, the validity of the param may change.

§Safety

The passed UnsafeWorldCell must have read-only access to world data registered in init_state.
world must be the same World that was used to initialize state.
All world’s archetypes have been processed by new_archetype.

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

§Builders

§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<'_>, )

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

§Safety

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 validate_param( state: &Self::State, _system_meta: &SystemMeta, _world: UnsafeWorldCell<'_>, ) -> bool

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, D: QueryData + 'static, F: QueryFilter + 'static> SystemParam for Option<Single<'a, D, F>>

type State = QueryState<D, F>

type Item<'w, 's> = Option<Single<'w, D, F>>

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

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

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

unsafe fn validate_param( state: &Self::State, system_meta: &SystemMeta, world: UnsafeWorldCell<'_>, ) -> bool

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<P: SystemParam> SystemParam for (P₁, P₂, …, Pₙ)

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

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

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

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

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

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

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

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<T: 'static> SystemParam for Option<NonSend<'_, T>>

type State = ComponentId

type Item<'w, 's> = Option<NonSend<'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<T: SystemParam> SystemParam for Vec<T>

type State = Vec<<T as SystemParam>::State>

type Item<'world, 'state> = Vec<<T as SystemParam>::Item<'world, 'state>>

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

unsafe fn validate_param( state: &Self::State, system_meta: &SystemMeta, world: UnsafeWorldCell<'_>, ) -> bool

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

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

impl<T: ?Sized> SystemParam for PhantomData<T>

type State = ()

Trait SystemParam

§`PhantomData`

§Generic `SystemParam`s