Struct World 

pub struct World { /* private fields */ }

World contains all data this library will manipulate.

Implementations

impl World

pub fn add_workload<Views, R, W, F: FnOnce() -> W + 'static>(&self, workload: F)

where W: IntoWorkload<Views, R>,

Creates a new workload and store it in the World.

impl World

pub fn builder() -> WorldBuilder<LockPresent, ThreadIdPresent>

Available on crate feature std only.

Returns a builder for World when one wants custom lock, custom thread pool or custom thread id provider function.

impl World

pub fn new() -> World

Available on crate feature std only.

Creates an empty World.

pub fn remove_local_thread_pool(&mut self) -> Option<ThreadPool>

Available on crate feature parallel only.

Removes the local ThreadPool.

pub fn add_unique<T: Send + Sync + Unique>(&self, component: T)

Adds a new unique storage, unique storages store a single value. To access a unique storage value, use UniqueView or UniqueViewMut.

Borrows

• AllStorages (shared)

Panics

• AllStorages borrow failed.

Example

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

#[derive(Unique)]
struct U32(u32);

let world = World::new();

world.add_unique(U32(0));

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

pub fn add_unique_non_send<T: Sync + Unique>(&self, component: T)

Available 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

• AllStorages (shared)

Panics

• AllStorages borrow failed.

Example

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

#[derive(Unique)]
struct U32(u32);

let world = World::new();

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

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

pub fn add_unique_non_sync<T: Send + Unique>(&self, component: T)

Available 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

• AllStorages (shared)

Panics

• AllStorages borrow failed.

Example

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

#[derive(Unique)]
struct U32(u32);

let world = World::new();

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

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

pub fn add_unique_non_send_sync<T: Unique>(&self, component: T)

Available 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

• AllStorages (shared)

Panics

• AllStorages borrow failed.

Example

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

let world = World::new();

#[derive(Unique)]
struct U32(u32);

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

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

pub fn remove_unique<T: Unique>(&self) -> Result<T, UniqueRemove>

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::{Unique, UniqueView, World};

#[derive(Unique, Debug)]
struct U32(u32);

let world = World::new();

world.add_unique(U32(0));

let i = world.remove_unique::<U32>().unwrap();
assert_eq!(i.0, 0);

pub fn borrow<V: WorldBorrow>(&self) -> Result<V::WorldView<'_>, GetStorage>

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:
  • NonSend<View<T>> for a shared access to a T storage where T isn’t Send
  • NonSend<ViewMut<T>> for an exclusive access to a T storage where T isn’t Send NonSend and UniqueView/UniqueViewMut can be used together to access a !Send unique storage.
  • NonSync<View<T>> for a shared access to a T storage where T isn’t Sync
  • NonSync<ViewMut<T>> for an exclusive access to a T storage where T isn’t Sync NonSync and UniqueView/UniqueViewMut can be used together to access a !Sync unique storage.
  • NonSendSync<View<T>> for a shared access to a T storage where T isn’t Send nor Sync
  • NonSendSync<ViewMut<T>> for an exclusive access to a T storage where T isn’t Send nor Sync NonSendSync and UniqueView/UniqueViewMut can be used together to access a !Send + !Sync unique storage.

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::{Component, EntitiesView, View, ViewMut, World};

#[derive(Component)]
struct U32(u32);

#[derive(Component)]
struct USIZE(usize);

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<Data, B, S: System<(Data,), B>>( &self, system: S, data: Data, ) -> S::Return

Borrows the requested storages, runs the function and evaluates to the function’s return value. 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:
  • NonSend<View<T>> for a shared access to a T storage where T isn’t Send
  • NonSend<ViewMut<T>> for an exclusive access to a T storage where T isn’t Send NonSend and UniqueView/UniqueViewMut can be used together to access a !Send unique storage.
  • NonSync<View<T>> for a shared access to a T storage where T isn’t Sync
  • NonSync<ViewMut<T>> for an exclusive access to a T storage where T isn’t Sync NonSync and UniqueView/UniqueViewMut can be used together to access a !Sync unique storage.
  • NonSendSync<View<T>> for a shared access to a T storage where T isn’t Send nor Sync
  • NonSendSync<ViewMut<T>> for an exclusive access to a T storage where T isn’t Send nor Sync NonSendSync and UniqueView/UniqueViewMut can be used together to access a !Send + !Sync unique storage.

Borrows

• AllStorages (exclusive) when requesting AllStoragesViewMut
• AllStorages (shared) + storage (exclusive or shared) for all other views

Panics

• AllStorages borrow failed.
• Storage borrow failed.
• Unique storage did not exist.
• Error returned by user.

Example

use shipyard::{Component, EntityId, Get, ViewMut, World};

#[derive(Component)]
struct Position([f32; 2]);

fn sys1((entity, [x, y]): (EntityId, [f32; 2]), mut positions: ViewMut<Position>) {
    if let Ok(mut pos) = (&mut positions).get(entity) {
        pos.0 = [x, y];
    }
}

let world = World::new();

world.run_with_data(sys1, (EntityId::dead(), [0., 0.]));

pub fn run<B, S: System<(), B>>(&self, system: S) -> S::Return

Borrows the requested storages, runs the function and evaluates to the function’s return value.

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:
  • NonSend<View<T>> for a shared access to a T storage where T isn’t Send
  • NonSend<ViewMut<T>> for an exclusive access to a T storage where T isn’t Send NonSend and UniqueView/UniqueViewMut can be used together to access a !Send unique storage.
  • NonSync<View<T>> for a shared access to a T storage where T isn’t Sync
  • NonSync<ViewMut<T>> for an exclusive access to a T storage where T isn’t Sync NonSync and UniqueView/UniqueViewMut can be used together to access a !Sync unique storage.
  • NonSendSync<View<T>> for a shared access to a T storage where T isn’t Send nor Sync
  • NonSendSync<ViewMut<T>> for an exclusive access to a T storage where T isn’t Send nor Sync NonSendSync and UniqueView/UniqueViewMut can be used together to access a !Send + !Sync unique storage.

Borrows

• AllStorages (exclusive) when requesting AllStoragesViewMut
• AllStorages (shared) + storage (exclusive or shared) for all other views

Panics

• AllStorages borrow failed.
• Storage borrow failed.
• Unique storage did not exist.
• Error returned by user.

Example

use shipyard::{Component, View, ViewMut, World};

#[derive(Component)]
struct I32(i32);

#[derive(Component)]
struct USIZE(usize);

#[derive(Component)]
struct U32(u32);

fn sys1(i32s: View<I32>) -> i32 {
    0
}

let world = World::new();

world
    .run(|usizes: View<USIZE>, mut u32s: ViewMut<U32>| {
        // -- snip --
    });

let i = world.run(sys1);

pub fn set_default_workload<T>( &self, name: impl AsLabel<T>, ) -> Result<(), SetDefaultWorkload>

Modifies the current default workload to name.

Borrows

• Scheduler (exclusive)

Errors

• Scheduler borrow failed.
• Workload did not exist.

pub fn rename_workload<T, U>( &self, old_name: impl AsLabel<T>, new_name: impl AsLabel<U>, )

Changes the name of a workload if it exists.

Borrows

• Scheduler (exclusive)

Panics

• Scheduler borrow failed.

pub fn run_workload<T>(&self, label: impl AsLabel<T>) -> Result<(), RunWorkload>

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 contains_workload<T>(&self, name: impl AsLabel<T>) -> bool

Returns true if the world contains the name workload.

Borrows

• Scheduler (shared)

Panics

• Scheduler borrow failed.

Example

use shipyard::{Workload, World};

let world = World::new();

Workload::new("foo").add_to_world(&world).unwrap();

assert!(world.contains_workload("foo"));
assert!(!world.contains_workload("bar"));

pub fn run_default_workload(&self) -> Result<(), RunWorkload>

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<ARef<'_, &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.

pub fn all_storages_mut(&self) -> Result<ARefMut<'_, &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.

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

Inserts a custom storage to the World.

Errors

• AllStorages is already borrowed exclusively.

pub fn get_tracking_timestamp(&self) -> TrackingTimestamp

Returns a timestamp used to clear tracking information.

impl World

pub fn add_entity<C: TupleAddComponent>(&mut self, component: C) -> EntityId

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::{Component, World};

#[derive(Component)]
struct U32(u32);

#[derive(Component)]
struct USIZE(usize);

let mut world = World::new();

let entity0 = world.add_entity((U32(0),));
let entity1 = world.add_entity((U32(1), USIZE(11)));

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

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::{Component, World};

#[derive(Component)]
struct U32(u32);

#[derive(Component)]
struct USIZE(usize);

let mut world = World::new();

let new_entities = world.bulk_add_entity((10..20).map(|i| (U32(i as u32), USIZE(i))));

pub fn add_component<C: TupleAddComponent>( &mut self, entity: EntityId, component: C, )

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::{Component, World};

#[derive(Component)]
struct U32(u32);

#[derive(Component)]
struct USIZE(usize);

let mut world = World::new();

// make an empty entity
let entity = world.add_entity(());

world.add_component(entity, (U32(0),));
// entity already had a `U32` component so it will be replaced
world.add_component(entity, (U32(1), USIZE(11)));

pub fn delete_component<C: TupleDelete>(&mut self, entity: EntityId)

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::{Component, World};

#[derive(Component, Debug, PartialEq, Eq)]
struct U32(u32);

#[derive(Component)]
struct USIZE(usize);

let mut world = World::new();

let entity = world.add_entity((U32(0), USIZE(1)));

world.delete_component::<(U32,)>(entity);

pub fn remove<C: TupleRemove>(&mut self, entity: EntityId) -> C::Out

Removes components from an entity. C must always be a tuple, even for a single component.

Example

use shipyard::{Component, World};

#[derive(Component, Debug, PartialEq, Eq)]
struct U32(u32);

#[derive(Component)]
struct USIZE(usize);

let mut world = World::new();

let entity = world.add_entity((U32(0), USIZE(1)));

let (i,) = world.remove::<(U32,)>(entity);
assert_eq!(i, Some(U32(0)));

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::{Component, World};

#[derive(Component)]
struct U32(u32);

#[derive(Component)]
struct USIZE(usize);

let mut world = World::new();

let entity = world.add_entity((U32(0), USIZE(1)));

assert!(world.delete_entity(entity));

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

Deletes all components of an entity without deleting the entity.

Example

use shipyard::{Component, World};

#[derive(Component)]
struct U32(u32);

#[derive(Component)]
struct USIZE(usize);

let mut world = World::new();

let entity = world.add_entity((U32(0), USIZE(1)));

world.strip(entity);

pub fn bulk_strip<I: IntoIterator<Item = EntityId>>(&mut self, entities: I)

where I::IntoIter: Clone,

Deletes all components of multiple entities without deleting them.

Example

use shipyard::{Component, View, World};

#[derive(Component)]
struct U32(u32);

#[derive(Component)]
struct USIZE(usize);

let mut world = World::new();

let eid0 = world.add_entity((U32(0), USIZE(1)));
let eid1 = world.add_entity(USIZE(10));
let eid2 = world.add_entity(U32(30));

world.bulk_strip([eid0, eid1, eid2]);

let (v_u32, v_usize) = world.borrow::<(View<U32>, View<USIZE>)>().unwrap();
assert_eq!(v_u32.len(), 0);
assert_eq!(v_usize.len(), 0);

pub fn delete_any<S: TupleDeleteAny>(&mut self)

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::{Component, sparse_set::SparseSet, World};

#[derive(Component)]
struct U32(u32);

#[derive(Component)]
struct USIZE(usize);

#[derive(Component)]
struct STR(&'static str);

let mut world = World::new();

let entity0 = world.add_entity((U32(0),));
let entity1 = world.add_entity((USIZE(1),));
let entity2 = world.add_entity((STR("2"),));

// deletes `entity2`
world.delete_any::<SparseSet<STR>>();
// deletes `entity0` and `entity1`
world.delete_any::<(SparseSet<U32>, SparseSet<USIZE>)>();

pub fn retain_storage<S: TupleRetainStorage>(&mut self, entity: EntityId)

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::{Component, sparse_set::SparseSet, World};

#[derive(Component)]
struct U32(u32);

#[derive(Component)]
struct USIZE(usize);

let mut world = World::new();

let entity = world.add_entity((U32(0), USIZE(1)));

world.retain_storage::<SparseSet<U32>>(entity);

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

Same as retain_storage 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)

Deletes all entities and components in the World.

Example

use shipyard::World;

let mut world = World::new();

world.clear();

pub fn clear_all_removed_and_deleted(&mut self)

Clear all deletion and removal tracking data.

pub fn clear_all_removed_and_deleted_older_than_timestamp( &mut self, timestamp: TrackingTimestamp, )

Clear all deletion and removal tracking data older than some timestamp.

pub fn clear_all_inserted(&mut self)

Clear all insertion tracking data.

pub fn clear_all_modified(&mut self)

Clear all modification tracking data.

pub fn clear_all_inserted_and_modified(&mut self)

Clear all insertion and modification tracking data.

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.

pub fn retain<T: Component + Send + Sync>( &mut self, f: impl FnMut(EntityId, &T) -> bool, )

Deletes all components for which f(id, &component) returns false.

Panics

• Storage borrow failed.

pub fn retain_mut<T: Component + Send + Sync>( &mut self, f: impl FnMut(EntityId, Mut<'_, T>) -> bool, )

Deletes all components for which f(id, Mut<component>) returns false.

Panics

• Storage borrow failed.

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

Displays storages memory information.

pub fn workloads_info(&self) -> WorkloadsInfo

Returns a list of workloads and all information related to them.

Borrows

• Scheduler (shared)

Panics

• Scheduler borrow failed.

pub fn track_insertion<T: TupleTrack>(&mut self) -> &mut World

Enable insertion tracking for the given components.

pub fn track_modification<T: TupleTrack>(&mut self) -> &mut World

Enable modification tracking for the given components.

pub fn track_deletion<T: TupleTrack>(&mut self) -> &mut World

Enable deletion tracking for the given components.

pub fn track_removal<T: TupleTrack>(&mut self) -> &mut World

Enable removal tracking for the given components.

pub fn track_all<T: TupleTrack>(&mut self)

Enable insertion, deletion and removal tracking for the given components.

pub fn get<T: GetComponent>( &self, entity: EntityId, ) -> Result<T::Out<'_>, GetComponent>

Retrieve components of entity.

Multiple components can be queried at the same time using a tuple.

You can use:

• &T for a shared access to T component
• &mut T for an exclusive access to T component
• This is supported on feature=“thread_local” only:
• NonSend<&T> for a shared access to a T component where T isn’t Send
• NonSend<&mut T> for an exclusive access to a T component where T isn’t Send
• NonSync<&T> for a shared access to a T component where T isn’t Sync
• NonSync<&mut T> for an exclusive access to a T component where T isn’t Sync
• NonSendSync<&T> for a shared access to a T component where T isn’t Send nor Sync
• NonSendSync<&mut T> for an exclusive access to a T component where T isn’t Send nor Sync

Borrows

• AllStorages (shared) + storage (exclusive or shared)

Errors

• AllStorages borrow failed.
• Storage borrow failed.
• Entity does not have the component.

Example

use shipyard::{Component, World};

#[derive(Component, Debug, PartialEq, Eq)]
struct U32(u32);

#[derive(Component, Debug, PartialEq, Eq)]
struct USIZE(usize);

let mut world = World::new();

let entity = world.add_entity((USIZE(0), U32(1)));

let (i, j) = world.get::<(&USIZE, &mut U32)>(entity).unwrap();

assert!(*i == &USIZE(0));
assert!(*j == &U32(1));

pub fn get_unique<T: GetUnique>(&self) -> Result<T::Out<'_>, GetStorage>

Retrieve a unique component.

You can use:

• &T for a shared access to T unique component
• &mut T for an exclusive access to T unique component
• This is supported on feature=“thread_local” only:
• NonSend<&T> for a shared access to a T unique component where T isn’t Send
• NonSend<&mut T> for an exclusive access to a T unique component where T isn’t Send
• NonSync<&T> for a shared access to a T unique component where T isn’t Sync
• NonSync<&mut T> for an exclusive access to a T unique component where T isn’t Sync
• NonSendSync<&T> for a shared access to a T unique component where T isn’t Send nor Sync
• NonSendSync<&mut T> for an exclusive access to a T unique component where T isn’t Send nor Sync

Borrows

• AllStorages (shared) + storage (exclusive or shared)

Errors

• AllStorages borrow failed.
• Storage borrow failed.

Example

use shipyard::{Unique, World};

#[derive(Unique, Debug, PartialEq, Eq)]
struct U32(u32);

let mut world = World::new();

world.add_unique(U32(0));

let i = world.get_unique::<&U32>().unwrap();

assert!(*i == U32(0));

pub fn iter<'a, T: IterComponent>(&'a self) -> IntoIterRef<'a, T>

where <T as IterComponent>::Shiperator<'a>: ShiperatorCaptain + ShiperatorSailor,

Iterate components.

Multiple components can be iterated at the same time using a tuple.

You can use:

• &T for a shared access to T component
• &mut T for an exclusive access to T component
• This is supported on feature=“thread_local” only:
• NonSend<&T> for a shared access to a T component where T isn’t Send
• NonSend<&mut T> for an exclusive access to a T component where T isn’t Send
• NonSync<&T> for a shared access to a T component where T isn’t Sync
• NonSync<&mut T> for an exclusive access to a T component where T isn’t Sync
• NonSendSync<&T> for a shared access to a T component where T isn’t Send nor Sync
• NonSendSync<&mut T> for an exclusive access to a T component where T isn’t Send nor Sync

Borrows

• AllStorages (shared)

Panics

• AllStorages borrow failed.

Example

use shipyard::{Component, World};

#[derive(Component, Debug, PartialEq, Eq)]
struct U32(u32);

#[derive(Component, Debug, PartialEq, Eq)]
struct USIZE(usize);

let mut world = World::new();

let entity = world.add_entity((USIZE(0), U32(1)));

let mut iter = world.iter::<(&USIZE, &mut U32)>();

for (i, j) in &mut iter {
    // <-- SNIP -->
}

pub fn on_deletion(&self, f: impl FnMut(EntityId) + Send + Sync + 'static)

Sets the on entity deletion callback.

Borrows

• AllStorages (shared)
• Entities (exclusive)

Panics

• AllStorages borrow failed.
• Entities borrow failed.

pub fn is_entity_alive(&mut self, entity: EntityId) -> bool

Returns true if entity matches a living entity.

pub fn move_entity(&mut self, other: &mut World, entity: EntityId)

Moves an entity from a World to another.

Panics

• entity is not alive

Example

use shipyard::{Component, World};

#[derive(Component, Debug, PartialEq, Eq)]
struct USIZE(usize);

let mut world1 = World::new();
let mut world2 = World::new();

let entity = world1.add_entity(USIZE(1));

world1.move_entity(&mut world2, entity);

assert!(!world1.is_entity_alive(entity));
assert_eq!(world2.get::<&USIZE>(entity).as_deref(), Ok(&&USIZE(1)));

pub fn move_components( &mut self, other: &mut World, from: EntityId, to: EntityId, )

Moves all components from an entity to another in another World.

Panics

• from is not alive
• to is not alive

Example

use shipyard::{Component, World};

#[derive(Component, Debug, PartialEq, Eq)]
struct USIZE(usize);

let mut world1 = World::new();
let mut world2 = World::new();

let from = world1.add_entity(USIZE(1));
let to = world2.add_entity(());

world1.move_components(&mut world2, from, to);

assert!(world1.get::<&USIZE>(from).is_err());
assert_eq!(world2.get::<&USIZE>(to).as_deref(), Ok(&&USIZE(1)));

pub fn register_clone<T: TupleClone>(&mut self)

Registers the function to clone these components.

The type of the storage is used and not the component itself.
That would be SparseSet<T> and UniqueStorage<T>.

Example

use shipyard::{Component, sparse_set::SparseSet, Unique, UniqueStorage, World};

#[derive(Component, Clone)]
struct USIZE(usize);

#[derive(Unique, Clone)]
struct U32(u32);

let mut world = World::new();

world.add_unique(U32(0));

world.register_clone::<(SparseSet<USIZE>, UniqueStorage<U32>)>();

pub fn clone_entity_to(&self, other: &mut World, entity: EntityId)

Clones entity from this World to other alongside all its with a registered clone function.

Borrows

• AllStorages (shared)
• Every Storage (shared)

Panics

• entity is not alive

Example

use shipyard::{Component, sparse_set::SparseSet, World};

#[derive(Component, Clone, Debug, PartialEq, Eq)]
struct USIZE(usize);

let mut world1 = World::new();
let mut world2 = World::new();

world1.register_clone::<SparseSet<USIZE>>();

let entity = world1.add_entity(USIZE(1));

world1.clone_entity_to(&mut world2, entity);

assert_eq!(world1.get::<&USIZE>(entity).as_deref(), Ok(&&USIZE(1)));
assert_eq!(world2.get::<&USIZE>(entity).as_deref(), Ok(&&USIZE(1)));

pub fn clone_components_to( &self, other: &mut World, from: EntityId, to: EntityId, )

Clones all components of from entity with a registered clone function from this World to other’s to entity.

Borrows

• AllStorages (shared)
• Every Storage (shared)

Panics

• from is not alive
• to is not alive

Example

use shipyard::{Component, sparse_set::SparseSet, World};

#[derive(Component, Clone, Debug, PartialEq, Eq)]
struct USIZE(usize);

let mut world1 = World::new();
let mut world2 = World::new();

world1.register_clone::<SparseSet<USIZE>>();

let from = world1.add_entity(USIZE(1));
let to = world2.add_entity(());

world1.clone_components_to(&mut world2, from, to);

assert_eq!(world1.get::<&USIZE>(from).as_deref(), Ok(&&USIZE(1)));
assert_eq!(world2.get::<&USIZE>(to).as_deref(), Ok(&&USIZE(1)));

impl World

pub fn serialize<'w, S: Serializer, V: WorldBorrow>( &'w self, serializer: S, ) -> Result<S::Ok, Serialize<S>>

where V::WorldView<'w>: Serialize,

Available on crate feature serde1 only.

Serializes the view using the provided serializer.

Example

use shipyard::{Component, View, World};

#[derive(Component, serde::Serialize)]
struct Name(String);

let mut world = World::new();

let eid1 = world.add_entity(Name("Alice".to_string()));

let mut serialized = Vec::new();
world
    .serialize::<_, View<Name>>(&mut serde_json::ser::Serializer::new(&mut serialized))
    .unwrap_or_else(|_| panic!());

let serialized_str = String::from_utf8(serialized).unwrap();
assert_eq!(serialized_str, r#"[[{"index":0,"gen":0},"Alice"]]"#);

pub fn deserialize<'w, 'de, D: Deserializer<'de>, V: WorldBorrow>( &'w self, deserializer: D, ) -> Result<(), Deserialize<'de, D>>

where V::WorldView<'w>: Deserialize<'de>,

Available on crate feature serde1 only.

Deserializes the view using the provided deserializer.

Example

use shipyard::{Component, EntityId, ViewMut, World};

#[derive(Component, serde::Deserialize)]
struct Name(String);

let mut world = World::new();

let mut serialized = r#"[[{"index":0,"gen":0},"Alice"]]"#;
world
    .deserialize::<_, ViewMut<Name>>(&mut serde_json::de::Deserializer::from_str(serialized))
    .unwrap_or_else(|_| panic!());

let alice_eid = EntityId::new_from_index_and_gen(0, 0);
assert_eq!(world.get::<&Name>(alice_eid).unwrap().0, "Alice");

// Careful here, the World is not in a stable state

assert_eq!(world.is_entity_alive(alice_eid), false);

// We can use World::spawn for example to fix the problem
// another solution would be to serialize EntitiesViewMut

world.spawn(alice_eid);

assert_eq!(world.is_entity_alive(alice_eid), true);

Trait Implementations

impl Clone for World

Available on crate feature std only.

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for World

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for World

Available on crate feature std only.

fn default() -> Self

Creates an empty World.