Struct shipyard::World

source · [−]
pub struct World { /* private fields */ }
Expand description

World contains all data this library will manipulate.

Implementations

Creates a new workload and store it in the World.

Creates an empty World.

Creates an empty World with a custom RwLock for AllStorages.

Creates an empty World with a local ThreadPool.

This is useful when you have multiple Worlds or something else using rayon and want them to stay isolated.
For example with a single ThreadPool, a panic would take down all Worlds.
With a ThreadPool per World we can keep the panic confined to a single World.

Creates an empty World with a custom RwLock for AllStorages and a local ThreadPool.

The local ThreadPool is useful when you have multiple Worlds or something else using rayon and want them to stay isolated.
For example with a single ThreadPool, a panic would take down all Worlds.
With a ThreadPool per World we can keep the panic confined to a single World.

Removes the local ThreadPool.

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
Panics
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);
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
Panics
Example
use shipyard::{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);
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
Panics
Example
use shipyard::{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);
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
Panics
Example
use shipyard::{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);

Removes a unique storage.

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

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

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

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

Modifies the current default workload to name.

Borrows
  • Scheduler (exclusive)
Errors
  • Scheduler borrow failed.
  • Workload did not exist.

Changes the name of a workload if it exists.

Borrows
  • Scheduler (exclusive)
Panics
  • Scheduler borrow failed.

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.

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

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.

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.

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.

Inserts a custom storage to the World.

Errors
  • AllStorages is already borrowed exclusively.

Returns a timestamp used to clear tracking information.

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

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

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

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

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

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

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

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

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, 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::<SparseSet<U32>>(entity);

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.

Deletes all entities and components in the World.

Example
use shipyard::World;

let mut world = World::new();

world.clear();

Clear all deletion and removal tracking data.

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

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.

Displays storages memory information.

Returns a list of workloads, their systems and which storages these systems borrow.

Borrows
  • Scheduler (shared)
Panics
  • Scheduler borrow failed.

Trait Implementations

Formats the value using the given formatter. Read more

Creates an empty World.

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more

Instruments this type with the current Span, returning an Instrumented wrapper. Read more

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The alignment of pointer.

The type for initializers.

Initializes a with the given initializer. Read more

Dereferences the given pointer. Read more

Mutably dereferences the given pointer. Read more

Drops the object pointed to by the given pointer. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more