Struct specs::World [−][src]
pub struct World { /* fields omitted */ }
Expand description
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:
- There are many utility methods Specs provides. To use them, you need to
import
specs::WorldExt
. - You should not use World::empty, but rather
specs::WorldExt::new
. The latter can simply be called usingWorld::new()
, as long asWorldExt
is imported.
Resource Ids
Resources are identified by ResourceId
s, which consist of a TypeId
.
Implementations
Creates a new, empty resource container.
Note that if you’re using Specs, you should use WorldExt::new
instead.
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));
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).
Returns true if the specified resource type R
exists in self
.
Returns true if the specified resource type exists in self
.
Returns an entry for the resource with type R
.
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.
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>>();
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);
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.
Like fetch
, but returns an Option
instead of inserting a default
value in case the resource does not exist.
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
.
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.
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,
[src]
pub fn try_fetch_mut_by_id<T>(&self, id: ResourceId) -> Option<FetchMut<'_, T>> where
T: Resource,
[src]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
.
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
.
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, Global>>>
[src]
pub fn try_fetch_internal(
&self,
id: ResourceId
) -> Option<&TrustCell<Box<dyn Resource + 'static, Global>>>
[src]Internal function for fetching resources, should only be used if you know what you’re doing.
Retrieves a resource without fetching, which is cheaper, but only
available with &mut self
.
Retrieves a resource without fetching, which is cheaper, but only
available with &mut self
.
Trait Implementations
Registers a new component, adding the component storage. Read more
fn register_with_storage<F, T>(&mut self, storage: F) where
F: FnOnce() -> T::Storage,
T: Component,
[src]
fn register_with_storage<F, T>(&mut self, storage: F) where
F: FnOnce() -> T::Storage,
T: Component,
[src]Registers a new component with a given storage. Read more
Fetches a component storage for reading. Read more
Fetches a component storage for writing. Read more
Fetches a resource for reading. Read more
Fetches a resource for writing. Read more
Convenience method for fetching entities. Read more
Convenience method for fetching entities.
Allows building an entity with its components. Read more
Allows building an entity with its components. Read more
fn create_iter(&mut self) -> CreateIter<'_>ⓘNotable traits for CreateIter<'a>
impl<'a> Iterator for CreateIter<'a> type Item = Entity;
[src]
fn create_iter(&mut self) -> CreateIter<'_>ⓘNotable traits for CreateIter<'a>
impl<'a> Iterator for CreateIter<'a> type Item = Entity;
[src]Returns an iterator for entity creation. This makes it easy to create a whole collection of them. Read more
Deletes an entity and its components.
Deletes the specified entities and their components.
Deletes all entities and their components.
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. Read more
Merges in the appendix, recording all the dynamically created and deleted entities into the persistent generations vector. Also removes all the abandoned components. Read more
Fetches a component storage for reading. Read more
Fetches a component storage for writing. Read more
Auto Trait Implementations
impl !RefUnwindSafe for World
impl !UnwindSafe for World
Blanket Implementations
impl<T> Any for T where
T: Any,
impl<T> Any for T where
T: Any,
pub fn get_type_id(&self) -> TypeId
Mutably borrows from an owned value. Read more
Tries to create the default.
Calls try_default
and panics on an error case.