pub struct World { /* private fields */ }
Expand description
World
contains all data this library will manipulate.
Implementations
sourceimpl World
impl World
sourcepub fn add_unique<T>(&self, component: T) -> Result<(), Borrow> where
T: 'static + Send + Sync,
pub fn add_unique<T>(&self, component: T) -> Result<(), Borrow> where
T: 'static + Send + Sync,
Adds a new unique storage, unique storages store a single value.
To access a unique storage value, use UniqueView
or UniqueViewMut
.
Does nothing if the storage already exists.
Borrows
AllStorages
(shared)
Errors
AllStorages
borrow failed.
Example
use shipyard::{UniqueView, World};
let world = World::new();
world.add_unique(0u32).unwrap();
let i = world.borrow::<UniqueView<u32>>().unwrap();
assert_eq!(*i, 0);
sourcepub fn remove_unique<T>(&self) -> Result<T, UniqueRemove> where
T: 'static,
pub fn remove_unique<T>(&self) -> Result<T, UniqueRemove> where
T: 'static,
Removes a unique storage.
Borrows
AllStorages
(shared)Unique<T>
storage (exclusive)
Errors
AllStorages
borrow failed.Unique<T>
storage borrow failed.Unique<T>
storage did not exist.
Example
use shipyard::{UniqueView, World};
let world = World::new();
world.add_unique(0u32).unwrap();
let i = world.remove_unique::<u32>().unwrap();
assert_eq!(i, 0);
sourcepub fn borrow<'s, V>(&'s self) -> Result<V, GetStorage> where
V: IntoBorrow,
<V as IntoBorrow>::Borrow: Borrow<'s>,
<<V as IntoBorrow>::Borrow as Borrow<'s>>::View == V,
pub fn borrow<'s, V>(&'s self) -> Result<V, GetStorage> where
V: IntoBorrow,
<V as IntoBorrow>::Borrow: Borrow<'s>,
<<V as IntoBorrow>::Borrow as Borrow<'s>>::View == V,
Borrows the requested storages, if they don’t exist they’ll get created.
You can use a tuple to get multiple storages at once.
You can use:
- View<T> for a shared access to
T
storage - ViewMut<T> for an exclusive access to
T
storage - EntitiesView for a shared access to the entity storage
- EntitiesViewMut for an exclusive reference to the entity storage
- AllStoragesViewMut for an exclusive access to the storage of all components, ⚠️ can’t coexist with any other storage borrow
- UniqueView<T> for a shared access to a
T
unique storage - UniqueViewMut<T> for an exclusive access to a
T
unique storage Option<V>
with one or multiple views for fallible access to one or more storages- NonSend: must activate the thread_local feature
- NonSync: must activate the thread_local feature
- NonSendSync: must activate the thread_local feature
Borrows
- AllStorages (exclusive) when requesting AllStoragesViewMut
- AllStorages (shared) + storage (exclusive or shared) for all other views
Errors
- AllStorages borrow failed.
- Storage borrow failed.
- Unique storage did not exist.
Example
use shipyard::{EntitiesView, View, ViewMut, World};
let world = World::new();
let u32s = world.borrow::<View<u32>>().unwrap();
let (entities, mut usizes) = world
.borrow::<(EntitiesView, ViewMut<usize>)>()
.unwrap();
sourcepub fn run_with_data<'s, Data, B, R, S>(
&'s self,
s: S,
data: Data
) -> Result<R, Run> where
S: System<'s, (Data,), B, R>,
pub fn run_with_data<'s, Data, B, R, S>(
&'s self,
s: S,
data: Data
) -> Result<R, Run> where
S: System<'s, (Data,), B, R>,
Borrows the requested storages and runs the function.
Data can be passed to the function, this always has to be a single type but you can use a tuple if needed.
You can use:
- View<T> for a shared access to
T
storage - ViewMut<T> for an exclusive access to
T
storage - EntitiesView for a shared access to the entity storage
- EntitiesViewMut for an exclusive reference to the entity storage
- AllStoragesViewMut for an exclusive access to the storage of all components, ⚠️ can’t coexist with any other storage borrow
- UniqueView<T> for a shared access to a
T
unique storage - UniqueViewMut<T> for an exclusive access to a
T
unique storage Option<V>
with one or multiple views for fallible access to one or more storages- NonSend: must activate the thread_local feature
- NonSync: must activate the thread_local feature
- NonSendSync: must activate the thread_local feature
Borrows
- AllStorages (exclusive) when requesting AllStoragesViewMut
- AllStorages (shared) + storage (exclusive or shared) for all other views
Errors
- AllStorages borrow failed.
- Storage borrow failed.
- Unique storage did not exist.
- Error returned by user.
Example
use shipyard::{EntityId, Get, ViewMut, World};
fn sys1((entity, [x, y]): (EntityId, [f32; 2]), mut positions: ViewMut<[f32; 2]>) {
if let Ok(mut pos) = (&mut positions).get(entity) {
*pos = [x, y];
}
}
let world = World::new();
world.run_with_data(sys1, (EntityId::dead(), [0., 0.])).unwrap();
sourcepub fn run<'s, B, R, S>(&'s self, s: S) -> Result<R, Run> where
S: System<'s, (), B, R>,
pub fn run<'s, B, R, S>(&'s self, s: S) -> Result<R, Run> where
S: System<'s, (), B, R>,
Borrows the requested storages and runs the function.
You can use:
- View<T> for a shared access to
T
storage - ViewMut<T> for an exclusive access to
T
storage - EntitiesView for a shared access to the entity storage
- EntitiesViewMut for an exclusive reference to the entity storage
- AllStoragesViewMut for an exclusive access to the storage of all components, ⚠️ can’t coexist with any other storage borrow
- UniqueView<T> for a shared access to a
T
unique storage - UniqueViewMut<T> for an exclusive access to a
T
unique storage Option<V>
with one or multiple views for fallible access to one or more storages- NonSend: must activate the thread_local feature
- NonSync: must activate the thread_local feature
- NonSendSync: must activate the thread_local feature
Borrows
- AllStorages (exclusive) when requesting AllStoragesViewMut
- AllStorages (shared) + storage (exclusive or shared) for all other views
Errors
- AllStorages borrow failed.
- Storage borrow failed.
- Unique storage did not exist.
- Error returned by user.
Example
use shipyard::{View, ViewMut, World};
fn sys1(i32s: View<i32>) -> i32 {
0
}
let world = World::new();
world
.run(|usizes: View<usize>, mut u32s: ViewMut<u32>| {
// -- snip --
})
.unwrap();
let i = world.run(sys1).unwrap();
sourcepub fn set_default_workload(
&self,
name: impl Into<Cow<'static, str>>
) -> Result<(), SetDefaultWorkload>
pub fn set_default_workload(
&self,
name: impl Into<Cow<'static, str>>
) -> Result<(), SetDefaultWorkload>
sourcepub fn rename_workload(
&self,
old_name: impl Into<Cow<'static, str>>,
new_name: impl Into<Cow<'static, str>>
) -> Result<(), Borrow>
pub fn rename_workload(
&self,
old_name: impl Into<Cow<'static, str>>,
new_name: impl Into<Cow<'static, str>>
) -> Result<(), Borrow>
sourcepub fn run_workload(&self, name: impl AsRef<str>) -> Result<(), RunWorkload>
pub fn run_workload(&self, name: impl AsRef<str>) -> Result<(), RunWorkload>
sourcepub fn run_default(&self) -> Result<(), RunWorkload>
pub fn run_default(&self) -> Result<(), RunWorkload>
sourcepub fn all_storages(&self) -> Result<Ref<'_, &AllStorages>, Borrow>
pub fn all_storages(&self) -> Result<Ref<'_, &AllStorages>, Borrow>
Returns a Ref<&AllStorages>
, used to implement custom storages.
To borrow AllStorages
you should use borrow
or run
with AllStoragesViewMut
.
Errors
AllStorages
is already borrowed.
sourcepub fn all_storages_mut(&self) -> Result<RefMut<'_, &mut AllStorages>, Borrow>
pub fn all_storages_mut(&self) -> Result<RefMut<'_, &mut AllStorages>, Borrow>
Returns a RefMut<&mut AllStorages>
, used to implement custom storages.
To borrow AllStorages
you should use borrow
or run
with AllStoragesViewMut
.
Errors
AllStorages
is already borrowed.
sourceimpl World
impl World
sourcepub fn add_entity<C>(&mut self, component: C) -> EntityId where
C: AddComponent,
pub fn add_entity<C>(&mut self, component: C) -> EntityId where
C: AddComponent,
Creates a new entity with the components passed as argument and returns its EntityId
.
component
must always be a tuple, even for a single component.
Example
use shipyard::World;
let mut world = World::new();
let entity0 = world.add_entity((0u32,));
let entity1 = world.add_entity((1u32, 11usize));
sourcepub fn bulk_add_entity<T>(&mut self, source: T) -> BulkEntityIter<'_>ⓘNotable traits for BulkEntityIter<'a>impl<'a> Iterator for BulkEntityIter<'a> type Item = EntityId;
where
T: BulkAddEntity,
pub fn bulk_add_entity<T>(&mut self, source: T) -> BulkEntityIter<'_>ⓘNotable traits for BulkEntityIter<'a>impl<'a> Iterator for BulkEntityIter<'a> type Item = EntityId;
where
T: BulkAddEntity,
Creates multiple new entities and returns an iterator yielding the new EntityId
s.
source
must always yield a tuple, even for a single component.
Example
use shipyard::World;
let mut world = World::new();
let entity0 = world.bulk_add_entity((0..1).map(|_| {})).next();
let entity1 = world.bulk_add_entity((1..2).map(|i| (i as u32,))).next();
let new_entities = world.bulk_add_entity((10..20).map(|i| (i as u32, i)));
sourcepub fn add_component<C>(&mut self, entity: EntityId, component: C) where
C: AddComponent,
pub fn add_component<C>(&mut self, entity: EntityId, component: C) where
C: AddComponent,
Adds components to an existing entity.
If the entity already owned a component it will be replaced.
component
must always be a tuple, even for a single component.
Panics
entity
is not alive.
Example
use shipyard::World;
let mut world = World::new();
// make an empty entity
let entity = world.add_entity(());
world.add_component(entity, (0u32,));
// entity already had a `u32` component so it will be replaced
world.add_component(entity, (1u32, 11usize));
sourcepub fn remove<C>(&mut self, entity: EntityId) -> <C as Remove>::Out where
C: Remove,
pub fn remove<C>(&mut self, entity: EntityId) -> <C as Remove>::Out where
C: Remove,
Removes components from an entity.
C
must always be a tuple, even for a single component.
Example
use shipyard::World;
let mut world = World::new();
let entity = world.add_entity((0u32, 1usize));
let (i,) = world.remove::<(u32,)>(entity);
assert_eq!(i, Some(0));
sourcepub fn delete_component<C>(&mut self, entity: EntityId) where
C: DeleteComponent,
pub fn delete_component<C>(&mut self, entity: EntityId) where
C: DeleteComponent,
Deletes components from an entity. As opposed to remove
, delete
doesn’t return anything.
C
must always be a tuple, even for a single component.
Example
use shipyard::World;
let mut world = World::new();
let entity = world.add_entity((0u32, 1usize));
world.delete_component::<(u32,)>(entity);
sourcepub fn delete_entity(&mut self, entity: EntityId) -> bool
pub fn delete_entity(&mut self, entity: EntityId) -> bool
Deletes an entity with all its components. Returns true if the entity were alive.
Example
use shipyard::World;
let mut world = World::new();
let entity = world.add_entity((0u32, 1usize));
assert!(world.delete_entity(entity));
sourcepub fn strip(&mut self, entity: EntityId)
pub fn strip(&mut self, entity: EntityId)
Deletes all components of an entity without deleting the entity.
Example
use shipyard::World;
let mut world = World::new();
let entity = world.add_entity((0u32, 1usize));
world.strip(entity);
sourcepub fn delete_any<S>(&mut self) where
S: DeleteAny,
pub fn delete_any<S>(&mut self) where
S: DeleteAny,
Deletes all entities with any of the given components.
The storage’s type has to be used and not the component.
SparseSet
is the default storage.
Example
use shipyard::{SparseSet, World};
let mut world = World::new();
let entity0 = world.add_entity((0u32,));
let entity1 = world.add_entity((1usize,));
let entity2 = world.add_entity(("2",));
// deletes `entity2`
world.delete_any::<SparseSet<&str>>();
// deletes `entity0` and `entity1`
world.delete_any::<(SparseSet<u32>, SparseSet<usize>)>();
sourcepub fn retain<S>(&mut self, entity: EntityId) where
S: Retain,
pub fn retain<S>(&mut self, entity: EntityId) where
S: Retain,
Deletes all components of an entity except the ones passed in S
.
The storage’s type has to be used and not the component.
SparseSet
is the default storage.
Example
use shipyard::{SparseSet, World};
let mut world = World::new();
let entity = world.add_entity((0u32, 1usize));
world.retain::<SparseSet<u32>>(entity);
sourcepub fn retain_storage(
&mut self,
entity: EntityId,
excluded_storage: &[StorageId]
)
pub fn retain_storage(
&mut self,
entity: EntityId,
excluded_storage: &[StorageId]
)
Same as retain
but uses StorageId
and not generics.
You should only use this method if you use a custom storage with a runtime id.
sourcepub fn clear(&mut self)
pub fn clear(&mut self)
Deletes all entities and components in the World
.
Example
use shipyard::World;
let mut world = World::new();
world.clear();
sourcepub fn spawn(&mut self, entity: EntityId) -> bool
pub fn spawn(&mut self, entity: EntityId) -> bool
Make the given entity alive.
Does nothing if an entity with a greater generation is already at this index.
Returns true
if the entity is successfully spawned.
sourcepub fn memory_usage(&self) -> WorldMemoryUsage<'_>
pub fn memory_usage(&self) -> WorldMemoryUsage<'_>
Displays storages memory information.
Trait Implementations
Auto Trait Implementations
impl !RefUnwindSafe for World
impl Send for World
impl Sync for World
impl Unpin for World
impl !UnwindSafe for World
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
impl<T> Pointable for T
impl<T> Pointable for T
impl<SS, SP> SupersetOf<SS> for SP where
SS: SubsetOf<SP>,
impl<SS, SP> SupersetOf<SS> for SP where
SS: SubsetOf<SP>,
fn to_subset(&self) -> Option<SS>
fn to_subset(&self) -> Option<SS>
The inverse inclusion map: attempts to construct self
from the equivalent element of its
superset. Read more
fn is_in_subset(&self) -> bool
fn is_in_subset(&self) -> bool
Checks if self
is actually part of its subset T
(and can be converted to it).
fn to_subset_unchecked(&self) -> SS
fn to_subset_unchecked(&self) -> SS
Use with care! Same as self.to_subset
but without any property checks. Always succeeds.
fn from_subset(element: &SS) -> SP
fn from_subset(element: &SS) -> SP
The inclusion map: converts self
to the equivalent element of its superset.