Struct bevy_ecs::system::SystemState
source · pub struct SystemState<Param: SystemParam + 'static> { /* 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);
// If you are using [`Commands`], you can choose when you want to apply them to the world.
// You need to manually call `.apply(world)` on the [`SystemState`] to apply them.
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§
source§impl<Param: SystemParam> SystemState<Param>
impl<Param: SystemParam> SystemState<Param>
pub fn new(world: &mut World) -> Self
pub fn meta(&self) -> &SystemMeta
sourcepub fn get<'w, 's>(
&'s mut self,
world: &'w World
) -> SystemParamItem<'w, 's, Param>where
Param: ReadOnlySystemParam,
pub fn get<'w, 's>( &'s mut self, world: &'w World ) -> SystemParamItem<'w, 's, Param>where Param: ReadOnlySystemParam,
Retrieve the SystemParam
values. This can only be called when all parameters are read-only.
sourcepub fn get_mut<'w, 's>(
&'s mut self,
world: &'w mut World
) -> SystemParamItem<'w, 's, Param>
pub fn get_mut<'w, 's>( &'s mut self, world: &'w mut World ) -> SystemParamItem<'w, 's, Param>
Retrieve the mutable SystemParam
values.
sourcepub 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
sourcepub fn update_archetypes(&mut self, world: &World)
pub fn update_archetypes(&mut self, world: &World)
Updates the state’s internal view of the world
’s archetypes. If this is not called before fetching the parameters,
the results may not accurately reflect what is in the world
.
This is only required if SystemState::get_manual
or SystemState::get_manual_mut
is being called, and it only needs to
be called if the world
has been structurally mutated (i.e. added/removed a component or resource). Users using
SystemState::get
or SystemState::get_mut
do not need to call this as it will be automatically called for them.
sourcepub fn get_manual<'w, 's>(
&'s mut self,
world: &'w World
) -> SystemParamItem<'w, 's, Param>where
Param: ReadOnlySystemParam,
pub fn get_manual<'w, 's>( &'s mut self, world: &'w World ) -> SystemParamItem<'w, 's, Param>where Param: ReadOnlySystemParam,
Retrieve the SystemParam
values. This can only be called when all parameters are read-only.
This will not update the state’s view of the world’s archetypes automatically nor increment the
world’s change tick.
For this to return accurate results, ensure SystemState::update_archetypes
is called before this
function.
Users should strongly prefer to use SystemState::get
over this function.
sourcepub fn get_manual_mut<'w, 's>(
&'s mut self,
world: &'w mut World
) -> SystemParamItem<'w, 's, Param>
pub fn get_manual_mut<'w, 's>( &'s mut self, world: &'w mut World ) -> SystemParamItem<'w, 's, Param>
Retrieve the mutable SystemParam
values. This will not update the state’s view of the world’s archetypes
automatically nor increment the world’s change tick.
For this to return accurate results, ensure SystemState::update_archetypes
is called before this
function.
Users should strongly prefer to use SystemState::get_mut
over this function.
sourcepub unsafe fn get_unchecked_manual<'w, 's>(
&'s mut self,
world: &'w World
) -> SystemParamItem<'w, 's, Param>
pub unsafe fn get_unchecked_manual<'w, 's>( &'s mut self, world: &'w World ) -> SystemParamItem<'w, 's, Param>
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§
source§impl<'a, P: SystemParam + 'static> ExclusiveSystemParam for &'a mut SystemState<P>
impl<'a, P: SystemParam + 'static> ExclusiveSystemParam for &'a mut SystemState<P>
type State = SystemState<P>
type Item<'s> = &'s mut SystemState<P>
fn init(world: &mut World, _system_meta: &mut SystemMeta) -> Self::State
fn get_param<'s>( state: &'s mut Self::State, _system_meta: &SystemMeta ) -> Self::Item<'s>
source§impl<Param: SystemParam> FromWorld for SystemState<Param>
impl<Param: SystemParam> FromWorld for SystemState<Param>
source§fn from_world(world: &mut World) -> Self
fn from_world(world: &mut World) -> Self
Self
using data from the given WorldAuto Trait Implementations§
impl<Param> RefUnwindSafe for SystemState<Param>where <Param as SystemParam>::State: RefUnwindSafe,
impl<Param> Send for SystemState<Param>
impl<Param> Sync for SystemState<Param>
impl<Param> Unpin for SystemState<Param>where <Param as SystemParam>::State: Unpin,
impl<Param> UnwindSafe for SystemState<Param>where <Param as SystemParam>::State: UnwindSafe,
Blanket Implementations§
source§impl<T> Downcast for Twhere
T: Any,
impl<T> Downcast for Twhere T: Any,
source§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
.source§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
.source§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.source§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.