Struct shipyard::World

pub struct World { /* fields omitted */ }

Holds all components and keeps track of entities and what they own.

Implementations

impl World

pub fn new() -> Self

Create an empty World.

pub fn new_with_custom_threads<F: FnMut(ThreadBuilder) -> Result<(), Error>>(
    f: F
) -> Self

Returns a new World with custom threads.
Custom threads can be useful when working with wasm for example.

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

Adds a new unique storage, unique storages store exactly one T at any time.
To access a unique storage value, use Unique.
Does nothing if the storage already exists.
Unwraps errors.

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

Adds a new unique storage, unique storages store exactly one T at any time.
To access a unique storage value, use Unique.
Does nothing if the storage already exists.

pub fn try_borrow<'s, C: SystemData<'s>>(
    &'s self
) -> Result<<C as SystemData<'s>>::View, GetStorage>

Borrows the requested storage(s), if it doesn’t exist it’ll get created.
You can use a tuple to get multiple storages at once.

You can use:

• &T for a shared access to T storage
• &mut T for an exclusive access to T storage
• Entities for a shared access to the entity storage
• EntitiesMut for an exclusive reference to the entity storage
• AllStorages for an exclusive access to the storage of all components
• Unique<&T> for a shared access to a T unique storage
• Unique<&mut T> for an exclusive access to a T unique storage
• ThreadPool for a shared access to the ThreadPool used by the World
• NonSend: must activate the non_send feature
• NonSync: must activate the non_sync feature
• NonSendSync: must activate the non_send and non_sync features

Example

let world = World::new();
let u32s = world.borrow::<&u32>();
let (entities, mut usizes) = world.try_borrow::<(Entities, &mut usize)>().unwrap();

pub fn borrow<'s, C: SystemData<'s>>(&'s self) -> <C as SystemData<'s>>::View

Borrows the requested storage(s), if it doesn’t exist it’ll get created.
You can use a tuple to get multiple storages at once.
Unwraps errors.

You can use:

• &T for a shared access to T storage
• &mut T for an exclusive access to T storage
• Entities for a shared access to the entity storage
• EntitiesMut for an exclusive reference to the entity storage
• AllStorages for an exclusive access to the storage of all components
• Unique<&T> for a shared access to a T unique storage
• Unique<&mut T> for an exclusive access to a T unique storage
• ThreadPool for a shared access to the ThreadPool used by the World
• NonSend: must activate the non_send feature
• NonSync: must activate the non_sync feature
• NonSendSync: must activate the non_send and non_sync features

Example

let world = World::new();
let u32s = world.borrow::<&u32>();
let (entities, mut usizes) = world.borrow::<(Entities, &mut usize)>();

pub fn run<'a, T: Run<'a>, R, F: FnOnce(T::Storage) -> R>(&'a self, f: F) -> R

Borrows the requested storages and runs f, this is an unnamed system.
You can use a tuple to get multiple storages at once.
Unwraps errors.

You can use:

• &T for a shared access to T storage
• &mut T for an exclusive access to T storage
• Entities for a shared access to the entity storage
• EntitiesMut for an exclusive reference to the entity storage
• AllStorages for an exclusive access to the storage of all components
• Unique<&T> for a shared access to a T unique storage
• Unique<&mut T> for an exclusive access to a T unique storage
• ThreadPool for a shared access to the ThreadPool used by the World
• NonSend: must activate the non_send feature
• NonSync: must activate the non_sync feature
• NonSendSync: must activate the non_send and non_sync features

Example

let world = World::new();
world.run::<(&usize, &mut u32), _, _>(|(usizes, u32s)| {
    // -- snip --
});

pub fn try_run<'a, T: Run<'a>, R, F: FnOnce(T::Storage) -> R>(
    &'a self,
    f: F
) -> Result<R, GetStorage>

Borrows the requested storages and runs f, this is an unnamed system.
You can use a tuple to get multiple storages at once.

You can use:

• &T for a shared access to T storage
• &mut T for an exclusive access to T storage
• Entities for a shared access to the entity storage
• EntitiesMut for an exclusive reference to the entity storage
• AllStorages for an exclusive access to the storage of all components
• Unique<&T> for a shared access to a T unique storage
• Unique<&mut T> for an exclusive access to a T unique storage
• ThreadPool for a shared access to the ThreadPool used by the World
• NonSend: must activate the non_send feature
• NonSync: must activate the non_sync feature
• NonSendSync: must activate the non_send and non_sync features

Example

let world = World::new();
world.try_run::<(&usize, &mut u32), _, _>(|(usizes, u32s)| {
    // -- snip --
}).unwrap();

pub fn try_run_system<S: for<'a> System<'a> + 'static>(
    &self
) -> Result<(), GetStorage>

Runs the S system immediately, borrowing the storages necessary to do so.

Example

struct Clock(u32);

#[system(Tick)]
fn run(mut clocks: &mut Clock) {
    (&mut clocks).iter().for_each(|clock| {
        clock.0 += 1;
    });
}

let world = World::default();
world.try_run_system::<Tick>().unwrap();

pub fn run_system<S: for<'a> System<'a> + 'static>(&self)

Runs the S system immediately, borrowing the storages necessary to do so.
Unwraps errors.

Example

struct Clock(u32);

#[system(Tick)]
fn run(mut clocks: &mut Clock) {
    (&mut clocks).iter().for_each(|clock| {
        clock.0 += 1;
    });
}

let world = World::default();
world.run_system::<Tick>();

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

Modifies the current default workload to name.

pub fn set_default_workload(&self, name: impl Into<Cow<'static, str>>)

Modifies the current default workload to name.
Unwraps errors.

pub fn try_add_workload<S: IntoWorkload, N: Into<Cow<'static, str>>>(
    &self,
    name: N
) -> Result<(), Borrow>

A workload is a collection of systems. They will execute as much in parallel as possible.
They are evaluated left to right when they can’t be parallelized.
The default workload will automatically be set to the first workload added.

Example

struct Adder;
impl<'a> System<'a> for Adder {
    type Data = (&'a mut usize, &'a u32);
    fn run((mut usizes, u32s): <Self::Data as SystemData>::View) {
        (&mut usizes, &u32s).iter().for_each(|(x, &y)| {
            *x += y as usize;
        });
    }
}

struct Checker;
impl<'a> System<'a> for Checker {
    type Data = &'a usize;
    fn run(usizes: <Self::Data as SystemData>::View) {
        let mut iter = usizes.iter();
        assert_eq!(iter.next(), Some(&1));
        assert_eq!(iter.next(), Some(&5));
        assert_eq!(iter.next(), Some(&9));
    }
}

let world = World::new();

world.run::<(EntitiesMut, &mut usize, &mut u32), _, _>(|(mut entities, mut usizes, mut u32s)| {
    entities.add_entity((&mut usizes, &mut u32s), (0, 1));
    entities.add_entity((&mut usizes, &mut u32s), (2, 3));
    entities.add_entity((&mut usizes, &mut u32s), (4, 5));
});

world.try_add_workload::<(Adder, Checker), _>("Add & Check").unwrap();
world.run_default();

pub fn add_workload<S: IntoWorkload, N: Into<Cow<'static, str>>>(&self, name: N)

A workload is a collection of systems. They will execute as much in parallel as possible.
They are evaluated left to right when they can’t be parallelized.
The default workload will automatically be set to the first workload added.
Unwraps errors.

Example

struct Adder;
impl<'a> System<'a> for Adder {
    type Data = (&'a mut usize, &'a u32);
    fn run((mut usizes, u32s): <Self::Data as SystemData>::View) {
        (&mut usizes, &u32s).iter().for_each(|(x, &y)| {
            *x += y as usize;
        });
    }
}

struct Checker;
impl<'a> System<'a> for Checker {
    type Data = &'a usize;
    fn run(usizes: <Self::Data as SystemData>::View) {
        let mut iter = usizes.iter();
        assert_eq!(iter.next(), Some(&1));
        assert_eq!(iter.next(), Some(&5));
        assert_eq!(iter.next(), Some(&9));
    }
}

let world = World::new();

world.run::<(EntitiesMut, &mut usize, &mut u32), _, _>(|(mut entities, mut usizes, mut u32s)| {
    entities.add_entity((&mut usizes, &mut u32s), (0, 1));
    entities.add_entity((&mut usizes, &mut u32s), (2, 3));
    entities.add_entity((&mut usizes, &mut u32s), (4, 5));
});

world.add_workload::<(Adder, Checker), _>("Add & Check");
world.run_default();

pub fn try_run_workload(&self, name: impl AsRef<str>) -> Result<(), RunWorkload>

Runs the name workload.

pub fn run_workload(&self, name: impl AsRef<str>)

Runs the name workload.
Unwraps error.

pub fn try_run_default(&self) -> Result<(), Borrow>

Run the default workload.

pub fn run_default(&self)

Run the default workload.
Unwraps error.

Trait Implementations

impl Default for World

fn default() -> Self

Create an empty World.