Type Definition specs::prelude::ReadStorage

type ReadStorage<'a, T> = Storage<'a, T, Fetch<'a, MaskedStorage<T>>>;

A storage with read access.

This is just a type alias for a fetched component storage.

The main functionality it provides is listed in the following, however make sure to also check out the documentation for the respective methods on Storage.

Aliasing

It is strictly disallowed to fetch both a ReadStorage and a WriteStorage of the same component. Because Specs uses interior mutability for its resources, we can't check this at compile time. If you try to do this, you will get a panic.

It is explicitly allowed to fetch multiple ReadStorages for the same component.

Joining storages

&ReadStorage implements Join, which allows to do something like this:

(&pos_storage, &vel_storage).join()

This joins the position and the velocity storage, which means it only iterates over the components of entities that have both a position and a velocity.

Retrieving single components

If you have an entity (for example because you stored it before or because you're joining over Entities), you can get a single component by calling Storage::get:

let entity1 = world.create_entity()
    .with(Pos)
    .build();
let entity2 = world.create_entity()
    .with(Vel)
    .build();

assert_eq!(pos_storage.get(entity1), Some(&Pos));
assert_eq!(pos_storage.get(entity2), None);

assert_eq!(vel_storage.get(entity1), None);
assert_eq!(vel_storage.get(entity2), Some(&Vel));

Usage as SystemData

ReadStorage implements SystemData which allows you to fetch it inside a system by simply adding it to the tuple:

#[derive(Debug)]
struct Pos {
    x: f32,
    y: f32,
}

impl Component for Pos {
    type Storage = VecStorage<Self>;
}

struct Sys;

impl<'a> System<'a> for Sys {
    type SystemData = (Entities<'a>, ReadStorage<'a, Pos>);

    fn run(&mut self, (ent, pos): Self::SystemData) {
        for (ent, pos) in (&*ent, &pos).join() {
            println!("Entitiy with id {} has a position of {:?}", ent.id(), pos);
        }
    }
}

These operations can't mutate anything; if you want to do insertions or modify components, you need to use WriteStorage. Note that you can also use LazyUpdate , which does insertions on World::maintain. This allows more concurrency and is designed to be used for entity initialization.

Trait Implementations

impl<'a, T> SystemData<'a> for ReadStorage<'a, T> where
    T: Component, 

fn fetch(res: &'a Resources) -> Self

Creates a new resource bundle by fetching the required resources from the [Resources] struct.

Important traits for Vec<u8>

impl Write for Vec<u8>

fn reads() -> Vec<ResourceId>

A list of [ResourceId]s the bundle needs read access to in order to build the target resource bundle.

Important traits for Vec<u8>

impl Write for Vec<u8>

fn writes() -> Vec<ResourceId>

A list of [ResourceId]s the bundle needs write access to in order to build the target resource bundle.

fn setup(res: &mut Resources)

Sets up Resources for fetching this system data.