Crate constellation 

Constellation ECS

A data-oriented entity component system optimized for cache coherent resource access and parallel system execution.

Constellation does not have any native understanding of a “component”. Instead, the library is concerned about ensuring safe concurrent access to shared resources, while providing direct access to each resource’s own APIs. These resources may store per-entity data such as positions, or may represent application wide services such as asset loaders or input devices.

Systems request read or write access to a set of resources, which can then be scheduled to be potentially executed in parallel by recording them into a SystemCommandBuffer and executing the command buffer within a World.

Examples

Defining Resources:

// Per-entity position data.
struct Position {
    x: f32,
    y: f32,
    z: f32
}

// Store position data into a vector resource
type Positions = VecResource<Position>;

// Per-entity debug names.
struct DebugName {
    name: String
}

// Store debug names in a map resource
type DebugNames = MapResource<DebugName>;

let mut world = World::new();
world.register_resource(Positions::new());
world.register_resource(DebugNames::new());

Update the world with Systems:

let mut update = SystemCommandBuffer::default();
update.queue_systems(|scope| {
    scope.run_r1w1(|ctx, velocities: &Velocities, positions: &mut Positions| {
        println!("Updating positions");

        // iterate through all components for entities with data in both
        // position and velocity resources
        ctx.iter_r1w1(velocities, positions).components(|entity, v, p| {
            p.x += v.x;
            p.y += v.y;
            p.z += v.z;
        });
    });

    scope.run_r2w0(|ctx, names: &DebugNames, positions: &Positions| {
        println!("Printing positions");

        // iterate through all entity IDs for entities with data in both
        // `names` and `positions`
        ctx.iter_r2w0(names, positions).entities(|entity_iter, n, p| {
            // `n` and `p` allow (potentially mutable) access to entity data inside
            // the resource without the ability to add or remove entities from the resource
            // - which would otherwise invalidate the iterator
            for e in entity_iter {
                println!("Entity {} is at {:?}",
                         n.get(e).unwrap().name,
                         p.get(e).unwrap());
            }
        });
    });
});

world.run(&mut update);

Parallel System Execution

Systems queued into a command buffer within a single call to queue_systems may be executed in parallel by the world.

The order in which systems are queued is significant in one way: the scheduler guarantees that any changes to resources will always be observed in the same order in which systems were queued.

For example, given two systems - ReadPositions and WritePositions - if WritePositions was queued before ReadPositions, then it is guarenteed that ReadPositions will see any changes made by WritePositions. Conversely, if the order were to be swapped, then ReadPositions is guaranteed to not observe the changes made by WritePositions.

There is one exception to this. Entity deletions are committed when all concurrently executing systems have completed. This behavior is deterministic, but not always obvious. If you wish to ensure that entity deletions from one system are always seen by a later system, then queue the two systems in separate queue_systems calls.

Modules

bitset

join

Structs

Entities

Manages the allocation and delection of Entity IDs.

EntitiesTransaction

An entity transaction allows concurrent creations and deletions of entities from an Entities.

Entity

A handle onto an entity in a scene.

EntityChangeSet

Summarises the final changes made during the lifetime of an entity transaction.

EntityIter

An iterator which converts indexes into entitiy IDs.

EntityIteratorBuilder

Provides methods for efficiently iterating through entity resources.

MapResource

A MapResource stores per-entity data in a HashMap.

MapStorage

Provides methods to retrieve and mutate entity data stored inside a MapResource.

ResourceBuilder

Constructs and configures a world resource.

SystemCommandBuffer

Records system executions, to be run later within a World.

SystemContext

Contains system execution state information.

SystemScope

Systems queued within a SystemScope may be scheduled to run in parallel.

VecResource

A VecResource stores per-entity data in a Vec.

VecStorage

Provides methods to retrieve and mutate entity data stored inside a VecResource.

VecStorageIter

An iterator over entity data stored in a VecResource.

VecStorageIterMut

An iterator over entity data stored in a VecResource.

World

Stores entities are resources, and provides mechanisms to update the world state via systems.

Enums

SequentialExecute

Determines the behavior entity transaction commits when running a system command buffer sequentially.

Traits

ComponentResourceApi

A component resource is a resource which stores data related to entities in the form of a single Self::Component per entity.

EntityResource

An entity resource is a resource which stores data about entities.

Handle

A handle is formed out of an Index and a Generation

Resource

A resource whos system access is controlled by the World.

Type Aliases

Generation

Generation is incremented each time an index is re-used.

Index

Only one entity with a given index may be alive at a time.