Struct bevy::ecs::system::SystemState
[−]pub struct SystemState<Param> where
Param: SystemParam, { /* private fields */ }
Expand description
Holds on to persistent state required to drive SystemParam
for a System
.
This is a very powerful and convenient tool for working with exclusive world access,
allowing you to fetch data from the World
as if you were running a System
.
Borrow-checking is handled for you, allowing you to mutably access multiple compatible system parameters at once,
and arbitrary system parameters (like EventWriter
) can be conveniently fetched.
For an alternative approach to split mutable access to the world, see World::resource_scope
.
Warning
SystemState
values created can be cached to improve performance,
and must be cached and reused in order for system parameters that rely on local state to work correctly.
These include:
Added
andChanged
query filtersLocal
variables that hold stateEventReader
system parameters, which rely on aLocal
to track which events have been seen
Example
Basic usage:
use bevy_ecs::prelude::*;
use bevy_ecs::{system::SystemState};
use bevy_ecs::event::Events;
struct MyEvent;
struct MyResource(u32);
#[derive(Component)]
struct MyComponent;
// Work directly on the `World`
let mut world = World::new();
world.init_resource::<Events<MyEvent>>();
// Construct a `SystemState` struct, passing in a tuple of `SystemParam`
// as if you were writing an ordinary system.
let mut system_state: SystemState<(
EventWriter<MyEvent>,
Option<ResMut<MyResource>>,
Query<&MyComponent>,
)> = SystemState::new(&mut world);
// Use system_state.get_mut(&mut world) and unpack your system parameters into variables!
// system_state.get(&world) provides read-only versions of your system parameters instead.
let (event_writer, maybe_resource, query) = system_state.get_mut(&mut world);
Caching:
use bevy_ecs::prelude::*;
use bevy_ecs::{system::SystemState};
use bevy_ecs::event::Events;
struct MyEvent;
struct CachedSystemState<'w, 's>{
event_state: SystemState<EventReader<'w, 's, MyEvent>>
}
// Create and store a system state once
let mut world = World::new();
world.init_resource::<Events<MyEvent>>();
let initial_state: SystemState<EventReader<MyEvent>> = SystemState::new(&mut world);
// The system state is cached in a resource
world.insert_resource(CachedSystemState{event_state: initial_state});
// Later, fetch the cached system state, saving on overhead
world.resource_scope(|world, mut cached_state: Mut<CachedSystemState>| {
let mut event_reader = cached_state.event_state.get_mut(world);
for events in event_reader.iter() {
println!("Hello World!");
};
});
Implementations
impl<Param> SystemState<Param> where
Param: SystemParam,
impl<Param> SystemState<Param> where
Param: SystemParam,
pub fn new(world: &mut World) -> SystemState<Param>
pub fn meta(&self) -> &SystemMeta
pub fn get(
&'s mut self,
world: &'w World
) -> <<Param as SystemParam>::Fetch as SystemParamFetch<'w, 's>>::Item where
<Param as SystemParam>::Fetch: ReadOnlySystemParamFetch,
pub fn get(
&'s mut self,
world: &'w World
) -> <<Param as SystemParam>::Fetch as SystemParamFetch<'w, 's>>::Item where
<Param as SystemParam>::Fetch: ReadOnlySystemParamFetch,
Retrieve the SystemParam
values. This can only be called when all parameters are read-only.
pub fn get_mut(
&'s mut self,
world: &'w mut World
) -> <<Param as SystemParam>::Fetch as SystemParamFetch<'w, 's>>::Item
pub fn get_mut(
&'s mut self,
world: &'w mut World
) -> <<Param as SystemParam>::Fetch as SystemParamFetch<'w, 's>>::Item
Retrieve the mutable SystemParam
values.
pub fn apply(&mut self, world: &mut World)
pub fn apply(&mut self, world: &mut World)
Applies all state queued up for SystemParam
values. For example, this will apply commands queued up
by a Commands
parameter to the given World
.
This function should be called manually after the values returned by SystemState::get
and SystemState::get_mut
are finished being used.
pub fn matches_world(&self, world: &World) -> bool
pub unsafe fn get_unchecked_manual(
&'s mut self,
world: &'w World
) -> <<Param as SystemParam>::Fetch as SystemParamFetch<'w, 's>>::Item
pub unsafe fn get_unchecked_manual(
&'s mut self,
world: &'w World
) -> <<Param as SystemParam>::Fetch as SystemParamFetch<'w, 's>>::Item
Retrieve the SystemParam
values. This will not update archetypes automatically.
Safety
This call might access any of the input parameters in a way that violates Rust’s mutability rules. Make sure the data
access is safe in the context of global World
access. The passed-in World
must be the World
the SystemState
was
created with.
Trait Implementations
impl<Param> FromWorld for SystemState<Param> where
Param: SystemParam,
impl<Param> FromWorld for SystemState<Param> where
Param: SystemParam,
fn from_world(world: &mut World) -> SystemState<Param>
fn from_world(world: &mut World) -> SystemState<Param>
Creates Self
using data from the given World
Auto Trait Implementations
impl<Param> RefUnwindSafe for SystemState<Param> where
<Param as SystemParam>::Fetch: RefUnwindSafe,
impl<Param> Send for SystemState<Param>
impl<Param> Sync for SystemState<Param>
impl<Param> Unpin for SystemState<Param> where
<Param as SystemParam>::Fetch: Unpin,
impl<Param> UnwindSafe for SystemState<Param> where
<Param as SystemParam>::Fetch: UnwindSafe,
Blanket Implementations
impl<T, U> AsBindGroupShaderType<U> for T where
U: ShaderType,
&'a T: for<'a> Into<U>,
impl<T, U> AsBindGroupShaderType<U> for T where
U: ShaderType,
&'a T: for<'a> Into<U>,
fn as_bind_group_shader_type(
&self,
_images: &HashMap<Handle<Image>, <Image as RenderAsset>::PreparedAsset, RandomState, Global>
) -> U
fn as_bind_group_shader_type(
&self,
_images: &HashMap<Handle<Image>, <Image as RenderAsset>::PreparedAsset, RandomState, Global>
) -> U
Return the T
ShaderType
for self
. When used in AsBindGroup
derives, it is safe to assume that all images in self
exist. Read more
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
impl<T> Downcast for T where
T: Any,
impl<T> Downcast for T where
T: Any,
fn into_any(self: Box<T, Global>) -> Box<dyn Any + 'static, Global>
fn into_any(self: Box<T, Global>) -> Box<dyn Any + 'static, Global>
Convert Box<dyn Trait>
(where Trait: Downcast
) to Box<dyn Any>
. Box<dyn Any>
can
then be further downcast
into Box<ConcreteType>
where ConcreteType
implements Trait
. Read more
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any + 'static>
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any + 'static>
Convert Rc<Trait>
(where Trait: Downcast
) to Rc<Any>
. Rc<Any>
can then be
further downcast
into Rc<ConcreteType>
where ConcreteType
implements Trait
. Read more
fn as_any(&self) -> &(dyn Any + 'static)
fn as_any(&self) -> &(dyn Any + 'static)
Convert &Trait
(where Trait: Downcast
) to &Any
. This is needed since Rust cannot
generate &Any
’s vtable from &Trait
’s. Read more
fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
Convert &mut Trait
(where Trait: Downcast
) to &Any
. This is needed since Rust cannot
generate &mut Any
’s vtable from &mut Trait
’s. Read more
sourceimpl<T> Instrument for T
impl<T> Instrument for T
sourcefn instrument(self, span: Span) -> Instrumented<Self>ⓘNotable traits for Instrumented<T>impl<T> Future for Instrumented<T> where
T: Future, type Output = <T as Future>::Output;
fn instrument(self, span: Span) -> Instrumented<Self>ⓘNotable traits for Instrumented<T>impl<T> Future for Instrumented<T> where
T: Future, type Output = <T as Future>::Output;
T: Future, type Output = <T as Future>::Output;
sourcefn in_current_span(self) -> Instrumented<Self>ⓘNotable traits for Instrumented<T>impl<T> Future for Instrumented<T> where
T: Future, type Output = <T as Future>::Output;
fn in_current_span(self) -> Instrumented<Self>ⓘNotable traits for Instrumented<T>impl<T> Future for Instrumented<T> where
T: Future, type Output = <T as Future>::Output;
T: Future, type Output = <T as Future>::Output;
sourceimpl<T> WithSubscriber for T
impl<T> WithSubscriber for T
sourcefn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>ⓘNotable traits for WithDispatch<T>impl<T> Future for WithDispatch<T> where
T: Future, type Output = <T as Future>::Output;
where
S: Into<Dispatch>,
fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>ⓘNotable traits for WithDispatch<T>impl<T> Future for WithDispatch<T> where
T: Future, type Output = <T as Future>::Output;
where
S: Into<Dispatch>,
T: Future, type Output = <T as Future>::Output;
Attaches the provided Subscriber
to this type, returning a
WithDispatch
wrapper. Read more
sourcefn with_current_subscriber(self) -> WithDispatch<Self>ⓘNotable traits for WithDispatch<T>impl<T> Future for WithDispatch<T> where
T: Future, type Output = <T as Future>::Output;
fn with_current_subscriber(self) -> WithDispatch<Self>ⓘNotable traits for WithDispatch<T>impl<T> Future for WithDispatch<T> where
T: Future, type Output = <T as Future>::Output;
T: Future, type Output = <T as Future>::Output;
Attaches the current default Subscriber
to this type, returning a
WithDispatch
wrapper. Read more