Struct rs_ecs::World

pub struct World { /* private fields */ }

The world storing entities and their components.

Implementations

impl World

pub fn new() -> Self

Create an empty world.

impl World

pub fn alloc(&mut self) -> Entity

Create an Entity without any components. To add components, see Self::insert().

Example

let mut world = World::new();

let entity = world.alloc();
world.insert(entity, (42_u32, true));

pub fn free(&mut self, ent: Entity)

Remove an Entity and all its components from the world. To remove components, see Self::remove().

Example

let mut world = World::new();

let entity = world.alloc();
world.insert(entity, (42_u32, true));

world.free(entity);

pub fn clear(&mut self)

Remove all entites and their components from the world.

Note that this will re-use the memory allocations but it will drop the meta-data which implies that previously used Entity values will be repeated.

impl World

pub fn insert<B>(&mut self, ent: Entity, comps: B)

where B: Bundle,

Insert components for a given Entity.

If a component is already present for the entity, its value will be overwritten.

Example

let mut world = World::new();

let entity = world.alloc();
world.insert(entity, (42_u32, true));
world.insert(entity, (String::from("Hello"),));

pub fn remove<B>(&mut self, ent: Entity) -> Option<B>

where B: Bundle,

Remove components for a given Entity.

Example

let mut world = World::new();

let entity = world.alloc();
world.insert(entity, (42_u32, true, String::from("Hello")));

world.remove::<(u32, bool)>(entity).unwrap();
world.remove::<(String,)>(entity).unwrap();

pub fn exchange<B1, B2>(&mut self, ent: Entity, new_comps: B2) -> Option<B1>

where B1: Bundle, B2: Bundle,

Exchange components for a given Entity

Example

let mut world = World::new();

let entity = world.alloc();
world.insert(entity, (42_u32, true));
assert!(world.contains::<u32>(entity));
assert!(world.contains::<bool>(entity));
assert!(!world.contains::<String>(entity));

world.exchange::<(u32, bool), _>(entity, (String::from("Hello"),)).unwrap();
assert!(!world.contains::<u32>(entity));
assert!(!world.contains::<bool>(entity));
assert!(world.contains::<String>(entity));

impl World

pub fn transfer(&mut self, ent: Entity, other: &mut World) -> Entity

Transfer an Entity and its components from this world to another.

Example

let mut world = World::new();

let entity = world.alloc();
world.insert(entity, (23_i32, false, String::from("Goodbye")));

let mut another_world = World::new();
let entity = world.transfer(entity, &mut another_world);

let comp = another_world.query_one::<&String>(entity).unwrap();
assert_eq!(&*comp.get(), "Goodbye");

impl World

pub fn exists(&self, ent: Entity) -> bool

Check if a given Entity exists.

Example

let mut world = World::new();

let entity = world.alloc();
assert!(world.exists(entity));

world.free(entity);
assert!(!world.exists(entity));

pub fn contains<C>(&self, ent: Entity) -> bool

where C: 'static,

Check if a certain component type is present for an Entity.

Example

let mut world = World::new();

let entity = world.alloc();
world.insert(entity, (42_u32, true));

assert!(world.contains::<u32>(entity));

pub fn query_one<S>(&self, ent: Entity) -> Option<QueryOne<'_, S>>

where S: QuerySpec,

Access the components matching given query for an Entity.

Note that for repeated calls, map can be used to amortize the set-up costs.

Example

let mut world = World::new();

let entity = world.alloc();
world.insert(entity, (42_u32, true));

{
    let mut comp = world.query_one::<&mut u32>(entity).unwrap();
    *comp.get_mut() = 42;
}

let comp = world.query_one::<&u32>(entity).unwrap();
assert_eq!(*comp.get(), 42);

impl World

pub fn clone(&mut self, cloner: &Cloner) -> Self

Creates a copy of the World

This requires that all component types are available in the given cloner.

Example

let mut world = World::new();

let ent = world.alloc();
world.insert(ent, (42, "foo".to_owned(),));

let mut cloner = Cloner::new();

cloner.add_copyable::<i32>();
cloner.add_cloneable::<String>();

let snapshot = world.clone(&cloner);

let mut comp = world.query_one::<&mut String>(ent).unwrap();
*comp.get_mut() = "bar".to_owned();

let comp = snapshot.query_one::<&String>(ent).unwrap();
assert_eq!(*comp.get(), "foo");

Trait Implementations

impl Default for World

fn default() -> Self

Create an empty world.