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. This is somewhat due to some limitations, and also due to trying to maintain as little overhead as possible - this means no unneccesary copies/clones.

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.

The basis of 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. For the most part, bitmasks are handled for you, and some helper methods are available to hide their use, but there are also methods to get the bitmask for any ID if you are inclined to do some manual management.

Note: defaults to bitmask of u64 size (so 64 components). If you need a smaller mask the feature bitmask_max_32 can be enabled for mask of u32 size.

Attention: borrows of ComponentMap are checked at runtime.

Examples

Init with a capacity

This is good to do if you know the size required as it will prevent many reallocs/moves as data is added. This affects both the entity and component map allocs (they will be equal in length).

use tiny_ecs::Entities;

let mut entities = Entities::new(Some(1000), Some(24));

Demonstrating use

use tiny_ecs::Entities;

// These are the "components" we will use
struct Vector1 {
x: i32,
}
struct Vector2 {
x: i32,
y: i32,
}
struct Vector3 {
x: i32,
y: i32,
z: i32,
}

// Initialize the Entity collection
let mut entities = Entities::new(Some(3), Some(3));

// To create an entity you only need to add the first component using
// a free slot
let entity_1 = entities.get_free_slot().unwrap();
assert!(entities.add_part(entity_1, Vector1 { x: 42 }).is_ok());
// And you can add more components to it
// The entity is only considered newly created if no components existed before
entities.add_part(entity_1,
Vector3 { x: 3,
y: 10,
z: -12 });

// To add another entity you need another free slot
let entity_2 = entities.get_free_slot().unwrap();
assert!(entities.add_part(entity_2, Vector2 { x: 66, y: 6 }).is_ok());
assert!(entities.add_part(entity_2, Vector1 { x: 6 }).is_ok());

Access an entities part of type <T>

# use tiny_ecs::{Entities, ComponentMap};
# struct Vector3 {x: i32, y: i32, z: i32 }
# let mut entities = Entities::new(Some(3), Some(3));
# let entity_1 = entities.get_free_slot().unwrap();
# assert!(entities.add_part(entity_1, Vector3 { x: 3, y: 10, z: -12 }).is_ok());
// To get access to a part belonging to an entity you need
// first to get the component map created for the part type
// You need to 'anchor' this with a let or the ref is
// dropped before you can use it
let mut components = entities
.borrow_mut::<Vector3>()
.unwrap();
// You can then use the part by getting a reference
let mut part = components.get_part_mut(entity_1).unwrap();
assert_eq!(part.z, -12);

Check if Entity contains a part type + remove part

# use tiny_ecs::Entities;
# struct Vector1 {x: i32 }
# let mut entities = Entities::new(Some(3), Some(3));
# let entity_1 = entities.get_free_slot().unwrap();
# assert!(entities.add_part(entity_1, Vector1 { x: 3 }).is_ok());
// You can check if an entity contains a part with the type signature
if entities.entity_contains::<Vector1>(entity_1) {
assert!(entities.rm_part::<Vector1>(entity_1).is_ok());
}
assert_eq!(entities.entity_contains::<Vector1>(entity_1), false);

A system that uses an get_mut()

# use tiny_ecs::{Entities, ComponentMap};
# struct Vector1 {x: i32 }
# let mut entities = Entities::new(Some(3), Some(3));
# let entity_1 = entities.get_free_slot().unwrap();
# assert!(entities.add_part(entity_1, Vector1 { x: 3 }).is_ok());

// Make a system of some form that takes a `ComponentMap<T>` arg
fn some_system(mut components: &mut ComponentMap<Vector1>) {
// You can then iterate over the components directly
for (k, v) in components.get_mut() {
v.x += 1;
assert!(v.x > k as i32);
}
}
# let mut components = entities.borrow_mut::<Vector1>().unwrap();
some_system(&mut components);

Get components for an entity ID list

# use tiny_ecs::{Entities, ComponentMap};
# struct Vector1 {x: i32 }
# let mut entities = Entities::new(Some(3), Some(3));
# let entity_1 = entities.get_free_slot().unwrap();
# assert!(entities.add_part(entity_1, Vector1 { x: 3 }).is_ok());

// A system that fetches the components for only the entities you are require
fn second_system(active: &[usize], mut v1_map: &mut ComponentMap<Vector1>) {
for id in active {
if let Ok(part) = v1_map.get_part_mut(*id) {
part.x = 42;
}
}
}
# let mut components = entities.borrow_mut::<Vector1>().unwrap();
second_system(&[0, 1, 2], &mut components);

A more complex system using ComponentMaps directly

# use tiny_ecs::{Entities, ComponentMap};
# struct Vector1 {x: i32 }
# struct Vector2 {x: i32, y: i32 }
# let mut entities = Entities::new(Some(3), Some(3));
# let entity_1 = entities.get_free_slot().unwrap();
# assert!(entities.add_part(entity_1, Vector1 { x: 3 }).is_ok());
# assert!(entities.add_part(entity_1, Vector2 { x: 3, y: 3 }).is_ok());

// Or a system handles the `Entities` container directly
fn other_system(active_ents: &[usize], entities: &mut Entities) {
// You can mutably borrow multiple part types at once
let mut v1_components = entities
.borrow_mut::<Vector1>()
.unwrap();

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

// But not have a mutable borrow and immutable borrow to the same
// Fails at runtime!
// let v2_components = entities.borrow::<Vector2>().unwrap();
// But you can have multiple immutable references to the same part
for id in active_ents {
if entities.entity_contains::<Vector1>(*id) &&
entities.entity_contains::<Vector2>(*id) {
let v1_part = v1_components.get_part_mut(*id).unwrap();
let v2_part = v2_components.get_part_mut(*id).unwrap();
v1_part.x = 42;
assert_ne!(v1_part.x, 43);
assert_eq!(v1_part.x, 42);
}
}
}
other_system(&[0, 1, 2], &mut entities);