Crate xecs

source · []
Expand description


An Entity-Component-System library

Simple Example

// Define two components struct
// Component is Send + Sync + 'static
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
        .attach(Position { x,y });
// print all postions
for pos in world.query::<&Position>() {

// filter some entities need to be hidden
let ids = world.query::<&Position>()
// attach hidden to id
for id in ids {

// make a full-owning group to accelerate the query

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

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


Some things to accelerate the iteration

The query functions


A read gurad for component

A write guard for component

A useful struct for building a lot of entities

A useful struct for building a entity

A read lock gurad for resource

A write lock gurad for resource

A read gurad for component storage

A write gurad for component storage

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


The Component trait

A trait to make sparse set dynamic

The resource trait

System core trait

Type Definitions

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