Struct Entities

pub struct Entities { /* private fields */ }

This is the root of the ECS implementation

Implementations

impl Entities

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

Create a new root entity container.

• entity_count will initialize the entity map to this size. Good to do if you know the max count of entities you will handle
• component_count is as above, for total unique component types/kinds

For component_count there is a maximum of either 32, 64, or 128 individual parts you can add of which the index starts at 0 to n-1, depending on which is enabled by the crate features

pub fn new_entity(&mut self) -> &mut Self

Start the creation of a new entity

If no parts are added to this call with with() then the entity will not be created.

pub fn with<T: 'static>(&mut self, part: T) -> Result<&mut Self, ECSError>

Chained with new_entity() to add components

with() can be chained multiple times to add many components.

Example

struct Component1 {}
struct Component2 {}

let entity_1 = entities
                .new_entity()
                .with(Component1 {})?
                .with(Component2 {})?
                .finalise()?;
assert_eq!(entity_1, 0);

pub fn finalise(&mut self) -> Result<usize, ECSError>

Optional final call in creating an entity - returns ID. You can begin using the entity without calling this, but it is recommended that you do to prevent workplace accidents.

If you don’t finalise an entity you can keep adding components to it later. This isn’t recommended though as it’s easy to lose track of which entity you are working on. The add_component() method allows you to add extra components to an existing entity if you know the ID.

pub fn entity_exists(&self, id: usize) -> bool

Check if an entity ID is valid (alive and has components)

If false then there are no components attached to this ID and the entity is None.

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

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

👎Deprecated

pub fn rm_component_from<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

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

Example

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

assert!(entities.rm_component_from::<Test1>(entity_1).is_ok());
assert!(!entities.entity_contains::<Test1>(entity_1));

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

👎Deprecated

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

Add a component to the existing Entity ID

Example

struct Test1 {}
struct Test2 {}
struct Test3 {}

let mut entities = Entities::new(Some(3), Some(3));
let entity_1 = entities
    .new_entity()
    .with(Test1 {})?
    .with(Test2 {})?
    .finalise()?;
entities.add_component_to(entity_1, Test3 {});
assert!(entities.entity_contains::<Test1>(entity_1));

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

Get a plain reference to the selected entity part map. Borrow rules are checked at runtime.

You may have multiple immutable references to the requested Persist type but no mutable references if the same typed Persist 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(entity_1).unwrap();

pub unsafe fn borrow_unchecked<T: 'static>( &self, ) -> Result<&Persist<T>, ECSError>

Allows you to borrow without runtime check overhead or to borrow when the standard borrow rules prevent you from doing so and you enforce safety

Safety

Borrows are not checked at compile-time or runtime. An unchecked borrow on a mutably borrowed Persist is UB.

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

Get a mutable reference to the selected entity part map. Borrow rules are checked at runtime.

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

• 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>()?;
    for id in 0..5 {
        if let Some(part) = components.get_mut(id) {
            part.x = 42;
        }
    }
}

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

pub unsafe fn borrow_mut_unchecked<T: 'static>( &self, ) -> Result<&mut Persist<T>, ECSError>

Allows you to borrow mutably without runtime check overhead or to borrow when the standard borrow rules prevent you from doing so and you enforce safety

Safety

Borrows are not checked at compile-time or runtime. An unchecked mutable on an immutably borrowed Persist is UB.

Trait Implementations

impl Debug for Entities

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

Formats the value using the given formatter.

impl Default for Entities

fn default() -> Self

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