pub unsafe trait SystemParamBuilder<P: SystemParam>: Sized {
// Required method
fn build(self, world: &mut World) -> P::State;
// Provided methods
fn build_state(self, world: &mut World) -> SystemState<P> { ... }
fn build_system<Marker, In, Out, Func>(
self,
func: Func,
) -> IntoBuilderSystem<Marker, In, Out, Func, Self>
where Self: 'static,
Func: SystemParamFunction<Marker, Param = P> { ... }
}Expand description
A builder that can create a SystemParam.
fn some_system(param: MyParam) {}
fn build_system(builder: impl SystemParamBuilder<MyParam> + 'static) {
// To build a system, create a tuple of `SystemParamBuilder`s
// with a builder for each parameter.
// Note that the builder for a system must be a tuple,
// even if there is only one parameter.
(builder,)
.build_system(some_system);
}
fn build_system_direct(builder: impl SystemParamBuilder<MyParam>) {
let mut world = World::new();
// You can also construct a system in two steps, first by
// constructing a [`SystemState`] with `build_state` and
// second by constructing the final system with `build_system`.
// This can be useful in cases that require type inference
// for function parameters (like closures!), since normal
// `build_system` requires explicitly specifying all parameter
// types. See `build_closure_system_infer/explicit` below for more
// info.
(builder,)
.build_state(&mut world)
.build_system(some_system);
}
fn build_closure_system_infer(builder: impl SystemParamBuilder<MyParam>) {
let mut world = World::new();
// Closures can be used in addition to named functions.
// If a closure is used, the parameter types must all be inferred
// from the builders, so you cannot use plain `ParamBuilder`.
(builder, ParamBuilder::resource())
.build_state(&mut world)
.build_system(|param, res| {
let param: MyParam = param;
let res: Res<R> = res;
});
}
fn build_closure_system_explicit(builder: impl SystemParamBuilder<MyParam>) {
let mut world = World::new();
// Alternately, you can provide all types in the closure
// parameter list and call `build_system()` normally.
(builder, ParamBuilder::resource())
.build_state(&mut world) // this line can be optionally omitted, since all the parameter types are explicit!
.build_system(|param: MyParam, res: Res<R>| {});
}See the documentation for individual builders for more examples.
§List of Builders
ParamBuilder can be used for parameters that don’t require any special building.
Using a ParamBuilder will build the system parameter the same way it would be initialized in an ordinary system.
ParamBuilder also provides factory methods that return a ParamBuilder typed as impl SystemParamBuilder<P>
for common system parameters that can be used to guide closure parameter inference.
QueryParamBuilder can build a Query to add additional filters,
or to configure the components available to FilteredEntityRef or FilteredEntityMut.
You can also use a QueryState to build a Query.
LocalBuilder can build a Local to supply the initial value for the Local.
FilteredResourcesParamBuilder can build a FilteredResources,
and FilteredResourcesMutParamBuilder can build a FilteredResourcesMut,
to configure the resources that can be accessed.
DynParamBuilder can build a DynSystemParam to determine the type of the inner parameter,
and to supply any SystemParamBuilder it needs.
Tuples of builders can build tuples of parameters, one builder for each element. Note that since systems require a tuple as a parameter, the outer builder for a system will always be a tuple.
A Vec of builders can build a Vec of parameters, one builder for each element.
A ParamSetBuilder can build a ParamSet.
This can wrap either a tuple or a Vec, one builder for each element.
A custom system param created with #[derive(SystemParam)] can be buildable if it includes a #[system_param(builder)] attribute.
See the documentation for SystemParam derives.
§Safety
The implementor must ensure that the state returned
from SystemParamBuilder::build is valid for P.
Note that the exact safety requirements depend on the implementation of SystemParam,
so if Self is not a local type then you must call SystemParam::init_state
or another SystemParamBuilder::build.
Required Methods§
Provided Methods§
Sourcefn build_state(self, world: &mut World) -> SystemState<P>
fn build_state(self, world: &mut World) -> SystemState<P>
Create a SystemState from a SystemParamBuilder.
To create a system, call SystemState::build_system on the result.
Sourcefn build_system<Marker, In, Out, Func>(
self,
func: Func,
) -> IntoBuilderSystem<Marker, In, Out, Func, Self>where
Self: 'static,
Func: SystemParamFunction<Marker, Param = P>,
fn build_system<Marker, In, Out, Func>(
self,
func: Func,
) -> IntoBuilderSystem<Marker, In, Out, Func, Self>where
Self: 'static,
Func: SystemParamFunction<Marker, Param = P>,
Create a System from a SystemParamBuilder directly.
This method is useful in cases where type inference for
closure parameters isn’t necessary, or where it’s not
possible to call SystemState::build_system by passing
in an &mut World. Rather than constructing the system’s
state immediately, this function returns a wrapper that
initializes the system state during the first run.
Caveats:
- doesn’t support parameter type inference.
- only works for ’static system param builder types.
In cases where either of these are required, call
SystemParamBuilder::build_state instead.
Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety".