Struct bevy::ecs::system::SystemState

pub struct SystemState<Param> where
    Param: SystemParam,  { /* private fields */ }

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 and Changed query filters
• Local variables that hold state
• EventReader system parameters, which rely on a Local 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, 

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, 

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

Retrieve the mutable SystemParam values.

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

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, 

fn from_world(world: &mut World) -> SystemState<Param>

Creates Self using data from the given World