Struct bevy::ecs::system::SystemState
pub struct SystemState<Param>where
Param: 'static + 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;
#[derive(Resource)]
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;
#[derive(Resource)]
struct CachedSystemState {
event_state: SystemState<EventReader<'static, 'static, 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<'w, 's>(
&'s mut self,
world: &'w World
) -> <<Param as SystemParam>::Fetch as SystemParamFetch<'w, 's>>::Itemwhere
<Param as SystemParam>::Fetch: ReadOnlySystemParamFetch,
pub fn get<'w, 's>(
&'s mut self,
world: &'w World
) -> <<Param as SystemParam>::Fetch as SystemParamFetch<'w, 's>>::Itemwhere
<Param as SystemParam>::Fetch: ReadOnlySystemParamFetch,
Retrieve the SystemParam
values. This can only be called when all parameters are read-only.
pub fn get_mut<'w, 's>(
&'s mut self,
world: &'w mut World
) -> <<Param as SystemParam>::Fetch as SystemParamFetch<'w, 's>>::Item
pub fn get_mut<'w, 's>(
&'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<'w, 's>(
&'s mut self,
world: &'w World
) -> <<Param as SystemParam>::Fetch as SystemParamFetch<'w, 's>>::Item
pub unsafe fn get_unchecked_manual<'w, 's>(
&'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<'a, P> ExclusiveSystemParam for &'a mut SystemState<P>where
P: 'static + SystemParam,
impl<'a, P> ExclusiveSystemParam for &'a mut SystemState<P>where
P: 'static + SystemParam,
type Fetch = SystemState<P>
§impl<'s, P> ExclusiveSystemParamFetch<'s> for SystemState<P>where
P: 'static + SystemParam,
impl<'s, P> ExclusiveSystemParamFetch<'s> for SystemState<P>where
P: 'static + SystemParam,
type Item = &'s mut SystemState<P>
fn get_param(
state: &'s mut SystemState<P>,
_system_meta: &SystemMeta
) -> <SystemState<P> as ExclusiveSystemParamFetch<'s>>::Item
§impl<P> ExclusiveSystemParamState for SystemState<P>where
P: SystemParam,
impl<P> ExclusiveSystemParamState for SystemState<P>where
P: SystemParam,
fn init(world: &mut World, _system_meta: &mut SystemMeta) -> SystemState<P>
fn apply(&mut self, _world: &mut World)
§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>
Self
using data from the given WorldAuto 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 Twhere
U: ShaderType,
&'a T: for<'a> Into<U>,
impl<T, U> AsBindGroupShaderType<U> for Twhere
U: ShaderType,
&'a T: for<'a> Into<U>,
§fn as_bind_group_shader_type(&self, _images: &RenderAssets<Image>) -> U
fn as_bind_group_shader_type(&self, _images: &RenderAssets<Image>) -> U
T
ShaderType
for self
. When used in AsBindGroup
derives, it is safe to assume that all images in self
exist. Read more§impl<T> Downcast for Twhere
T: Any,
impl<T> Downcast for Twhere
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>
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>
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)
&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)
&mut Trait
(where Trait: Downcast
) to &Any
. This is needed since Rust cannot
generate &mut Any
’s vtable from &mut Trait
’s. Read more