Struct shipyard::World[−][src]

pub struct World { /* fields omitted */ }

World contains all data this library will manipulate.

Implementations

impl World[src]

pub fn new() -> Self[src]

Creates an empty World.

pub fn add_unique<T: 'static + Send + Sync>(
    &self,
    component: T
) -> Result<(), Borrow>[src]

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

Errors

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);

pub fn add_unique_non_send<T: 'static + Sync>(
    &self,
    component: T
) -> Result<(), Borrow>[src]

This is supported on crate feature thread_local only.

Adds a new unique storage, unique storages store a single value.
To access a !Send unique storage value, use NonSend with UniqueView or UniqueViewMut.
Does nothing if the storage already exists.

Borrows

Errors

Example

use shipyard::{NonSend, UniqueView, World};

let world = World::new();

// I'm using `u32` here but imagine it's a `!Send` type
world.add_unique_non_send(0u32).unwrap();

let i = world.borrow::<NonSend<UniqueView<u32>>>().unwrap();
assert_eq!(**i, 0);

pub fn add_unique_non_sync<T: 'static + Send>(
    &self,
    component: T
) -> Result<(), Borrow>[src]

This is supported on crate feature thread_local only.

Adds a new unique storage, unique storages store a single value.
To access a !Sync unique storage value, use NonSync with UniqueView or UniqueViewMut.
Does nothing if the storage already exists.

Borrows

Errors

Example

use shipyard::{NonSync, UniqueView, World};

let world = World::new();

// I'm using `u32` here but imagine it's a `!Sync` type
world.add_unique_non_sync(0u32).unwrap();

let i = world.borrow::<NonSync<UniqueView<u32>>>().unwrap();
assert_eq!(**i, 0);

pub fn add_unique_non_send_sync<T: 'static>(
    &self,
    component: T
) -> Result<(), Borrow>[src]

This is supported on crate feature thread_local only.

Adds a new unique storage, unique storages store a single value.
To access a !Send + !Sync unique storage value, use NonSendSync with UniqueView or UniqueViewMut.
Does nothing if the storage already exists.

Borrows

Errors

Example

use shipyard::{NonSendSync, UniqueView, World};

let world = World::new();

// I'm using `u32` here but imagine it's a `!Send + !Sync` type
world.add_unique_non_send_sync(0u32).unwrap();

let i = world.borrow::<NonSendSync<UniqueView<u32>>>().unwrap();
assert_eq!(**i, 0);

pub fn remove_unique<T: 'static>(&self) -> Result<T, UniqueRemove>[src]

Removes a unique storage.

Borrows

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);

pub fn borrow<'s, V: IntoBorrow>(&'s self) -> Result<V, GetStorage> where
    V::Borrow: Borrow<'s, View = V>, [src]

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
  • This is supported on feature=“thread_local” only:

Borrows

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();

pub fn run_with_data<'s, Data, B, R, S: System<'s, (Data,), B, R>>(
    &'s self,
    s: S,
    data: Data
) -> Result<R, Run>[src]

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
  • This is supported on feature=“thread_local” only:

Borrows

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();

pub fn run<'s, B, R, S: System<'s, (), B, R>>(&'s self, s: S) -> Result<R, Run>[src]

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
  • This is supported on feature=“thread_local” only:

Borrows

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();

pub fn set_default_workload(
    &self,
    name: impl Into<Cow<'static, str>>
) -> Result<(), SetDefaultWorkload>[src]

Modifies the current default workload to name.

Borrows

  • Scheduler (exclusive)

Errors

  • Scheduler borrow failed.
  • Workload did not exist.

pub fn rename_workload(
    &self,
    old_name: impl Into<Cow<'static, str>>,
    new_name: impl Into<Cow<'static, str>>
) -> Result<(), Borrow>[src]

Changes the name of a workload if it exists.

Borrows

  • Scheduler (exclusive)

Errors

  • Scheduler borrow failed.

pub fn run_workload(&self, name: impl AsRef<str>) -> Result<(), RunWorkload>[src]

Runs the name workload.

Borrows

  • Scheduler (shared)
  • Systems’ borrow as they are executed

Errors

  • Scheduler borrow failed.
  • Workload did not exist.
  • Storage borrow failed.
  • User error returned by system.

pub fn run_default(&self) -> Result<(), RunWorkload>[src]

Run the default workload if there is one.

Borrows

  • Scheduler (shared)
  • Systems’ borrow as they are executed

Errors

  • Scheduler borrow failed.
  • Storage borrow failed.
  • User error returned by system.

pub fn all_storages(&self) -> Result<Ref<'_, &AllStorages>, Borrow>[src]

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.

pub fn all_storages_mut(&self) -> Result<RefMut<'_, &mut AllStorages>, Borrow>[src]

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.

pub fn add_custom_storage<S: 'static + Storage + Send + Sync>(
    &self,
    storage_id: StorageId,
    storage: S
) -> Result<(), Borrow>[src]

Inserts a custom storage to the World.

Errors

  • AllStorages is already borrowed exclusively.

impl World[src]

pub fn add_entity<C: AddComponent>(&mut self, component: C) -> EntityId[src]

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));

pub fn bulk_add_entity<T: BulkAddEntity>(
    &mut self,
    source: T
) -> BulkEntityIter<'_>ⓘ

Notable traits for BulkEntityIter<'a>

impl<'a> Iterator for BulkEntityIter<'a> type Item = EntityId;
[src]

Creates multiple new entities and returns an iterator yielding the new EntityIds.
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)));

pub fn add_component<C: AddComponent>(&mut self, entity: EntityId, component: C)[src]

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));

pub fn remove<C: Remove>(&mut self, entity: EntityId) -> C::Out[src]

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));

pub fn delete_component<C: DeleteComponent>(&mut self, entity: EntityId)[src]

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);

pub fn delete_entity(&mut self, entity: EntityId) -> bool[src]

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));

pub fn strip(&mut self, entity: EntityId)[src]

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);

pub fn delete_any<S: DeleteAny>(&mut self)[src]

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>)>();

pub fn retain<S: Retain>(&mut self, entity: EntityId)[src]

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);

pub fn retain_storage(
    &mut self,
    entity: EntityId,
    excluded_storage: &[StorageId]
)[src]

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.

pub fn clear(&mut self)[src]

Deletes all entities and components in the World.

Example

use shipyard::World;

let mut world = World::new();

world.clear();

pub fn spawn(&mut self, entity: EntityId) -> bool[src]

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.

pub fn memory_usage(&self) -> WorldMemoryUsage<'_>[src]

Displays storages memory information.

Trait Implementations

impl Debug for World[src]

impl Default for World[src]

fn default() -> Self[src]

Creates an empty World.

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

impl<T> Any for T where
    T: 'static + ?Sized, [src]

impl<T> Borrow<T> for T where
    T: ?Sized, [src]

impl<T> BorrowMut<T> for T where
    T: ?Sized, [src]

impl<T> From<T> for T[src]

impl<T, U> Into<U> for T where
    U: From<T>, [src]

impl<T> Pointable for T

type Init = T

The type for initializers.

impl<T, U> TryFrom<U> for T where
    U: Into<T>, [src]

type Error = Infallible

The type returned in the event of a conversion error.

impl<T, U> TryInto<U> for T where
    U: TryFrom<T>, [src]

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.