Trait bevy_ecs::system::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
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
) { ... }
}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 SystemParams
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_statecorrectly registers allWorldaccesses used bySystemParam::get_paramwith the providedsystem_meta.- None of the world accesses may conflict with any prior accesses registered
on
system_meta.
Required Associated Types§
sourcetype State: Send + Sync + 'static
type State: Send + Sync + 'static
Used to store data which persists across invocations of a system.
sourcetype Item<'world, 'state>: SystemParam<State = Self::State>
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§
sourcefn init_state(world: &mut World, system_meta: &mut SystemMeta) -> Self::State
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.
sourceunsafe 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 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
UnsafeWorldCellmust have access to any world data registered ininit_state. worldmust be the sameWorldthat was used to initializestate.
Provided Methods§
sourcefn new_archetype(
_state: &mut Self::State,
_archetype: &Archetype,
_system_meta: &mut SystemMeta
)
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).
sourcefn apply(state: &mut Self::State, system_meta: &SystemMeta, world: &mut World)
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.
Object Safety§
This trait is not object safe.