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) -> Self::State;
fn init_access(
state: &Self::State,
system_meta: &mut SystemMeta,
component_access_set: &mut FilteredAccessSet,
world: &mut World,
);
unsafe fn get_param<'world, 'state>(
state: &'state mut Self::State,
system_meta: &SystemMeta,
world: UnsafeWorldCell<'world>,
change_tick: Tick,
) -> Result<Self::Item<'world, 'state>, SystemParamValidationError>;
// Provided methods
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>,
Query<'w, 's, &'static SomeComponent>,
Res<'w, SomeResource>,
ResMut<'w, SomeOtherResource>,
Local<'s, u8>,
Commands<'w, 's>,
MessageReader<'w, 's, SomeMessage>,
MessageWriter<'w, SomeMessage>§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.
§Custom Validation Messages
When using the derive macro, any SystemParamValidationErrors will be propagated from the sub-parameters.
If you want to override the error message, add a #[system_param(validation_message = "New message")] attribute to the parameter.
#[derive(SystemParam)]
struct MyParam<'w> {
#[system_param(validation_message = "Custom Message")]
foo: Res<'w, SomeResource>,
}
let mut world = World::new();
let err = world.run_system_cached(|param: MyParam| {}).unwrap_err();
let expected = "Parameter `MyParam::foo` failed validation: Custom Message";
assert!(err.to_string().contains(expected));§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_accesscorrectly 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) -> Self::State
fn init_state(world: &mut World) -> Self::State
Creates a new instance of this param’s State.
Sourcefn init_access(
state: &Self::State,
system_meta: &mut SystemMeta,
component_access_set: &mut FilteredAccessSet,
world: &mut World,
)
fn init_access( state: &Self::State, system_meta: &mut SystemMeta, component_access_set: &mut FilteredAccessSet, world: &mut World, )
Registers any World access used by this SystemParam.
This method must panic if the access would conflict with any existing access in the FilteredAccessSet.
Sourceunsafe fn get_param<'world, 'state>(
state: &'state mut Self::State,
system_meta: &SystemMeta,
world: UnsafeWorldCell<'world>,
change_tick: Tick,
) -> Result<Self::Item<'world, 'state>, SystemParamValidationError>
unsafe fn get_param<'world, 'state>( state: &'state mut Self::State, system_meta: &SystemMeta, world: UnsafeWorldCell<'world>, change_tick: Tick, ) -> Result<Self::Item<'world, 'state>, SystemParamValidationError>
Creates a parameter to be passed into a SystemParamFunction.
This method also validates that the param can be acquired. If validation fails,
an appropriate SystemParamValidationError should be returned.
Systems will convert this to a RunSystemError,
and the built-in executors will ignore any “skipped” validation results,
but pass any “invalid” results to the fallback error handler defined in bevy_ecs::error.
For nested SystemParams validation will fail if any
delegated validation fails.
§Safety
- The passed
UnsafeWorldCellmust have access to any world data registered ininit_access. SystemParam::init_accessmust not request conflicting access. IfSelfisReadOnlySystemParam, the access is read-only and can never conflict. Otherwise,SystemParam::init_accessmust be called to ensure it does not panic.worldmust be the sameWorldthat was used to initializestate.
Provided Methods§
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 ApplyDeferred.
Sourcefn queue(
state: &mut Self::State,
system_meta: &SystemMeta,
world: DeferredWorld<'_>,
)
fn queue( state: &mut Self::State, system_meta: &SystemMeta, world: DeferredWorld<'_>, )
Queues any deferred mutations to be applied at the next ApplyDeferred.
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.