Struct apecs::World

pub struct World { /* private fields */ }

A collection of resources and systems.

The World is the executor of your systems and async computations.

Most applications will create and configure a World in their main function, finally running it or ticking it in a loop.

use apecs::*;

#[derive(CanFetch)]
struct MyAppData {
    channel: Read<chan::mpmc::Channel<String>>,
    count: Write<usize>,
}

let mut world = World::default();
world
    .with_system(
        "compute_hello",
        |mut data: MyAppData| -> anyhow::Result<ShouldContinue> {
            if *data.count >= 3 {
                data.channel
                    .tx
                    .try_broadcast("hello world".to_string())
                    .unwrap();
                end()
            } else {
                *data.count += 1;
                ok()
            }
        },
    )
    .unwrap()
    .with_async_system("await_hello", |mut facade: Facade| async move {
        let mut rx = facade
            .visit(|mut data: MyAppData| Ok(data.channel.new_receiver()))
            .await?;
        if let Ok(msg) = rx.recv().await {
            println!("got message: {}", msg);
        }
        Ok(())
    });
world.run();

World is the outermost object of apecs, as it contains all systems and resources. It contains Entities and Components as default resources. You can create entities, attach components and query them from outside the world if desired:

let mut world = World::default();
// Nearly any type can be used as a component with zero boilerplate
let a = world.entity_with_bundle((123, true, "abc"));
let b = world.entity_with_bundle((42, false));

// Query the world for all matching bundles
let mut query = world.query::<(&mut i32, &bool)>();
for (number, flag) in query.iter_mut() {
    if **flag {
        **number *= 2;
    }
}

// Perform random access within the same query
let a_entry: &Entry<i32> = query.find_one(a.id()).unwrap().0;
assert_eq!(**a_entry, 246);
// Track changes to individual components
assert_eq!(apecs::current_iteration(), a_entry.last_changed());

Where to look next 📚

• Entities for info on creating and deleting Entitys
• Components for info on creating updating and deleting components
• Entry for info on tracking changes to individual components
• Query for info on querying bundles of components
• Facade for info on interacting with the World from within an async system
• Plugin for info on how to bundle systems and resources of common operation together into an easy-to-integrate package

Implementations

impl World

pub fn with_default_resource<T: Default + IsResource>(
    &mut self
) -> Result<&mut Self>

pub fn with_resource<T: IsResource>(&mut self, resource: T) -> Result<&mut Self>

pub fn set_resource<T: IsResource>(&mut self, resource: T) -> Result<Option<T>>

pub fn with_plugin(&mut self, plugin: impl Into<Plugin>) -> Result<&mut Self>

Add a plugin to the world, instantiating any missing resources or systems.

Errs

Errs if the plugin requires resources that cannot be created by default.

pub fn with_data<T: CanFetch>(&mut self) -> Result<&mut Self>

pub fn with_system<T, F>(
    &mut self,
    name: impl AsRef<str>,
    sys_fn: F
) -> Result<&mut Self>where
    F: FnMut(T) -> Result<ShouldContinue> + Send + Sync + 'static,
    T: CanFetch + 'static,

Add a syncronous system.

Errs

Errs if expected resources must first be added to the world.

pub fn with_system_with_dependencies<T, F>(
    &mut self,
    name: impl AsRef<str>,
    sys_fn: F,
    after_deps: &[&str],
    before_deps: &[&str]
) -> Result<&mut Self>where
    F: FnMut(T) -> Result<ShouldContinue> + Send + Sync + 'static,
    T: CanFetch + 'static,

Add a syncronous system that has a dependency on one or more other syncronous systems.

Errs

Errs if expected resources must first be added to the world.

pub fn with_system_barrier(&mut self) -> &mut Self

Add a syncronous system barrier.

Any systems added after the barrier will be scheduled after the systems added before the barrier.

pub fn with_parallelism(&mut self, parallelism: Parallelism) -> &mut Self

pub fn with_async_system<F, Fut>(
    &mut self,
    name: impl AsRef<str>,
    make_system_future: F
) -> &mut Selfwhere
    F: FnOnce(Facade) -> Fut,
    Fut: Future<Output = Result<()>> + Send + Sync + 'static,

pub fn with_async(
    &mut self,
    future: impl Future<Output = ()> + Send + Sync + 'static
) -> &mut Self

pub fn has_resource<T: IsResource>(&self) -> bool

Returns whether a resources of the given type exists in the world.

pub fn spawn(&self, future: impl Future<Output = ()> + Send + Sync + 'static)

Spawn an asynchronous task.

pub fn tick(&mut self)

Conduct a world tick.

Calls World::tick_async, then World::tick_sync, then World::tick_lazy.

Panics

Panics if any sub-tick step returns an error

pub fn tick_sync(&mut self) -> Result<()>

Just tick the synchronous systems.

pub fn tick_async(&mut self) -> Result<()>

Just tick the async futures, including sending resources to async systems.

pub fn tick_lazy(&mut self) -> Result<()>

Applies lazy world updates.

Also runs component entity and archetype upkeep.

pub fn run(&mut self) -> &mut Self

Run all systems and futures until they have finished or one system has erred, whichever comes first.

pub fn resource<T: IsResource>(&self) -> Result<&T>

Attempt to get a reference to one resource.

pub fn resource_mut<T: IsResource>(&mut self) -> Result<&mut T>

Attempt to get a mutable reference to one resource.

pub fn fetch<T: CanFetch>(&mut self) -> Result<T>

pub fn entity(&mut self) -> Entity

Create a new entity.

pub fn entity_with_bundle<B: IsBundle>(&mut self, bundle: B) -> Entity

Create a new entity and immediately attach the bundle of components to it.

pub fn query<Q: IsQuery + 'static>(&mut self) -> QueryGuard<'_, Q>

pub fn insert_component<T: Send + Sync + 'static>(
    &mut self,
    id: usize,
    component: T
) -> Option<T>

pub fn insert_bundle<B: IsBundle>(&mut self, id: usize, bundle: B)

pub fn get_component<T: Send + Sync + 'static>(
    &self,
    id: usize
) -> Option<impl Deref<Target = T> + '_>

pub fn get_schedule_description(&self) -> String

pub fn get_sync_schedule_names(&self) -> Vec<Vec<&str>>

Returns the scheduled systems’ names, collated by batch.

Trait Implementations

impl Default for World

fn default() -> Self

Returns the “default value” for a type.