Trait specs::WorldExt

pub trait WorldExt {
    fn new() -> Self;
    fn register<T: Component>(&mut self)
    where
        T::Storage: Default;
    fn register_with_storage<F, T>(&mut self, storage: F)
    where
        F: FnOnce() -> T::Storage,
        T: Component;
    fn add_resource<T: Resource>(&mut self, res: T);
    fn read_component<T: Component>(&self) -> ReadStorage<'_, T>;
    fn write_component<T: Component>(&self) -> WriteStorage<'_, T>;
    fn read_resource<T: Resource>(&self) -> Fetch<'_, T>;
    fn write_resource<T: Resource>(&self) -> FetchMut<'_, T>;
    fn entities(&self) -> Read<'_, EntitiesRes>;
    fn entities_mut(&self) -> FetchMut<'_, EntitiesRes>;
    fn create_entity(&mut self) -> EntityBuilder<'_>;
    fn create_entity_unchecked(&self) -> EntityBuilder<'_>;
    fn create_iter(&mut self) -> CreateIter<'_>;
    fn delete_entity(&mut self, entity: Entity) -> Result<(), WrongGeneration>;
    fn delete_entities(
        &mut self,
        delete: &[Entity]
    ) -> Result<(), WrongGeneration>;
    fn delete_all(&mut self);
    fn is_alive(&self, e: Entity) -> bool;
    fn maintain(&mut self);

    fn read_storage<T: Component>(&self) -> ReadStorage<'_, T> { ... }
    fn write_storage<T: Component>(&self) -> WriteStorage<'_, T> { ... }
}

This trait provides some extension methods to make working with shred’s World easier.

Many methods take &self which works because everything is stored with interior mutability. In case you violate the borrowing rules of Rust (multiple reads xor one write), you will get a panic.

Difference between resources and components

While components exist per Entity, resources are like globals in the World. Components are stored in component storages (MaskedStorage), which are resources themselves.

Everything that is Any + Send + Sync can be a resource.

Built-in resources

There are two built-in resources:

• LazyUpdate and
• EntitiesRes

Both of them should only be fetched immutably, which is why the latter one has a type def for convenience: Entities which is just Fetch<EntitiesRes>. Both resources are special and need to execute code at the end of the frame, which is done in World::maintain.

Examples

use specs::prelude::*;

let mut world = World::new();
world.register::<Pos>();
world.register::<Vel>();

world.insert(DeltaTime(0.02));

world
    .create_entity()
    .with(Pos { x: 1.0, y: 2.0 })
    .with(Vel { x: -1.0, y: 0.0 })
    .build();

let b = world
    .create_entity()
    .with(Pos { x: 3.0, y: 5.0 })
    .with(Vel { x: 1.0, y: 0.0 })
    .build();

let c = world
    .create_entity()
    .with(Pos { x: 0.0, y: 1.0 })
    .with(Vel { x: 0.0, y: 1.0 })
    .build();

{
    // `World::read_storage` returns a component storage.
    let pos_storage = world.read_storage::<Pos>();
    let vel_storage = world.read_storage::<Vel>();

    // `Storage::get` allows to get a component from it:
    assert_eq!(pos_storage.get(b), Some(&Pos { x: 3.0, y: 5.0 }));
    assert_eq!(vel_storage.get(c), Some(&Vel { x: 0.0, y: 1.0 }));
}

let empty = world.create_entity().build();

{
    // This time, we write to the `Pos` storage:
    let mut pos_storage = world.write_storage::<Pos>();
    let vel_storage = world.read_storage::<Vel>();

    assert!(pos_storage.get(empty).is_none());

    // You can also insert components after creating the entity:
    pos_storage.insert(empty, Pos { x: 3.1, y: 4.15 });

    assert!(pos_storage.get(empty).is_some());
}

Required Methods

fn new() -> Self

Constructs a new World instance.

fn register<T: Component>(&mut self) where
    T::Storage: Default, 

Registers a new component, adding the component storage.

Calls register_with_storage with Default::default().

Does nothing if the component was already registered.

Examples

use specs::prelude::*;

struct Pos {
    x: f32,
    y: f32,
}

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

let mut world = World::new();
world.register::<Pos>();
// Register all other components like this

fn register_with_storage<F, T>(&mut self, storage: F) where
    F: FnOnce() -> T::Storage,
    T: Component, 

Registers a new component with a given storage.

Does nothing if the component was already registered.

fn add_resource<T: Resource>(&mut self, res: T)

👎 Deprecated since 0.15.0:

use World::insert instead

Adds a resource to the world.

If the resource already exists it will be overwritten.

DEPRECATED: Use World::insert instead.

Examples

use specs::prelude::*;

let mut world = World::new();
world.insert(timer);
world.insert(server_con);

fn read_component<T: Component>(&self) -> ReadStorage<'_, T>

Fetches a component storage for reading.

Panics

Panics if it is already borrowed mutably. Panics if the component has not been registered.

fn write_component<T: Component>(&self) -> WriteStorage<'_, T>

Fetches a component storage for writing.

Panics

Panics if it is already borrowed. Panics if the component has not been registered.

fn read_resource<T: Resource>(&self) -> Fetch<'_, T>

Fetches a resource for reading.

Panics

Panics if it is already borrowed mutably. Panics if the resource has not been added.

fn write_resource<T: Resource>(&self) -> FetchMut<'_, T>

Fetches a resource for writing.

Panics

Panics if it is already borrowed. Panics if the resource has not been added.

fn entities(&self) -> Read<'_, EntitiesRes>

Convenience method for fetching entities.

Creation and deletion of entities with the Entities struct are atomically, so the actual changes will be applied with the next call to maintain().

fn entities_mut(&self) -> FetchMut<'_, EntitiesRes>

Convenience method for fetching entities.

fn create_entity(&mut self) -> EntityBuilder<'_>

Allows building an entity with its components.

This takes a mutable reference to the World, since no component storage this builder accesses may be borrowed. If it’s necessary that you borrow a resource from the World while this builder is alive, you can use create_entity_unchecked.

fn create_entity_unchecked(&self) -> EntityBuilder<'_>

Allows building an entity with its components.

You have to make sure that no component storage is borrowed during the building!

This variant is only recommended if you need to borrow a resource during the entity building. If possible, try to use create_entity.

fn create_iter(&mut self) -> CreateIter<'_>

Returns an iterator for entity creation. This makes it easy to create a whole collection of them.

Examples

use specs::prelude::*;

let mut world = World::new();
let five_entities: Vec<_> = world.create_iter().take(5).collect();

fn delete_entity(&mut self, entity: Entity) -> Result<(), WrongGeneration>

Deletes an entity and its components.

fn delete_entities(&mut self, delete: &[Entity]) -> Result<(), WrongGeneration>

Deletes the specified entities and their components.

fn delete_all(&mut self)

Deletes all entities and their components.

fn is_alive(&self, e: Entity) -> bool

Checks if an entity is alive. Please note that atomically created or deleted entities (the ones created / deleted with the Entities struct) are not handled by this method. Therefore, you should have called maintain() before using this method.

If you want to get this functionality before a maintain(), you are most likely in a system; from there, just access the Entities resource and call the is_alive method.

Panics

Panics if generation is dead.

fn maintain(&mut self)

Merges in the appendix, recording all the dynamically created and deleted entities into the persistent generations vector. Also removes all the abandoned components.

Additionally, LazyUpdate will be merged.

Provided Methods

fn read_storage<T: Component>(&self) -> ReadStorage<'_, T>

Fetches a component storage for reading.

Panics

Panics if it is already borrowed mutably. Panics if the component has not been registered.

fn write_storage<T: Component>(&self) -> WriteStorage<'_, T>

Fetches a component storage for writing.

Panics

Panics if it is already borrowed. Panics if the component has not been registered.

Implementors

impl WorldExt for World