#ecs #entity #component #system #tiny

tiny_ecs

A tiny ECS that tries to avoid unnecessary copy/clones

30 releases (8 breaking)

✓ Uses Rust 2018 edition

0.19.4 Oct 5, 2019
0.19.0 Aug 11, 2019
0.18.1 Jul 21, 2019

#91 in Data structures

Download history 264/week @ 2019-06-22 63/week @ 2019-06-29 125/week @ 2019-07-06 25/week @ 2019-07-13 96/week @ 2019-07-20 31/week @ 2019-07-27 135/week @ 2019-08-03 58/week @ 2019-08-10 98/week @ 2019-08-17 81/week @ 2019-08-24 108/week @ 2019-08-31 80/week @ 2019-09-07 67/week @ 2019-09-14 352/week @ 2019-09-21 79/week @ 2019-09-28

422 downloads per month

MPL-2.0 license

30KB
328 lines

Build Status

Tiny ECS

Documentation

Description

Tiny ECS

The intention of this crate is that a basic ECS is provided, where you will be required to exercise a little additional control.

Where most other ECS crates provide a mechanism for inserting "systems" in to the ECS to run against entities, this one leaves it out - you can think of it as a "system for entity/components". You will need to create external systems; these can be a function, a loop, or anything else.

Internally this ECS is the use of bitmasks. Each entity ID is in practice an internal index number in to an array which contains bitmasks. The bitmasks themselves keep track of what components the entity has.

Note: borrows of ComponentMap are checked at runtime.

Benchmarks

Based on the ecs_bench project.

Running target/release/deps/pos_vel-ae14aca3c44438c0
Pos/Vel build                   time:   [217.56 us 218.52 us 219.65 us]
Found 9 outliers among 100 measurements (9.00%)
  9 (9.00%) high mild

Pos/Vel update/safe
                        time:   [5.9081 us 5.9175 us 5.9280 us]
Found 6 outliers among 100 measurements (6.00%)
  3 (3.00%) high mild
  3 (3.00%) high severe
Pos/Vel update/unsafe
                        time:   [5.9153 us 5.9242 us 5.9349 us]
Found 9 outliers among 100 measurements (9.00%)
  1 (1.00%) high mild
  8 (8.00%) high severe

Usage

Cargo.toml

[dependencies]
tiny_ecs = "0.19.1"

Creation and Adding Entities

// Create new container
let entities = Entities::new();

// The builder pattern is powerful
let ent = world .entities
                .new_entity()
                .with(ParticleID { id })?
                .with(Sprite::new(sprite_id, rec))?
                .with(InputTypes::Player(binds))?
                .with(Player::new(5.0, 15.0))?
                .finalise()?;

Systems

// Example system
fn example_system(active_ents: &[usize], entities: &mut Entities) -> Result<(), ECSError> {
    // You can mutably borrow multiple component maps at once
    let mut v1_components = entities
        .borrow_mut::<Vector1>()?;

    let mut v2_components = entities
        .borrow_mut::<Vector2>()?;

    // But not have a mutable borrow and immutable borrow to the same map
    // Fails at runtime!
    // let v2_components = entities.borrow::<Vector2>().unwrap();
    for id in active_ents {
        if entities.entity_contains::<Vector1>(*id) &&
           entities.entity_contains::<Vector2>(*id) {
            let v1_part = v1_components.get_mut(*id)?;
            let v2_part = v2_components.get_mut(*id)?;
            v1_part.x = 42;
            assert_ne!(v1_part.x, 43);
            assert_eq!(v1_part.x, 42);
        }
    }
    Ok(())
}

Please see docs for further examples and help.

License

MPL v2

Dependencies

~425KB