Struct specs::prelude::World

pub struct World { /* fields omitted */ }

A [Resource] container, which provides methods to insert, access and manage the contained resources.

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.

Use with Specs

If you're using this from the Specs ECS library, there are two things to be aware of:

1. There are many utility methods Specs provides. To use them, you need to import specs::WorldExt.
2. You should not use [World::empty], but rather specs::WorldExt::new. The latter can simply be called using World::new(), as long as WorldExt is imported.

Resource Ids

Resources are identified by ResourceIds, which consist of a TypeId.

Methods

impl World

pub fn empty() -> World

Creates a new, empty resource container.

Note that if you're using Specs, you should use WorldExt::new instead.

pub fn insert<R>(&mut self, r: R) where
    R: Resource, 

Inserts a resource into this container. If the resource existed before, it will be overwritten.

Examples

Every type satisfying Any + Send + Sync automatically implements Resource, thus can be added:

struct MyRes(i32);

When you have a resource, simply insert it like this:

use shred::World;

let mut world = World::empty();
world.insert(MyRes(5));

pub fn remove<R>(&mut self) -> Option<R> where
    R: Resource, 

Removes a resource of type R from the World and returns its ownership to the caller. In case there is no such resource in this World, None will be returned.

Use this method with caution; other functions and systems might assume this resource still exists. Thus, only use this if you're sure no system will try to access this resource after you removed it (or else you will get a panic).

pub fn has_value<R>(&self) -> bool where
    R: Resource, 

Returns true if the specified resource type R exists in self.

pub fn has_value_raw(&self, id: ResourceId) -> bool

Returns true if the specified resource type exists in self.

pub fn entry<R>(&mut self) -> Entry<R> where
    R: Resource, 

Returns an entry for the resource with type R.

pub fn system_data<'a, T>(&'a self) -> T where
    T: SystemData<'a>, 

Gets SystemData T from the World. This can be used to retrieve data just like in Systems.

This will not setup the system data, i.e. resources fetched here must exist already.

Examples

// NOTE: If you use Specs, use `World::new` instead.
let mut world = World::empty();
world.insert(Timer);
world.insert(AnotherResource);
let system_data: (Read<Timer>, Read<AnotherResource>) = world.system_data();

Panics

• Panics if T is already borrowed in an incompatible way.

pub fn setup<'a, T>(&mut self) where
    T: SystemData<'a>, 

Sets up system data T for fetching afterwards.

Most SystemData implementations will insert a sensible default value, by implementing [SystemData::setup]. However, it is not guaranteed to do that; if there is no sensible default, setup might not do anything.

Examples

use shred::{Read, World};

#[derive(Default)]
struct MyCounter(u32);

// NOTE: If you use Specs, use `World::new` instead.
let mut world = World::empty();
assert!(!world.has_value::<MyCounter>());

// `Read<MyCounter>` requires a `Default` implementation, and uses
// that to initialize the resource
world.setup::<Read<MyCounter>>();
assert!(world.has_value::<MyCounter>());

Here's another example, showing the case where no resource gets initialized:

use shred::{ReadExpect, World};

struct MyCounter(u32);

// NOTE: If you use Specs, use `World::new` instead.
let mut world = World::empty();

world.setup::<ReadExpect<MyCounter>>();

pub fn exec<'a, F, R, T>(&'a mut self, f: F) -> R where
    F: FnOnce(T) -> R,
    T: SystemData<'a>, 

Executes f once, right now and with the specified system data.

This sets up the system data f expects, fetches it and then executes f. This is essentially like a one-time System.

This is especially useful if you either need a lot of system data or, with Specs, if you want to build an entity and for that you need to access resources first - just fetching the resources and building the entity would cause a double borrow.

Calling this method is equivalent to:

{
    // note the extra scope
    world.setup::<MySystemData>();
    let my_data: MySystemData = world.system_data();
    my_data.do_something();
}

Examples

// NOTE: If you use Specs, use `World::new` instead.
let mut world = World::empty();

#[derive(Default)]
struct MyRes {
    field: i32,
}

world.exec(|(mut my_res,): (Write<MyRes>,)| {
    assert_eq!(my_res.field, 0);
    my_res.field = 5;
});

assert_eq!(world.fetch::<MyRes>().field, 5);

pub fn fetch<T>(&self) -> Fetch<T> where
    T: Resource, 

Fetches the resource with the specified type T or panics if it doesn't exist.

Panics

Panics if the resource doesn't exist. Panics if the resource is being accessed mutably.

pub fn try_fetch<T>(&self) -> Option<Fetch<T>> where
    T: Resource, 

Like fetch, but returns an Option instead of inserting a default value in case the resource does not exist.

pub fn try_fetch_by_id<T>(&self, id: ResourceId) -> Option<Fetch<T>> where
    T: Resource, 

Like try_fetch, but fetches the resource by its ResourceId which allows using a dynamic ID.

This is usually not what you need; please read the type-level documentation of ResourceId.

Panics

This method panics if id refers to a different type ID than T.

pub fn fetch_mut<T>(&self) -> FetchMut<T> where
    T: Resource, 

Fetches the resource with the specified type T mutably.

Please see fetch for details.

Panics

Panics if the resource doesn't exist. Panics if the resource is already being accessed.

pub fn try_fetch_mut<T>(&self) -> Option<FetchMut<T>> where
    T: Resource, 

Like fetch_mut, but returns an Option instead of inserting a default value in case the resource does not exist.

pub fn try_fetch_mut_by_id<T>(&self, id: ResourceId) -> Option<FetchMut<T>> where
    T: Resource, 

Like try_fetch_mut, but fetches the resource by its ResourceId which allows using a dynamic ID.

This is usually not what you need; please read the type-level documentation of ResourceId.

Panics

This method panics if id refers to a different type ID than T.

pub fn insert_by_id<R>(&mut self, id: ResourceId, r: R) where
    R: Resource, 

Internal function for inserting resources, should only be used if you know what you're doing.

This is useful for inserting resources with a custom ResourceId.

Panics

This method panics if id refers to a different type ID than R.

pub fn remove_by_id<R>(&mut self, id: ResourceId) -> Option<R> where
    R: Resource, 

Internal function for removing resources, should only be used if you know what you're doing.

This is useful for removing resources with a custom ResourceId.

Panics

This method panics if id refers to a different type ID than R.

pub fn try_fetch_internal(
    &self,
    id: ResourceId
) -> Option<&TrustCell<Box<dyn Resource + 'static>>>

Internal function for fetching resources, should only be used if you know what you're doing.

pub fn get_mut<T>(&mut self) -> Option<&mut T> where
    T: Resource, 

Retrieves a resource without fetching, which is cheaper, but only available with &mut self.

pub fn get_mut_raw(
    &mut self,
    id: ResourceId
) -> Option<&mut (dyn Resource + 'static)>

Retrieves a resource without fetching, which is cheaper, but only available with &mut self.

Trait Implementations

impl Default for World

fn default() -> World

Returns the "default value" for a type.

impl WorldExt for World

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.

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.

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

Deprecated since 0.15.0:

use World::insert instead

Adds a resource to the world.

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

Fetches a component storage for reading.

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

Fetches a component storage for writing.

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

Fetches a resource for reading.

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

Fetches a resource for writing.

fn entities(&self) -> Read<EntitiesRes>

Convenience method for fetching entities.

fn entities_mut(&self) -> FetchMut<EntitiesRes>

Convenience method for fetching entities.

fn create_entity(&mut self) -> EntityBuilder

Allows building an entity with its components.

fn create_entity_unchecked(&self) -> EntityBuilder

Allows building an entity with its components.

Important traits for CreateIter<'a>

impl<'a> Iterator for CreateIter<'a> type Item = Entity;

fn create_iter(&mut self) -> CreateIter

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

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.

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.

fn delete_components(&mut self, delete: &[Entity])

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

Fetches a component storage for reading.

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

Fetches a component storage for writing.