[][src]Struct specs::FlaggedStorage

pub struct FlaggedStorage<C, T = DenseVecStorage<C>> { /* fields omitted */ }

Wrapper storage that tracks modifications, insertions, and removals of components through an EventChannel.

Note: Joining over all components of a FlaggedStorage mutably will flag all components.

What you want to instead is to use restrict_mut() to first get the entities which contain the component and then conditionally modify the component after a call to get_mut_unchecked() or get_mut().

Examples

extern crate specs;

use specs::prelude::*;

pub struct Comp(u32);
impl Component for Comp {
    // `FlaggedStorage` acts as a wrapper around another storage.
    // You can put any store inside of here (e.g. HashMapStorage, VecStorage, etc.)
    //
    // It also works as `FlaggedStorage<Self>` and defaults to `DenseVecStorage<Self>`
    // for the inner storage.
    type Storage = FlaggedStorage<Self, VecStorage<Self>>;
}

pub struct CompSystem {
    // These keep track of where you left off in the event channel.
    reader_id: ReaderId<ComponentEvent>,

    // The bitsets you want to populate with modification/insertion events.
    modified: BitSet,
    inserted: BitSet,
}

impl<'a> System<'a> for CompSystem {
    type SystemData = (Entities<'a>, WriteStorage<'a, Comp>);
    fn run(&mut self, (entities, mut comps): Self::SystemData) {
        // We want to clear the bitset first so we don't have left over events
        // from the last frame.
        //
        // However, if you want to accumulate changes over a couple frames then you
        // can only clear it when necessary. (This might be useful if you have some
        // sort of "tick" system in your game and only want to do operations every
        // 1/4th of a second or something)
        //
        // It is not okay to only read the events in an interval though as that could
        // leave behind events which would end up growing the event ring buffer to
        // extreme sizes.
        self.modified.clear();
        self.inserted.clear();

        // Here we can populate the bitsets by iterating over the events.
        // You can also just iterate over the events without using a bitset which will
        // give you an ordered history of the events (which is good for caches and synchronizing
        // other storages, but this allows us to use them in joins with components.
        {
            let events = comps.channel()
                .read(&mut self.reader_id);
            for event in events {
                match event {
                    ComponentEvent::Modified(id) => { self.modified.add(*id); },
                    ComponentEvent::Inserted(id) => { self.inserted.add(*id); },
                    _ => { },
                };
            }
        }

        // Iterates over all components like normal.
        for comp in (&comps).join() {
            // ...
        }

        // **Never do this**
        // This will flag all components as modified regardless of whether the inner loop
        // actually modified the component.
        //
        // Only do this if you have other filters, like some other components to filter
        // out the ones you want to modify.
        for comp in (&mut comps).join() {
            // ...
        }

        // Instead you will want to restrict the amount of components iterated over, either through
        // other components in the join, or by using `RestrictedStorage` and only getting the component
        // mutably when you are sure you need to modify it.
        for (entity, mut comps) in (&entities, &mut comps.restrict_mut()).join() {
            if condition { // check whether this component should be modified.
                 let mut comp = comps.get_mut_unchecked();
                 // ...
            }
        }

        // To iterate over the modified components:
        for comp in (&comps, &self.modified).join() {
            // ...
        }

        // To iterate over all inserted/modified components;
        for comp in (&comps, &self.modified & &self.inserted).join() {
            // ...
        }
    }
}

fn main() {
    let mut world = World::new();
    world.register::<Comp>();

    // You will want to register the system `ReaderId`s
    // before adding/modifying/removing any entities and components.
    //
    // Otherwise you won't receive any of the modifications until
    // you start tracking them.
    let mut comp_system = {
        let mut comps = world.write_storage::<Comp>();
        CompSystem {
            reader_id: comps.register_reader(),
            modified: BitSet::new(),
            inserted: BitSet::new(),
        }
    };

    world.create_entity().with(Comp(19u32)).build();

    {
        let mut comps = world.write_storage::<Comp>();
        let events = comps.channel().read(&mut comp_system.reader_id);
        assert_eq!(events.len(), 1);
    }

    #[cfg(feature = "storage-event-control")]
    {
        world.write_storage::<Comp>().set_event_emission(false);
        world.create_entity().with(Comp(19u32)).build();

        {
            let mut comps = world.write_storage::<Comp>();
            let events = comps.channel().read(&mut comp_system.reader_id);
            assert_eq!(events.len(), 0);
        }

        world.write_storage::<Comp>().set_event_emission(true);
        world.create_entity().with(Comp(19u32)).build();

        {
            let mut comps = world.write_storage::<Comp>();
            let events = comps.channel().read(&mut comp_system.reader_id);
            assert_eq!(events.len(), 1);
        }
    }
}

Trait Implementations

impl<C, T> Tracked for FlaggedStorage<C, T>[src]

impl<C: Component, T: UnprotectedStorage<C>> UnprotectedStorage<C> for FlaggedStorage<C, T>[src]

unsafe fn drop(&mut self, id: Index)[src]

Drops the data associated with an Index. This is simply more efficient than remove and can be used if the data is no longer needed. Read more

impl<C, T> Default for FlaggedStorage<C, T> where
    T: TryDefault
[src]

Auto Trait Implementations

impl<C, T> Unpin for FlaggedStorage<C, T> where
    C: Unpin,
    T: Unpin

impl<C, T> Sync for FlaggedStorage<C, T> where
    C: Sync,
    T: Sync

impl<C, T> Send for FlaggedStorage<C, T> where
    C: Send,
    T: Send

impl<C, T = DenseVecStorage<C>> !UnwindSafe for FlaggedStorage<C, T>

impl<C, T = DenseVecStorage<C>> !RefUnwindSafe for FlaggedStorage<C, T>

Blanket Implementations

impl<T> TryDefault for T where
    T: Default
[src]

fn unwrap_default() -> Self[src]

Calls try_default and panics on an error case.

impl<T> From<T> for T[src]

impl<T, U> Into<U> for T where
    U: From<T>, 
[src]

impl<T, U> TryFrom<U> for T where
    U: Into<T>, 
[src]

type Error = Infallible

The type returned in the event of a conversion error.

impl<T, U> TryInto<U> for T where
    U: TryFrom<T>, 
[src]

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.

impl<T> Borrow<T> for T where
    T: ?Sized
[src]

impl<T> BorrowMut<T> for T where
    T: ?Sized
[src]

impl<T> Any for T where
    T: 'static + ?Sized
[src]

impl<T> Resource for T where
    T: Any + Send + Sync
[src]

impl<T> Any for T where
    T: Any
[src]

impl<T> Event for T where
    T: Send + Sync + 'static, 
[src]