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 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
.
However, simply calling world::run_system(my_system)
using a World::run_system
can be significantly simpler and ensures that change detection and command flushing work as expected.
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
Note that this is automatically handled for you when using a World::run_system
.
§Example
Basic usage:
// 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:
#[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.read() {
println!("Hello World!");
}
});
Implementations§
source§impl<Param: SystemParam> SystemState<Param>
impl<Param: SystemParam> SystemState<Param>
sourcepub fn new(world: &mut World) -> Self
pub fn new(world: &mut World) -> Self
Creates a new SystemState
with default state.
§Note
For users of SystemState::get_manual
or get_manual_mut
:
new
does not cache any of the world’s archetypes, so you must call SystemState::update_archetypes
manually before calling get_manual{_mut}
.
sourcepub fn meta(&self) -> &SystemMeta
pub fn meta(&self) -> &SystemMeta
Gets the metadata for this instance.
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.
sourcepub fn matches_world(&self, world_id: WorldId) -> bool
pub fn matches_world(&self, world_id: WorldId) -> bool
Returns true
if world_id
matches the World
that was used to call SystemState::new
.
Otherwise, this returns false.
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 update_archetypes_unsafe_world_cell(
&mut self,
world: UnsafeWorldCell<'_>
)
pub fn update_archetypes_unsafe_world_cell( &mut self, world: UnsafeWorldCell<'_> )
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.
§Note
This method only accesses world metadata.
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: UnsafeWorldCell<'w>
) -> SystemParamItem<'w, 's, Param>
pub unsafe fn get_unchecked_manual<'w, 's>( &'s mut self, world: UnsafeWorldCell<'w> ) -> 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 State = SystemState<P>
§type Item<'s> = &'s mut SystemState<P>
type Item<'s> = &'s mut SystemState<P>
SystemParam::Item
.source§fn init(world: &mut World, _system_meta: &mut SystemMeta) -> Self::State
fn init(world: &mut World, _system_meta: &mut SystemMeta) -> Self::State
State
.source§fn get_param<'s>(
state: &'s mut Self::State,
_system_meta: &SystemMeta
) -> Self::Item<'s>
fn get_param<'s>( state: &'s mut Self::State, _system_meta: &SystemMeta ) -> Self::Item<'s>
ExclusiveSystemParamFunction
.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 World
.Auto Trait Implementations§
impl<Param> Freeze for SystemState<Param>
impl<Param> RefUnwindSafe for SystemState<Param>
impl<Param> Send for SystemState<Param>
impl<Param> Sync for SystemState<Param>
impl<Param> Unpin for SystemState<Param>
impl<Param> UnwindSafe for SystemState<Param>
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> Downcast for Twhere
T: Any,
impl<T> Downcast for Twhere
T: Any,
source§fn into_any(self: Box<T>) -> Box<dyn Any>
fn into_any(self: Box<T>) -> Box<dyn Any>
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>
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
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.