Struct tiny_ecs::Entities

pub struct Entities { /* fields omitted */ }

This is the root of the ECS implementation

Methods

impl Entities

pub fn new(entity_count: Option<usize>, part_count: Option<usize>) -> Entities

Create a new root entity container.

• entity_count will initialize the entity map and new component maps to this size. This is a good thing to do to prevent unnecessary (re)allocations if you know the total active entity count. Entity removals will free up slots which are then reused instead of expanding the map.
• part_count is as above, for total part types/kinds, there is a maximum of either 32 or 64 individual parts you can add of which the index starts at 0 to n-1

pub fn get_free_slot(&mut self) -> Result<usize, &'static str>

Find the first EMPTY ID number to use

As entities are only created by actually inserting new components in to the Entity structure, this should be called to find the first available entity slot. Slot states are determined by the mask it holds.

pub fn get_entity_mask(&self, id: usize) -> u64

Returns the mask of the requested entity enabling you to manually check composition using bitmasks.

pub fn get_type_mask<T: 'static>(&self) -> Result<u64, &'static str>

Returns the mask associated with the requested type.

pub fn entity_contains<T: 'static>(&self, id: usize) -> bool

pub fn add_part<T: 'static>(
    &mut self,
    id: usize,
    part: T
) -> Result<(), ECSError>

Adding a part requires a valid slot along with the initialised data to use with the entity. Effectively creates the entity if the slot is currently empty.

A bitmask is created internally for each data type added (only one per type).

Example

struct Test1 {}
const TEST1: u32 = 1 << 2;

let entity_1 = entities.get_free_slot().unwrap();
assert!(entities.add_part(entity_1, Test1 {}).is_ok());

pub fn rm_part<T: 'static>(&mut self, id: usize) -> Result<(), ECSError>

Remove an entities part. If no components are left after part removal then the entity is considered deleted and an EMPTY (0) mask is inserted in its place.

Removal requires the ID of the entity and the components type signature.

Example

#[derive(Debug, PartialEq)]
struct Test1 {}

assert!(entities.rm_part::<Test1>(entity_1).is_ok());
assert_eq!(entities.get_entity_mask(entity_1), EMPTY);

pub fn borrow<T: 'static>(&self) -> Result<MapRef<T>, ECSError>

Get a plain reference to the selected entity part map

You may have multiple immutable references to the requested ComponentMap type but no mutable references if the same typed ComponentMap is currently referenced.

• Option is whether or not there is a part of <T> for that entity.
• Borrowing (Ref) is checked at runtime.

Example

let components = entities
    .borrow::<Test1>()
    .unwrap();
let part = components.get_part_ref(entity_1).unwrap();

pub fn borrow_mut<T: 'static>(&self) -> Result<MapRefMut<T>, ECSError>

Get a mutable reference to the selected entity part map

You may have only one mutable reference to the requested ComponentMap type and no immutable references. You can however, have multiple mutable references to different types of ComponentMap

• Result covers if the map was able to be borrowed mutably or not.
• Borrowing is checked at runtime.

Example

// Because we later need a ref to the same `Type` of map, the mut ref
// will need to be scoped. If the later ref was of a different type,
// eg: Vector2, then it wouldn't need scoping.
{
    let mut components = entities
        .borrow_mut::<Test1>()
        .unwrap();
    for id in 0..5 {
        if let Ok(part) = components.get_part_mut(id) {
            part.x = 42;
        }
    }
}

// Now get a ref to the modified part
let components = entities.borrow::<Test1>().unwrap();
let part = components.get_part_ref(entity_1).unwrap();
assert_eq!(part.x, 42);

Trait Implementations

impl Default for Entities

fn default() -> Self

Create a new Entities struct with no pre-allocated memory for maps

impl Debug for Entities

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.