Crate xecs

XECS

An Entity-Component-System library

Simple Example

// Define two components struct
// Component is Send + Sync + 'static
#[derive(Debug,Copy)]
struct Position{
    x : f32,
    y : f32
};
struct Hidden;

// create an empty world
let mut world = World::new();

// generate 10 entities
for _ in 0..10 {
    let x = random();
    lety = random();
    // andomly generate the positions
    world.create_entity()
        .attach(Position { x,y });
}
 
// print all postions
for pos in world.query::<&Position>() {
    print!("{:?}",pos)
}

// filter some entities need to be hidden
let ids = world.query::<&Position>()
    .with_id()
    .filter(|(_,_)|random())
    .map(|(id,_)|id)
    .collect::<Vec<_>>();
 
// attach hidden to id
for id in ids {
    world.attach_component(id,Hidden);
}

// make a full-owning group to accelerate the query
world.make_group(full_owning::<Hidden,Position>());

// only print postions with id that is not hidden
for (id,data) in world.query::<&Position,Without<&Hidden>>() {
    print!("{}:{:?}",id,data);
}

About entity

Entity in XECS is just an number ID.In XECS, it’s just a NonZeroUsize. The ID is allocated from 1 by world automatically. The id=0 represents a recycled ID without any other flags through Option<EntityId>.

ID recycling

When you call world.create_entity(), an ID will be allocated automatically. If you call world.remove_entity(id), this ID will be a pit. If the next world.create_entity() is called, it will allocate this ID to fill the pit.Thanks to sparse set, it’s still fast to iterate all components no matter how random of ID

Concurrency Safety

Because Component is just T : Send + Sync. World can use RwLock to ensure the borrow check relations of all components.And World can also be Send + Sync.Therefore,the all other states of world can be guarded by RwLock.So we can use world in concurrency environment by RwLock<World>.

System in XECS

System is a Stream with World as Context. Because Stream is not stable in std, XECS use futures::Stream instead.

To Run System

Because system is just an async trait, you need a wrapper of runtime from tokio or async-std

Modules

group

Some things to accelerate the iteration

query

The query functions

Structs

ComponentRead

A read gurad for component

ComponentWrite

A write guard for component

Entities

A useful struct for building a lot of entities

Entity

A useful struct for building a entity

ResourceRead

A read lock gurad for resource

ResourceWrite

A write lock gurad for resource

StorageRead

A read gurad for component storage

StorageWrite

A write gurad for component storage

World

The resource type World is the core of XECS.It manages all components and entities

Traits

Component

The Component trait

ComponentStorage

A trait to make sparse set dynamic

Resource

The resource trait

System

System core trait

Type Aliases

EntityId

The type of ID of entity which starts from 1 and can be recycled automatically