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 SystemParam
s 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`
}
PhantomData
PhantomData
is a special type of SystemParam
that does nothing.
This is useful for constraining generic types or lifetimes.
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 SystemParam
s 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_state
correctly registers allWorld
accesses used bySystemParam::get_param
with 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
SystemParam
s that exist at the same time, including those on other threads. world
must be the sameWorld
that 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
.