Struct specs::World
[−]
[src]
pub struct World { pub res: Resources, // some fields omitted }
The World
struct contains the component storages and
other 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.
Component / Resources ids
Components and resources may, in addition to their type, be identified
by an id of type usize
. The convenience methods dealing
with components assume that it's 0
.
If a system attempts to access a component/resource that has not been
registered/added, it will panic when run. Add all components with
World::register
before running any systems. Also add all resources
with World::add_resource
.
Examples
use specs::World; let mut world = World::new(); world.register::<Pos>(); world.register::<Vel>(); world.add_resource(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` returns a component storage. let pos_storage = world.read::<Pos>(); let vel_storage = world.read::<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::<Pos>(); let vel_storage = world.read::<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()); }
Fields
res: Resources
The resources used for this world.
Methods
impl World
[src]
pub fn new() -> World
[src]
Creates a new empty World
.
pub fn register<T: Component>(&mut self)
[src]
Registers a new component.
Calls register_with_id
with id 0
, which
is the default for component ids.
Does nothing if the component was already registered.
Examples
use specs::{Component, DenseVecStorage, World}; 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
pub fn register_with_id<T: Component>(&mut self, id: usize)
[src]
Registers a new component with a given id.
Does nothing if the component was already registered.
pub fn add_resource<T: Resource>(&mut self, res: T)
[src]
Adds a resource with the default ID (0
).
If the resource already exists it will be overwritten.
Difference between resources and components
While components exist per entity, resources are like globals in the World
.
Components are stored in component storages, which are resources themselves.
Everything that is Any + Send + Sync
can be a resource.
Built-in resources
There are two built-in resources:
LazyUpdate
andEntitiesRes
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::World; let mut world = World::new(); world.add_resource(timer); world.add_resource(server_con);
pub fn add_resource_with_id<T: Resource>(&mut self, res: T, id: usize)
[src]
Adds a resource with a given ID.
If the resource already exists it will be overwritten.
pub fn read<T: Component>(&self) -> ReadStorage<T>
[src]
Fetches a component's storage with the default id for reading.
Convenience method for read_with_id
, using the default component
id (0
).
Panics
Panics if it is already borrowed mutably. Panics if the component has not been registered.
pub fn write<T: Component>(&self) -> WriteStorage<T>
[src]
Fetches a component's storage with the default id for writing.
Convenience method for write_with_id
, using the default component
id (0
).
Panics
Panics if it is already borrowed. Panics if the component has not been registered.
pub fn read_with_id<T: Component>(&self, id: usize) -> ReadStorage<T>
[src]
Fetches a component's storage with a specified component id for reading. ID is for components registered with an ID, and does not correspond to entity IDs. For basic setups, use an ID of 0 or use the read() function.
Panics
Panics if it is already borrowed mutably.
Also panics if the component is not registered with World::register
.
pub fn write_with_id<T: Component>(&self, id: usize) -> WriteStorage<T>
[src]
Fetches a component's storage with a specified id for writing. ID is for components registered with an ID, and does not correspond to entity IDs. For basic setups, use an ID of 0 or use the write() function.
Panics
Panics if it is already borrowed.
Also panics if the component is not registered with World::register
.
pub fn read_resource_with_id<T: Resource>(&self, id: usize) -> Fetch<T>
[src]
Fetches a resource with a specified id for reading. ID is for resources registered with an ID, and does not correspond to entity IDs. For basic setups, use an ID of 0 or use the read_resource() function.
Panics
Panics if it is already borrowed mutably. Panics if the resource has not been added.
pub fn write_resource_with_id<T: Resource>(&self, id: usize) -> FetchMut<T>
[src]
Fetches a resource with a specified id for writing. ID is for resources registered with an ID, and does not correspond to entity IDs. For basic setups, use an ID of 0 or use the write_resource() function.
Panics
Panics if it is already borrowed. Panics if the resource has not been added.
pub fn read_resource<T: Resource>(&self) -> Fetch<T>
[src]
Fetches a resource with the default id for reading.
Convenience method for read_resource_with_id
, using the default component
id (0
).
Panics
Panics if it is already borrowed mutably. Panics if the resource has not been added.
pub fn write_resource<T: Resource>(&self) -> FetchMut<T>
[src]
Fetches a resource with the default id for writing.
Convenience method for write_resource_with_id
, using the default component
id (0
).
Panics
Panics if it is already borrowed. Panics if the resource has not been added.
pub fn entities(&self) -> Fetch<EntitiesRes>
[src]
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()
.
pub fn create_entity(&mut self) -> EntityBuilder
[src]
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
.
pub fn create_entity_unchecked(&self) -> EntityBuilder
[src]
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
.
pub fn create_iter(&mut self) -> CreateIter
[src]
Returns an iterator for entity creation. This makes it easy to create a whole collection of them.
Examples
use specs::World; let mut world = World::new(); let five_entities: Vec<_> = world.create_iter().take(5).collect();
pub fn delete_entity(&mut self, entity: Entity) -> Result<(), WrongGeneration>
[src]
Deletes an entity and its components.
pub fn delete_entities(
&mut self,
delete: &[Entity]
) -> Result<(), WrongGeneration>
[src]
&mut self,
delete: &[Entity]
) -> Result<(), WrongGeneration>
Deletes the specified entities and their components.
pub fn delete_all(&mut self)
[src]
Deletes all entities and their components.
pub fn is_alive(&self, e: Entity) -> bool
[src]
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.
pub fn maintain(&mut self)
[src]
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.
pub fn add_bundle<B>(&mut self, bundle: B) where
B: Bundle,
[src]
B: Bundle,
Adds the given bundle of resources/components.
Trait Implementations
impl Send for World
[src]
impl Sync for World
[src]
impl Borrow<Resources> for World
[src]
impl Component for World
[src]
type Storage = DenseVecStorage<Self>
Associated storage type for this component.