Trait bevy::ecs::system::SystemParam
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: &'world World,
change_tick: u32
) -> 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.
Attributes
#[system_param(ignore)]:
Can be added to any field in the struct. Fields decorated with this attribute
will be created with the default value upon realisation.
This is most useful for PhantomData fields, such as markers for generic types.
Example
use std::marker::PhantomData;
use bevy_ecs::system::SystemParam;
#[derive(SystemParam)]
struct MyParam<'w, Marker: 'static> {
foo: Res<'w, SomeResource>,
#[system_param(ignore)]
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.
!Sync Resources
A !Sync type cannot implement Resource. However, it is possible to wrap a Send but not Sync
type in SyncCell or the currently unstable Exclusive to make it Sync. This forces only
having mutable access (&mut T only, never &T), but makes it safe to reference across multiple
threads.
This will fail to compile since RefCell is !Sync.
ⓘ
#[derive(Resource)]
struct NotSync {
counter: RefCell<usize>,
}This will compile since the RefCell is wrapped with SyncCell.
use bevy_utils::synccell::SyncCell;
#[derive(Resource)]
struct ActuallySync {
counter: SyncCell<RefCell<usize>>,
}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§
type 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§
fn 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.
unsafe fn get_param<'world, 'state>(
state: &'state mut Self::State,
system_meta: &SystemMeta,
world: &'world World,
change_tick: u32
) -> Self::Item<'world, 'state>
unsafe fn get_param<'world, 'state>( state: &'state mut Self::State, system_meta: &SystemMeta, world: &'world World, change_tick: u32 ) -> Self::Item<'world, 'state>
Safety
This call might use any of the World accesses that were registered in Self::init_state.
- None of those accesses may conflict with any other
SystemParams that exist at the same time, including those on other threads. worldmust be the sameWorldthat was used to initializestate.
Provided Methods§
fn 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).
fn 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_system_buffers.